> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> உங்கள் டெர்மினலிலிருந்து Avala வளங்களை நிர்வகியுங்கள்

The Avala CLI lets you list datasets, create exports, manage cloud storage, and more — directly from the command line.

## Installation

<CodeGroup>
  ```bash Recommended theme={null}
  curl -fsSL https://avala.ai/install.sh | bash
  ```

  ```bash pip theme={null}
  pip install avala[cli]
  ```
</CodeGroup>

The install script detects your Python version, installs `avala[cli]` via pip, and verifies the setup. Requires Python 3.9+.

This installs the `avala` command along with [Click](https://click.palletsprojects.com/) and [Rich](https://rich.readthedocs.io/) for formatted terminal output.

## Authentication

Set your API key as an environment variable (recommended):

```bash theme={null}
export AVALA_API_KEY="avk_your_api_key"
```

Or pass it as a flag on any command:

```bash theme={null}
avala --api-key avk_your_api_key datasets list
```

To set up credentials interactively:

```bash theme={null}
avala configure
```

This walks you through entering your API key and base URL, then prints the `export` statements to add to your shell profile.

## Global Options

| Option            | Description                                                                             |
| ----------------- | --------------------------------------------------------------------------------------- |
| `--api-key TEXT`  | Avala API key (or set `AVALA_API_KEY` env var).                                         |
| `--base-url TEXT` | API base URL (or set `AVALA_BASE_URL` env var). Default: `https://api.avala.ai/api/v1`. |
| `--help`          | Show help for any command.                                                              |

## Commands

### datasets

```bash theme={null}
# List all datasets
avala datasets list

# Limit results
avala datasets list --limit 10

# Get a specific dataset
avala datasets get <uid>
```

**`list` options:**

| Option            | Description                          |
| ----------------- | ------------------------------------ |
| `--limit INTEGER` | Maximum number of results to return. |

**`get` output fields:** UID, Name, Slug, Items, Type, Created, Updated.

***

### projects

```bash theme={null}
# List all projects
avala projects list

# Get a specific project
avala projects get <uid>
```

**`list` options:**

| Option            | Description                          |
| ----------------- | ------------------------------------ |
| `--limit INTEGER` | Maximum number of results to return. |

**`get` output fields:** UID, Name, Status, Created, Updated.

***

### tasks

```bash theme={null}
# List all tasks
avala tasks list

# Limit results
avala tasks list --limit 50

# Get a specific task
avala tasks get <uid>
```

**`list` options:**

| Option            | Description                          |
| ----------------- | ------------------------------------ |
| `--limit INTEGER` | Maximum number of results to return. |

**`get` output fields:** UID, Name, Type, Status, Project, Created, Updated.

***

### exports

```bash theme={null}
# List all exports
avala exports list

# Get export details
avala exports get <uid>

# Create a new export
avala exports create --project <uid>
avala exports create --dataset <uid>
```

**`create` options:**

| Option           | Description            |
| ---------------- | ---------------------- |
| `--dataset TEXT` | Dataset UID to export. |
| `--project TEXT` | Project UID to export. |

***

### storage-configs

Manage cloud storage connections (AWS S3, Google Cloud Storage).

```bash theme={null}
# List storage configurations
avala storage-configs list

# Add an S3 bucket
avala storage-configs create \
  --name "Production S3" \
  --provider aws_s3 \
  --s3-bucket-name my-bucket \
  --s3-bucket-region us-west-1 \
  --s3-access-key-id $AWS_ACCESS_KEY_ID \
  --s3-secret-access-key $AWS_SECRET_ACCESS_KEY

# Add a GCS bucket
avala storage-configs create \
  --name "Production GCS" \
  --provider gc_storage \
  --gc-bucket-name my-gcs-bucket \
  --gc-auth-json '{"type":"service_account",...}'

# Test a storage connection
avala storage-configs test <uid>

# Delete a storage config (prompts for confirmation)
avala storage-configs delete <uid>
```

**`create` options:**

| Option              | Description                                    |
| ------------------- | ---------------------------------------------- |
| `--name TEXT`       | Name for the storage configuration (required). |
| `--provider CHOICE` | `aws_s3` or `gc_storage` (required).           |

**AWS S3 options:**

| Option                        | Description                     |
| ----------------------------- | ------------------------------- |
| `--s3-bucket-name TEXT`       | S3 bucket name.                 |
| `--s3-bucket-region TEXT`     | AWS region (e.g., `us-west-1`). |
| `--s3-bucket-prefix TEXT`     | Object key prefix.              |
| `--s3-access-key-id TEXT`     | AWS access key ID.              |
| `--s3-secret-access-key TEXT` | AWS secret access key.          |

**Google Cloud Storage options:**

| Option                  | Description                       |
| ----------------------- | --------------------------------- |
| `--gc-bucket-name TEXT` | GCS bucket name.                  |
| `--gc-prefix TEXT`      | Object key prefix.                |
| `--gc-auth-json TEXT`   | Service account JSON credentials. |

***

### agents

Manage automation agents.

```bash theme={null}
# List agents
avala agents list

# Get agent details
avala agents get <uid>

# Create an agent
avala agents create \
  --name "QA Bot" \
  --events "task.completed,result.submitted" \
  --callback-url https://example.com/hook

# Delete an agent (prompts for confirmation)
avala agents delete <uid>

# List executions for an agent
avala agents executions <uid>

# Test an agent
avala agents test <uid>
```

**`create` options:**

| Option                | Description                          |
| --------------------- | ------------------------------------ |
| `--name TEXT`         | Agent name (required).               |
| `--events TEXT`       | Comma-separated list of event types. |
| `--callback-url TEXT` | Webhook callback URL (HTTPS).        |
| `--description TEXT`  | Agent description.                   |
| `--project TEXT`      | Project UID to scope the agent to.   |
| `--task-types TEXT`   | Comma-separated list of task types.  |

**`list` options:**

| Option            | Description                          |
| ----------------- | ------------------------------------ |
| `--limit INTEGER` | Maximum number of results to return. |

**`executions` options:**

| Option            | Description                          |
| ----------------- | ------------------------------------ |
| `--limit INTEGER` | Maximum number of results to return. |

***

### webhooks

Manage webhook subscriptions.

```bash theme={null}
# List webhooks
avala webhooks list

# Get webhook details
avala webhooks get <uid>

# Create a webhook
avala webhooks create \
  --target-url https://example.com/webhook \
  --events "task.completed,export.ready"

# Delete a webhook (prompts for confirmation)
avala webhooks delete <uid>

# Test a webhook
avala webhooks test <uid>

# List webhook deliveries
avala webhooks deliveries
```

**`create` options:**

| Option              | Description                                      |
| ------------------- | ------------------------------------------------ |
| `--target-url TEXT` | Webhook target URL, HTTPS (required).            |
| `--events TEXT`     | Comma-separated list of event types (required).  |
| `--secret TEXT`     | HMAC signing secret (auto-generated if omitted). |

**`list` / `deliveries` options:**

| Option            | Description                          |
| ----------------- | ------------------------------------ |
| `--limit INTEGER` | Maximum number of results to return. |

***

### quality-targets

Manage quality targets for projects.

```bash theme={null}
# List quality targets for a project
avala quality-targets list --project <uid>

# Get a specific quality target
avala quality-targets get --project <uid> <target_uid>

# Create a quality target
avala quality-targets create \
  --project <uid> \
  --name "Accuracy Target" \
  --metric accuracy \
  --threshold 0.95 \
  --operator gte \
  --severity critical

# Delete a quality target (prompts for confirmation)
avala quality-targets delete --project <uid> <target_uid>

# Evaluate all quality targets for a project
avala quality-targets evaluate --project <uid>
```

**`create` options:**

| Option              | Description                                     |
| ------------------- | ----------------------------------------------- |
| `--project TEXT`    | Project UID (required).                         |
| `--name TEXT`       | Target name (required).                         |
| `--metric TEXT`     | Metric to monitor (required).                   |
| `--threshold FLOAT` | Threshold value (required).                     |
| `--operator TEXT`   | Comparison operator (`gt`, `lt`, `gte`, `lte`). |
| `--severity CHOICE` | Alert severity: `warning` or `critical`.        |

**`list` options:**

| Option            | Description                          |
| ----------------- | ------------------------------------ |
| `--project TEXT`  | Project UID (required).              |
| `--limit INTEGER` | Maximum number of results to return. |

***

### consensus

Manage consensus scoring for projects.

```bash theme={null}
# Get consensus summary for a project
avala consensus summary --project <uid>

# List consensus scores
avala consensus scores --project <uid>

# Compute consensus scores
avala consensus compute --project <uid>

# View or update consensus config
avala consensus config --project <uid>
avala consensus config --project <uid> --iou-threshold 0.7 --min-annotations 3
```

**`summary` / `scores` / `compute` options:**

| Option           | Description             |
| ---------------- | ----------------------- |
| `--project TEXT` | Project UID (required). |

**`scores` options:**

| Option            | Description                          |
| ----------------- | ------------------------------------ |
| `--limit INTEGER` | Maximum number of results to return. |

**`config` options (pass any to update, omit all to view):**

| Option                        | Description                        |
| ----------------------------- | ---------------------------------- |
| `--project TEXT`              | Project UID (required).            |
| `--iou-threshold FLOAT`       | IoU threshold (0.0-1.0).           |
| `--min-agreement-ratio FLOAT` | Minimum agreement ratio (0.0-1.0). |
| `--min-annotations INTEGER`   | Minimum annotations required.      |

***

### inference-providers

Manage inference providers.

```bash theme={null}
# List inference providers
avala inference-providers list

# Get provider details
avala inference-providers get <uid>

# Create a provider
avala inference-providers create \
  --name "My SageMaker" \
  --provider-type sagemaker \
  --config '{"endpoint": "my-endpoint", "region": "us-east-1"}'

# Delete a provider (prompts for confirmation)
avala inference-providers delete <uid>

# Test provider connection
avala inference-providers test <uid>
```

**`create` options:**

| Option                   | Description                                |
| ------------------------ | ------------------------------------------ |
| `--name TEXT`            | Provider name (required).                  |
| `--provider-type CHOICE` | `http` or `sagemaker` (required).          |
| `--config TEXT`          | Provider config as JSON string (required). |
| `--description TEXT`     | Provider description.                      |
| `--project TEXT`         | Project UID to scope the provider to.      |

**`list` options:**

| Option            | Description                          |
| ----------------- | ------------------------------------ |
| `--limit INTEGER` | Maximum number of results to return. |

***

### auto-label

Manage auto-label jobs.

```bash theme={null}
# List auto-label jobs
avala auto-label list

# Filter by project
avala auto-label list --project <uid>

# Get job details
avala auto-label get <uid>

# Create an auto-label job
avala auto-label create \
  --project <uid> \
  --model-type sam3 \
  --confidence-threshold 0.85 \
  --labels "car,truck"

# Cancel a running job (prompts for confirmation)
avala auto-label cancel <uid>
```

**`create` options:**

| Option                         | Description                               |
| ------------------------------ | ----------------------------------------- |
| `--project TEXT`               | Project UID (required).                   |
| `--model-type CHOICE`          | Inference model: `sam3` or `yolo`.        |
| `--confidence-threshold FLOAT` | Minimum confidence (0.0-1.0).             |
| `--labels TEXT`                | Comma-separated list of labels to filter. |
| `--dry-run`                    | Run inference without saving results.     |

**`list` options:**

| Option            | Description                          |
| ----------------- | ------------------------------------ |
| `--project TEXT`  | Filter by project UID.               |
| `--limit INTEGER` | Maximum number of results to return. |

***

### fleet

<Info>
  Fleet commands are in preview. Commands described here may change.
</Info>

Manage fleet devices, recordings, events, rules, and alerts.

```bash theme={null}
# List online devices
avala fleet devices list --status online

# Register a new device
avala fleet devices register --name "robot-arm-01" --type manipulator --firmware "2.4.1"

# List recordings for a device
avala fleet recordings list --device dev_abc123 --since 7d

# Create a timeline event
avala fleet events create --recording rec_abc123 --type anomaly --label "Gripper force spike"

# List recording rules
avala fleet rules list

# List active alerts
avala fleet alerts list --status open
```

**`devices list` options:**

| Option            | Description                                           |
| ----------------- | ----------------------------------------------------- |
| `--status CHOICE` | Filter by status: `online`, `offline`, `maintenance`. |
| `--type TEXT`     | Filter by device type.                                |
| `--limit INTEGER` | Maximum number of results to return.                  |

**`recordings list` options:**

| Option            | Description                                                                |
| ----------------- | -------------------------------------------------------------------------- |
| `--device TEXT`   | Filter by device UID.                                                      |
| `--since TEXT`    | Recordings from the last N days (e.g., `7d`, `30d`).                       |
| `--status CHOICE` | Filter by status: `uploading`, `processing`, `ready`, `error`, `archived`. |
| `--limit INTEGER` | Maximum number of results to return.                                       |

**`alerts list` options:**

| Option              | Description                                                 |
| ------------------- | ----------------------------------------------------------- |
| `--status CHOICE`   | Filter by status: `open`, `acknowledged`, `resolved`.       |
| `--severity CHOICE` | Filter by severity: `info`, `warning`, `error`, `critical`. |
| `--limit INTEGER`   | Maximum number of results to return.                        |

***

### configure

Interactive setup wizard for CLI credentials.

```bash theme={null}
avala configure
```

Prompts for your API key and base URL, then outputs the `export` commands to add to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.).

