> ## 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

> Manage Avala resources from your terminal

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`. |
| `--output`, `-o`  | Output format: `table` (default) or `json`.                                             |
| `--version`       | Show CLI version and exit.                                                              |
| `--help`          | Show help for any command.                                                              |

## Version

Print the installed CLI version:

```bash theme={null}
avala --version
```

```
avala, version 0.8.1
```

## JSON Output

Pass `--output json` (or `-o json`) to any command to get machine-readable JSON instead of Rich tables. This is useful for scripting and piping into tools like `jq`.

<CodeGroup>
  ```bash List dataset names theme={null}
  avala -o json datasets list | jq '.[].name'
  ```

  ```bash Check export status theme={null}
  avala -o json exports get exp_uid | jq '.status'
  ```

  ```bash Count pending exports theme={null}
  avala -o json exports list | jq '[.[] | select(.status == "pending")] | length'
  ```
</CodeGroup>

<Tip>
  When `-o json` is set, all output goes to stdout as valid JSON. Progress indicators and status messages are sent to stderr, so piping works cleanly.
</Tip>

## Shell Completion

Enable tab-completion for all `avala` commands and options. The CLI supports bash, zsh, and fish.

<CodeGroup>
  ```bash Bash theme={null}
  avala shell-completion bash >> ~/.bashrc
  source ~/.bashrc
  ```

  ```bash Zsh theme={null}
  avala shell-completion zsh >> ~/.zshrc
  source ~/.zshrc
  ```

  ```bash Fish theme={null}
  avala shell-completion fish > ~/.config/fish/completions/avala.fish
  ```
</CodeGroup>

If you omit the shell argument, the CLI auto-detects your current shell from the `SHELL` environment variable.

## Configure

Interactive setup wizard that prompts for your API key and base URL, validates the key against the API, and prints the `export` statements to add to your shell profile.

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

```
Configure your Avala CLI credentials.

