# CLI Usage

इंस्टॉल करके `inference-cli` आपको एक्सेस मिलता है `inference rf-cloud` कमांड का, जो आपको Batch Processing और Data Staging के साथ इंटरैक्ट करने की अनुमति देता है — Roboflow Batch Processing के मुख्य घटक।

## सेटअप

```bash
pip install inference-cli
export ROBOFLOW_API_KEY="YOUR-API-KEY-GOES-HERE"
```

cloud storage सपोर्ट के लिए:

```bash
pip install 'inference-cli[cloud-storage]'
```

यदि आपको अपना API key ढूंढने में मदद चाहिए, तो हमारा देखें [authentication guide](https://docs.roboflow.com/api-reference/authentication).

## डेटा इनजेस्ट करें

### Images

```bash
inference rf-cloud data-staging create-batch-of-images \
  --images-dir <your-images-dir-path> \
  --batch-id <your-batch-id>
```

### Videos

```bash
inference rf-cloud data-staging create-batch-of-videos \
  --videos-dir <your-videos-dir-path> \
  --batch-id <your-batch-id>
```

{% hint style="info" %}
**Batch ID format:** लोअरकेस होना चाहिए, अधिकतम 64 अक्षर, और केवल letters, digits, hyphens (`-`), और underscores (`_`).
{% endhint %}

### Cloud Storage

यदि आपका डेटा पहले से cloud storage (S3, Google Cloud Storage, या Azure) में है, तो आप उसे लोकली files डाउनलोड किए बिना सीधे प्रोसेस कर सकते हैं।

**Images के लिए:**

```bash
inference rf-cloud data-staging create-batch-of-images \
  --data-source cloud-storage \
  --bucket-path <cloud-path> \
  --batch-id <your-batch-id>
```

**Videos के लिए:**

```bash
inference rf-cloud data-staging create-batch-of-videos \
  --data-source cloud-storage \
  --bucket-path <cloud-path> \
  --batch-id <your-batch-id>
```

The `--bucket-path` parameter supports:

* **S3**: `s3://bucket-name/path/`
* **Google Cloud Storage**: `gs://bucket-name/path/`
* **Azure Blob Storage**: `az://container-name/path/`

आप files को filter करने के लिए glob patterns शामिल कर सकते हैं:

* `s3://my-bucket/training-data/**/*.jpg` — सभी JPG files recursively
* `gs://my-bucket/videos/2024-*/*.mp4` — 2024-\* folders में MP4 files
* `az://container/images/*.png` — images folder में PNG files

{% hint style="info" %}
आपकी cloud storage credentials का उपयोग किया जाता है **केवल लोकली** CLI द्वारा presigned URLs बनाने के लिए। इन्हें **कभी भी upload नहीं किया जाता** Roboflow servers पर।
{% endhint %}

{% hint style="warning" %}
Generated presigned URLs 24 घंटे तक वैध रहते हैं। सुनिश्चित करें कि आपका batch processing job इस समयसीमा के भीतर पूरा हो जाए।
{% endhint %}

बड़े datasets के लिए, सिस्टम स्वचालित रूप से images को 20,000 files के chunks में split करता है। Videos 1,000 से कम के batches में सबसे अच्छे काम करते हैं।

### Signed URL Ingestion

Advanced automation के लिए, आप local files के बजाय signed URLs के माध्यम से data ingest कर सकते हैं:

* `--data-source references-file` — signed URLs के माध्यम से संदर्भित files को process करें।
* `--references <path_or_url>` — एक JSONL file का path जिसमें file URLs हों, या ऐसी file की ओर pointing करने वाला signed URL।

**Reference File Format (JSONL):**

```
{"name": "<unique-file-name-1>", "url": "https://<signed-url>"}
{"name": "<unique-file-name-2>", "url": "https://<signed-url>"}
```

{% hint style="info" %}
Signed URL ingestion Growth Plan और Enterprise ग्राहकों के लिए उपलब्ध है।
{% endhint %}

## Staged Data Inspect करें

```bash
inference rf-cloud data-staging show-batch-details --batch-id <your-batch-id>
```

## Job शुरू करें

### Images Process करें

```bash
inference rf-cloud batch-processing process-images-with-workflow \
  --workflow-id <workflow-id> \
  --batch-id <batch-id> \
  --machine-type gpu
```

### Videos Process करें

```bash
inference rf-cloud batch-processing process-videos-with-workflow \
  --workflow-id <workflow-id> \
  --batch-id <batch-id> \
  --machine-type gpu \
  --max-video-fps <your-desired-fps>
```

{% hint style="info" %}
**अपना Workflow ID कैसे ढूंढें:** Roboflow App में Workflow Editor खोलें, "Deploy" पर क्लिक करें, और code snippet में identifier ढूंढें।
{% endhint %}

{% hint style="info" %}
By default, processing CPU पर चलता है। `--machine-type gpu` को multiple या बड़े models वाले Workflows के लिए उपयोग करें।
{% endhint %}

## Job Progress मॉनिटर करें

start command एक **Job ID**आउटपुट करता है। इसका उपयोग status जांचने के लिए करें:

```bash
inference rf-cloud batch-processing show-job-details --job-id <your-job-id>
```

## Results Export करें

job details में **output batch ID**शामिल होगा। इसका उपयोग results export करने के लिए करें:

```bash
inference rf-cloud data-staging export-batch \
  --target-dir <dir-to-export-result> \
  --batch-id <output-batch-of-a-job>
```

## Webhook Automation

status के लिए polling करने के बजाय, ingestion या processing पूरा होने पर notification पाने के लिए आप webhooks का उपयोग कर सकते हैं।

### Data Ingestion Webhooks

CLI commands `create-batch-of-images` और `create-batch-of-videos` support करते हैं:

* `--notifications-url <webhook_url>` — notifications के लिए webhook endpoint।
* `--notification-category <value>` — notifications फ़िल्टर करें:
  * `ingest-status` (default) — कुल ingestion process status.
  * `files-status` — individual file processing status.

Notifications HTTP POST के माध्यम से एक `Authorization` header के साथ deliver की जाती हैं, जिसमें आपका Roboflow Publishable Key होता है।

#### Ingest Status Notification

```json
{
    "type": "roboflow-data-staging-notification-v1",
    "event_id": "8c20f970-fe10-41e1-9ef2-e057c63c07ff",
    "ingest_id": "8cd48813430f2be70b492db67e07cc86",
    "batch_id": "test-batch-117",
    "shard_id": null,
    "notification": {
        "type": "ingest-status-notification-v1",
        "success": false,
        "error_details": {
            "type": "unsafe-url-detected",
            "reason": "Untrusted domain found: https://example.com/image.png"
        }
    },
    "delivery_attempt": 1
}
```

#### File Status Notification

```json
{
    "type": "roboflow-data-staging-notification-v1",
    "event_id": "8f42708b-aeb7-4b73-9d83-cf18518b6d81",
    "ingest_id": "d5cb69aa-b2d1-4202-a1c1-0231f180bda9",
    "batch_id": "prod-batch-1",
    "shard_id": "0d40fa12-349e-439f-83f8-42b9b7987b33",
    "notification": {
        "type": "ingest-files-status-notification-v1",
        "success": true,
        "ingested_files": [
            "000000494869.jpg",
            "000000186042.jpg"
        ],
        "failed_files": [
            {
                "type": "file-size-limit-exceeded",
                "file_name": "big_image.png",
                "reason": "Max size of single image is 20971520B."
            }
        ],
        "content_truncated": false
    },
    "delivery_attempt": 1
}
```

### Job Completion Webhooks

जोड़ें `--notifications-url` जब job शुरू करें:

```bash
inference rf-cloud batch-processing process-images-with-workflow \
  --workflow-id <workflow-id> \
  --batch-id <batch-id> \
  --notifications-url <webhook_url>
```

#### Job Completion Notification

```json
{
  "type": "roboflow-batch-job-notification-v1",
  "event_id": "8f42708b-aeb7-4b73-9d83-cf18518b6d81",
  "job_id": "<your-batch-job-id>",
  "job_state": "success | fail",
  "delivery_attempt": 1
}
```

## Cloud Storage Authentication

### AWS S3 और S3-Compatible Storage

Credentials स्वतः detect की जाती हैं:

1. **Environment variables से:**

```bash
export AWS_ACCESS_KEY_ID=your-access-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-access-key
export AWS_SESSION_TOKEN=your-session-token  # वैकल्पिक
```

2. **AWS credential files** (`~/.aws/credentials`, `~/.aws/config`)
3. **IAM roles** (EC2, ECS, Lambda)

**Named profiles:**

```bash
export AWS_PROFILE=production
```

**S3-compatible services (Cloudflare R2, MinIO, आदि):**

```bash
export AWS_ENDPOINT_URL=https://account-id.r2.cloudflarestorage.com
export AWS_REGION=auto  # R2 requires region='auto'
export AWS_ACCESS_KEY_ID=your-r2-access-key
export AWS_SECRET_ACCESS_KEY=your-r2-secret-key
```

### Google Cloud Storage

Credentials detect की जाती हैं:

1. **Service account key file** (automation के लिए अनुशंसित):

```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
```

2. **User credentials** gcloud CLI से (`gcloud auth login`)
3. **GCP metadata service** (जब Google Cloud Platform पर चल रहा हो)

### Azure Blob Storage

**SAS Token (अनुशंसित):**

```bash
export AZURE_STORAGE_ACCOUNT_NAME=mystorageaccount
export AZURE_STORAGE_SAS_TOKEN="sv=2021-06-08&ss=b&srt=sco&sp=rl&se=2024-12-31"
```

**Account Key:**

```bash
export AZURE_STORAGE_ACCOUNT_NAME=mystorageaccount
export AZURE_STORAGE_ACCOUNT_KEY=your-account-key
```

Azure CLI के माध्यम से SAS token बनाएं:

```bash
az storage container generate-sas \
  --account-name mystorageaccount \
  --name my-container \
  --permissions rl \
  --expiry 2024-12-31T23:59:59Z
```

### Custom Scripts

advanced use cases के लिए, signed URL files जनरेट करने हेतु scripts देखें:

* **AWS S3:** [generateS3SignedUrls.sh](https://raw.githubusercontent.com/roboflow/roboflow-python/main/scripts/generateS3SignedUrls.sh)
* **Google Cloud Storage:** [generateGCSSignedUrls.sh](https://github.com/roboflow/roboflow-python/blob/main/scripts/generateGCSSignedUrls.sh)
* **Azure Blob Storage:** [generateAzureSasUrls.sh](https://raw.githubusercontent.com/roboflow/roboflow-python/main/scripts/generateAzureSasUrls.sh)

## सभी विकल्प खोजें

```bash
inference rf-cloud --help
inference rf-cloud data-staging --help
inference rf-cloud batch-processing --help
```