## Examples

### List datasets and export a project

```bash theme={null}
# See what datasets you have
avala datasets list

# Export annotations from a project
avala exports create --project proj_abc123

# Check export status
avala exports get exp_xyz789
```

### Set up cloud storage

```bash theme={null}
# Connect an S3 bucket
avala storage-configs create \
  --name "Training Data" \
  --provider aws_s3 \
  --s3-bucket-name ml-training-data \
  --s3-bucket-region us-east-1 \
  --s3-access-key-id $AWS_ACCESS_KEY_ID \
  --s3-secret-access-key $AWS_SECRET_ACCESS_KEY

# Verify the connection works
avala storage-configs test sc_abc123
```

### Use with CI/CD

```bash theme={null}
# In your CI pipeline
export AVALA_API_KEY="${AVALA_API_KEY}"

# Trigger an export and capture the UID
avala exports create --project proj_abc123
```

## Environment Variables

| Variable         | Description            | Default                       |
| ---------------- | ---------------------- | ----------------------------- |
| `AVALA_API_KEY`  | Your Avala API key.    | Required                      |
| `AVALA_BASE_URL` | API base URL override. | `https://api.avala.ai/api/v1` |

## Output Format

The CLI uses [Rich](https://rich.readthedocs.io/) for formatted output:

* **List commands** display results in formatted tables.
* **Get commands** display a key-value detail view.
* **Create/delete commands** print confirmation messages.

Colors and formatting are automatically disabled when output is piped or redirected.

<Note>
  The CLI does not yet support `--output json` or `--format` flags. All output is formatted for terminal readability. For machine-readable output, use the [Python SDK](/docs/sdks/python) or [REST API](/docs/sdks/rest-api) directly.
</Note>