CLI - Avala Documentation

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

Installation

curl -fsSL https://avala.ai/install.sh | bash

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 and Rich for formatted terminal output.

Authentication

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

export AVALA_API_KEY="avk_your_api_key"

Or pass it as a flag on any command:

avala --api-key avk_your_api_key datasets list

To set up credentials interactively:

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:

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.

avala -o json datasets list | jq '.[].name'

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.

Shell Completion

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

avala shell-completion bash >> ~/.bashrc
source ~/.bashrc

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.

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.

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:

avala -o json status | jq '.datasets.showing'

Commands

datasets

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

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

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 for zero-copy ingest instead of re-uploading.

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

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

pip install 'avala[lerobot]'

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

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

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.

projects

# 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

# 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

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

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

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

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

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

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

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

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

# 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

Fleet commands are in preview. Commands described here may change.

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

# 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 section above for the full walkthrough.

avala configure

Examples

List datasets and export a project

# 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

# 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

# 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 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 section for examples.

​Installation

​Authentication

​Global Options

​Version

​JSON Output

​Shell Completion

​Configure

​Status Dashboard

​Commands

​datasets

​import

​LeRobot / Hugging Face Hub

​projects

​tasks

​exports

​storage-configs

​agents

​webhooks

​quality-targets

​consensus

​inference-providers

​auto-label

​fleet

​configure

​Examples

​List datasets and export a project

​Set up cloud storage

​Use with CI/CD

​Environment Variables

​Output Format

Installation

Authentication

Global Options

Version

JSON Output

Shell Completion

Configure

Status Dashboard

Commands

datasets

import

LeRobot / Hugging Face Hub

projects

tasks

exports

storage-configs

agents

webhooks

quality-targets

consensus

inference-providers

auto-label

fleet

configure

Examples

List datasets and export a project

Set up cloud storage

Use with CI/CD

Environment Variables

Output Format