API Key: avk_your_api_key
Base URL [https://api.avala.ai/api/v1]:

Validating API key... OK
  Organization: Acme Robotics

Add these to your shell profile (.zshrc):

  export AVALA_API_KEY='avk_your_api_key'
```

If validation fails (wrong key, network issue), the wizard asks whether to save anyway. This is useful for offline setup or when working with a custom base URL.

## Status Dashboard

Get a quick overview of your organization -- datasets, projects, pending exports, and fleet health -- in a single command.

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

The dashboard shows:

* **Organization name** from your API key
* **Recent datasets** (up to 5)
* **Recent projects** with status
* **Pending exports** (if any are processing)
* **Fleet devices** online/offline count (if Fleet is enabled)

Use `-o json` for a machine-readable snapshot:

```bash theme={null}
avala -o json status | jq '.datasets.showing'
```

## Commands

### datasets

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

# Limit results
avala datasets list --limit 10

# Get a specific dataset by UID
avala datasets get <uid>

# Ingest / health snapshot (post-upload validation)
avala datasets health <owner> <slug>

# Inspect a sequence
avala datasets get-sequence <owner> <slug> <sequence_uid>

# Inspect a single frame's LiDAR JSON metadata
avala datasets get-frame <owner> <slug> <sequence_uid> <frame_idx>

# Inspect the canonicalized rig calibration
avala datasets get-calibration <owner> <slug> <sequence_uid>
```

**`list` options:**

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

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

**`health` output fields:** dataset UID/status, item/sequence/frame counts, S3 prefix, `ingest_ok` flag, detected `issues`, per-sequence frame counts and calibration presence.

**`get-frame` output fields:** frame index, camera model (`pinhole` / `doublesphere`), `xi`, `alpha`, device position/heading, number of cameras.

**`get-calibration` output fields:** per-camera table — camera id, model, intrinsics (`fx`, `fy`, `cx`, `cy`), double-sphere parameters (`xi`, `alpha`) when applicable.

***

### import

Bring data into Mission Control from outside Avala. `import` uploads local media and registers a dataset in one step, auto-detecting the data type from file extensions. It is the fast path for "I have a folder of frames / video / LiDAR / MCAP — turn it into an Avala dataset."

```bash theme={null}
# List the available import sources
avala import list

# Import a local folder (data type auto-detected from extensions)
avala import folder \
  --source ./my_drive \
  --name "My Drive" \
  --slug my-drive

# Force the data type when extensions are ambiguous
avala import folder --source ./scans --name Scans --slug scans --data-type lidar

# Import and wait for server-side indexing to finish
avala import folder --source ./run01 --name "Run 01" --slug run-01 --wait
```

The `folder` source accepts a single file or a directory tree (uploaded recursively, preserving relative paths). Files are uploaded in parallel via presigned URLs, and the dataset is created from the manual-upload batch. Data type is inferred from extensions that the Avala indexer admits — images (`.jpg`, `.png`, `.webp`, `.bmp`, `.tif`, …), video (`.mp4`, `.webm`, `.mkv`, `.mov`), LiDAR (`.alp`, `.alp.gz`), MCAP (`.mcap`), and splats (`.ply`, `.splat`, `.spz`, …). Pass `--data-type` to override when extensions are ambiguous; the importer refuses up front if none of the files are indexable for the chosen type (so you never finalize an empty dataset).

**`folder` options:**

| Option               | Description                                                                  |
| -------------------- | ---------------------------------------------------------------------------- |
| `--source PATH`      | Local file or directory to import (required).                                |
| `--name TEXT`        | Dataset name (required).                                                     |
| `--slug TEXT`        | Dataset slug (required).                                                     |
| `--data-type CHOICE` | Override the auto-detected type: `image`, `video`, `lidar`, `mcap`, `splat`. |
| `--owner TEXT`       | Dataset owner username or email (defaults to the API key's user).            |
| `--workers INTEGER`  | Parallel upload threads (default: 8).                                        |
| `--wait / --no-wait` | Wait for server-side indexing to finish (default: `--no-wait`).              |

<Tip>
  Per-file and per-user upload caps apply (2 GiB per file, 10 GiB per user). For very large or already-cloud-hosted data, connect a bucket with [`storage-configs`](#storage-configs) for zero-copy ingest instead of re-uploading.
</Tip>

The same importers are available from the Python SDK via `avala.importers`:

```python theme={null}
from avala import Client
from avala.importers import import_folder

ds = import_folder(Client(), source="./my_drive", name="My Drive", slug="my-drive")
print(ds.uid, ds.data_type, ds.item_count)
```

#### LeRobot / Hugging Face Hub

Import a [LeRobot](https://github.com/huggingface/lerobot) robotics dataset — from the Hugging Face Hub or a local directory — as an Avala **MCAP** dataset. Each episode becomes one `.mcap` file (one Avala MCAP episode): camera streams are written as `foxglove.CompressedImage` so they render in the Mission Control viewer, and proprioception (`observation.state`, `action`) is written as protobuf `Struct` messages so the values are preserved in the file.

Requires the `lerobot` extra:

```bash theme={null}
pip install 'avala[lerobot]'
```

```bash theme={null}
# Import a dataset from the Hugging Face Hub
avala import lerobot \
  --repo-id lerobot/svla_so101_pickplace \
  --name "SO-101 Pick & Place" \
  --slug so101-pickplace

# Import a local LeRobot dataset, limiting to a few episodes
avala import lerobot --root ./my_lerobot_ds --name "My Robot" --slug my-robot --episodes 0,1,2

# Wait for server-side indexing to finish
avala import lerobot --repo-id lerobot/aloha_static_coffee --name Coffee --slug coffee --wait
```

**`lerobot` options:**

| Option               | Description                                                              |
| -------------------- | ------------------------------------------------------------------------ |
| `--repo-id TEXT`     | Hugging Face Hub dataset id (e.g. `lerobot/svla_so101_pickplace`).       |
| `--root PATH`        | Local LeRobot dataset directory (instead of, or alongside, `--repo-id`). |
| `--name TEXT`        | Dataset name (required).                                                 |
| `--slug TEXT`        | Dataset slug (required).                                                 |
| `--episodes TEXT`    | Comma-separated episode indices to import (default: all).                |
| `--camera-keys TEXT` | Comma-separated camera feature keys (default: all cameras).              |
| `--fps FLOAT`        | Override the dataset frame rate.                                         |
| `--owner TEXT`       | Dataset owner username or email.                                         |
| `--workers INTEGER`  | Parallel upload threads (default: 8).                                    |
| `--wait / --no-wait` | Wait for server-side indexing to finish (default: `--no-wait`).          |

```python theme={null}
from avala import Client
from avala.importers import import_lerobot

ds = import_lerobot(Client(), repo_id="lerobot/svla_so101_pickplace", name="SO-101", slug="so101")
print(ds.uid, ds.data_type)  # -> mcap
```

<Note>
  Mission Control's embedded MCAP viewer renders images, point clouds and logs. Scalar time-series (joint state / actions) are preserved in the `.mcap` and viewable as raw messages, but are not charted yet.
</Note>

#### ROS bags

Import a **ROS bag** (ROS1 `.bag` or ROS2 `.db3`) as an Avala MCAP dataset. Camera topics (`sensor_msgs/Image` and `sensor_msgs/CompressedImage`) are re-encoded as `foxglove.CompressedImage` so they render in the Mission Control viewer. Reading uses the pure-Python `rosbags` library — no ROS install required.

Requires the `rosbag` extra:

```bash theme={null}
pip install 'avala[rosbag]'
```

```bash theme={null}
# Import all camera topics from a bag
avala import rosbag ./session.bag --name "Session 12" --slug session-12

# A ROS2 bag directory, restricted to specific camera topics, waiting for indexing
avala import rosbag ./ros2_bag/ --name Run --slug run \
  --image-topics /camera/front/image_raw,/camera/rear/compressed --wait
```

**`rosbag` options:**

| Option                | Description                                                                |
| --------------------- | -------------------------------------------------------------------------- |
| `BAG`                 | Path to a ROS1 `.bag` file or a ROS2 bag directory (positional, required). |
| `--name` / `--slug`   | Dataset name / slug (required).                                            |
| `--image-topics TEXT` | Comma-separated image topics to convert (default: all image topics).       |
| `--owner TEXT`        | Dataset owner username or email.                                           |
| `--workers INTEGER`   | Parallel upload threads (default: 8).                                      |
| `--wait / --no-wait`  | Wait for server-side indexing to finish (default: `--no-wait`).            |

<Note>
  This increment carries **camera topics only**. Non-image topics (point clouds, TF, joint states, …) are reported but not yet carried over — faithfully copying ROS-encoded messages through (preserving their schemas) is a planned follow-up.
</Note>

```python theme={null}
from avala import Client
from avala.importers import import_ros_bag

ds = import_ros_bag(Client(), bag="./session.bag", name="Session 12", slug="session-12")
print(ds.uid, ds.data_type)  # -> mcap
```

#### Cloud buckets (S3 / GCS) — zero-copy

Import data you already have in an S3 or GCS bucket **without re-uploading it**. Avala points the dataset at your bucket + prefix and indexes the objects in place — nothing is copied. Ideal for terabyte-scale data that already lives in the cloud.

```bash theme={null}
# AWS S3 with access keys — read from the environment so secrets stay off argv
export AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... AWS_REGION=us-west-2
avala import cloud s3://my-bucket/datasets/run01/ \
  --name "Run 01" --slug run-01 --data-type image

# AWS S3 keyless (cross-account IAM role — no secrets exchanged)
avala import cloud s3://my-bucket/lidar/ \
  --name Scans --slug scans --data-type lidar --region us-west-2 \
  --role-arn arn:aws:iam::123456789012:role/AvalaRead

# Google Cloud Storage (service-account JSON key file)
avala import cloud gs://my-gcs-bucket/frames/ \
  --name Frames --slug frames --data-type image --gcs-auth-json ./service-account.json

# Scope the import and wait for indexing
avala import cloud s3://b/p --name N --slug n --data-type image --region us-west-2 \
  --role-arn arn:aws:iam::123456789012:role/AvalaRead \
  --include-extensions webp,png --ignore-paths "*/thumbnails/*" --wait
```

The server lists the bucket under the prefix and registers every object whose extension matches `--data-type` (image / video / lidar / mcap / splat) — the same indexer filter as uploads. Use `--include-extensions` / `--ignore-paths` to narrow the scope.

**`cloud` options:**

| Option                                    | Description                                                                                     |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `URI`                                     | `s3://bucket/prefix` or `gs://bucket/prefix` (positional, required).                            |
| `--name` / `--slug`                       | Dataset name / slug (required).                                                                 |
| `--data-type CHOICE`                      | What the server indexes from the bucket: `image`, `video`, `lidar`, `mcap`, `splat` (required). |
| `--region TEXT`                           | S3 bucket region (or `AWS_REGION`).                                                             |
| `--access-key-id` / `--secret-access-key` | S3 static credentials (or `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`).                       |
| `--role-arn TEXT`                         | S3 keyless cross-account IAM role (instead of access keys).                                     |
| `--accelerated`                           | Use S3 Transfer Acceleration.                                                                   |
| `--gcs-auth-json TEXT`                    | GCS service-account JSON, or a path to a `.json` key file.                                      |
| `--include-extensions`                    | Comma-separated extensions to index (e.g. `webp,png`).                                          |
| `--ignore-paths`                          | Comma-separated glob paths to skip (matched against object keys).                               |
| `--owner TEXT`                            | Dataset owner username or email.                                                                |
| `--wait / --no-wait`                      | Wait for server-side indexing to finish (default: `--no-wait`).                                 |

<Tip>
  For **keyless** S3 access, the customer grants Avala's account + external ID via an IAM trust policy — run `avala storage-configs ...` setup or call `client.storage_configs.setup_info()` to get the account ID and external ID for the trust policy. GCS uses a service-account JSON key.
</Tip>

```python theme={null}
from avala import Client
from avala.importers import import_cloud

ds = import_cloud(
    Client(), uri="s3://my-bucket/run01/", name="Run 01", slug="run-01",
    data_type="image", region="us-west-2", role_arn="arn:aws:iam::123456789012:role/AvalaRead",
)
print(ds.uid, ds.data_type)
```

***

### 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>

# Wait for an export to finish
avala exports wait <uid>
```

**`create` options:**

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

**`wait` options:**

| Option             | Description                             |
| ------------------ | --------------------------------------- |
| `--interval FLOAT` | Seconds between polls (default: 2.0).   |
| `--timeout FLOAT`  | Maximum seconds to wait (default: 300). |

The `wait` command polls the export until it reaches a terminal state (`completed` or `failed`), then prints the final export details. Progress dots are printed to stderr so you can pipe the result:

```bash theme={null}
# Create and wait in one pipeline
avala exports create --project proj_abc123 \
  | grep -oP 'exp_\w+' \
  | xargs avala exports wait
```

***

### 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

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

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. See the [Configure](#configure) section above for the full walkthrough.

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

## 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 wait for it to complete
avala exports create --project proj_abc123
avala exports wait exp_xyz789 --timeout 600

# Use JSON output for scripting
DATASET_COUNT=$(avala -o json datasets list | jq 'length')
echo "Found $DATASET_COUNT datasets"
```

## 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.

Pass `--output json` (or `-o json`) to any command for machine-readable JSON output. See the [JSON Output](#json-output) section for examples.