Metadata-Version: 2.5
Name: qualia-cli
Version: 0.3.0rc7
Summary: CLI for the Qualia robotics data and VLA platform
Project-URL: Homepage, https://qualiastudios.dev
Project-URL: Documentation, https://docs.qualiastudios.dev
Author: Qualia Studios
License-Expression: MIT
Keywords: cli,fine-tuning,qualia,robotics,vla
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: qualia-sdk>=0.8.0rc7
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.15.0
Description-Content-Type: text/markdown

# qualia-cli — terminal client for the Qualia robotics data and VLA platform

**Status:** beta source candidate (0.3.0rc7) · **Distribution:** PyPI, `qualia-cli`

Wraps the public Qualia API: authenticate once, then manage projects, import datasets, launch
fine-tuning jobs and follow their progress from a shell. Every command takes `--json`, so the same
surface works interactively and in CI.

The CLI and the endpoint it talks to negotiate the upload protocol exactly, so a deployment running
ahead of the public release needs the matching pre-release wheel. See Install below.

## Install

```sh
pip install qualia-cli
```

Or with [uv](https://docs.astral.sh/uv/):

```sh
uv tool install qualia-cli
```

### Pre-release builds

Pin the wheel that matches the endpoint's generation. This source candidate is
`0.3.0rc7` and requires `qualia-sdk>=0.8.0rc7` for workspace-bound saved upload
destinations, the handheld setup commands and `qualia robot`. Use these commands after the candidates are published and your
deployment supports the merged-upload lifecycle; otherwise select the matching
published version.

```sh
pip install 'qualia-cli==0.3.0rc7'
```

uv does not resolve a pre-release through a dependency, even one that names it, so uv needs the
flag as well as the pin:

```sh
uv tool install --prerelease=allow 'qualia-cli==0.3.0rc7'
```

## Draft Tasks from selected episodes (staged)

Manual creation remains available: `qualia task create --name "Pick a box"`
needs no dataset or episode. For a model proposal, choose every reference
explicitly (1–3 success episodes; 1–2 per named failure/recovery mode):

```sh
qualia task create --name "Pick a box" \
  --success accounts/<a>/datasets/<d>/episodes/<e> \
  --failure slip=accounts/<a>/datasets/<d>/episodes/<other-e>
qualia task references <task>
qualia task draft <task> --estimate          # price, no run or reservation
qualia task draft <task> --wait              # bill for the stored proposal
qualia task draft-get <draft>                # review all text and the graph
qualia task draft-apply <draft> --file reviewed.yaml
qualia task publish <task>                  # separate person-controlled action
```

No reference is sampled, suggested or silently omitted. The apply command
saves an editable proposal, never publishes; the file may edit its text and
procedure. `--max-cost` caps credit reservation, and `task draft-get` can
resume review after a lost connection. The `vlm-task-draft` template is
currently disabled: estimates and runs will fail until rollout is authorized.

## Usage

```sh
# Authenticate (pick one)
qualia auth login                        # interactive, saves to config
export QUALIA_API_KEY="your-api-key"     # env var
qualia --token <KEY> <command>           # inline, for CI/scripts

# List available models
qualia model list

# List GPU instances
qualia instance list

# Create a project
qualia project create "My Robot"

# Start a fine-tuning job
qualia job launch \
  --project-id <id> \
  --vla-type pi05 \
  --model-id lerobot/pi05_base \
  --dataset-version-id <DATASET_VERSION_UUID> \
  --hours 2.0 \
  --camera-mappings '{"cam_1": "observation.images.top"}'

# Check job status (a pipeline with map nodes also shows each map's item
# progress and its map ID)
qualia job get <job-id>
# A failed job also prints who caused it (your side or ours), what, why, and its credits

# Page a map's items: one row per attempt, filtered by state if you like
qualia job items <job-id> <map-id> --status failed --limit 50 --offset 0

# Upload a recorded MCAP session; a session no bag can derive is refused
# before upload unless you pass --allow-underivable
qualia dataset upload ./session dk1-kitchen --source-format mcap_ros2
# exits 0 published/degraded, 1 nothing uploaded, 3 stored but no episode derived

# A teleop arm needs no config when its state is a JointState topic named
# joint_state(s) and its action is a JointTrajectory topic, or a JointState or
# MultiArray topic named cmd, command or action. In <session>/meta/ingest.toml,
# declare [actions] alone when a topic named like a command is operator input
# (a joystick), and both [state] and [actions] when a second JointState topic
# (a leader arm) would be read as state, or the rig publishes poses and has no
# JointState:
#   schema = 1
#   [state]
#   topics = ["/controller/left/pose", "/controller/right/pose"]
#   [actions]
#   topics = []   # no action column
# Fields are carried as recorded, with no rotation conversion. [clock] takes
# row_clock_topic or fixed_hz, not both.
# Guide: https://docs.qualiastudios.dev/global/guides/data-collection
# A successful upload prints the topics that fed state and action, and says
# "action: none (no action column)" when there is none. --quiet still prints them.
# While bytes travel it prints "X / Y sent": source bytes already in storage,
# before the server verifies them. `qualia dataset uploads` shows how far each
# upload in flight has got, counting stored as well as verified bytes, as the
# dashboard card does.

# LeRobot trees are checked before upload too. A structural problem the server
# always refuses (bad meta/info.json, codebase_version not matching
# --source-format, no parquet under data/, v2.1 without episodes.jsonl or
# tasks.jsonl) exits 1 with nothing uploaded; --allow-underivable cannot
# override it. A missing video only warns, naming the episode and camera; the
# upload continues and that episode will be flagged (you should probably
# exclude it).
#
# The format is read from the tree when --source-format is left out.
qualia dataset upload ./my-recording my-dataset

# Save a default merged-dataset destination for uploads in this local config.
# It is bound to this API host, account, and workspace; changing it affects
# future upload intents, not uploads already in flight.
qualia dataset destination set accounts/<account-uuid>/datasets/<merged-uuid>
qualia dataset destination show
qualia dataset destination clear

# Override that default for one upload, or keep one upload standalone.
qualia dataset upload ./week-2 week-2 --source-format lerobot_v3 \
  --merge-target accounts/<account-uuid>/datasets/<merged-uuid>
qualia dataset upload ./calibration calibration --source-format lerobot_v3 --standalone

# Convert a handheld (UMI) recording at a gripper's TCP as it lands. The gripper
# is its name, id or rig key; an upload into a merged dataset whose uploads
# agree on one rig takes that rig without --rig. Your local files are untouched.
qualia dataset upload ./umi-session umi-session --source-format mcap_ros2 --rig umi-handheld

# Workspace selection is the gateway's X-Qualia-Workspace context. An explicit
# selection overrides the workspace bound to the saved destination; a mismatch
# leaves this upload standalone instead of sending it into another workspace.
qualia --workspace <project-uuid> dataset upload ./week-3 week-3 \
  --source-format lerobot_v3
export QUALIA_WORKSPACE=<project-uuid>  # alternatively, select it for this shell

# If append needs action, the upload remains published and the command prints
# its dataset ID and reason. A retry after an explicit revert keeps that intent
# reverted; it never silently appends again.

# List your uploads; Verdict is published | degraded | underivable. With your account set
# (see Tasks below) it reads qualia.v1 and --json prints qualia.v1 Datasets (reason:
# verdict_reason); without one it reads the older route (reason: qds.verdict_reason).
qualia dataset list

# Filter by collection tags (repeat for alternatives).
qualia dataset list --tag umi --tag gello

# Change classifications through this dataset's saved metadata. A merged
# dataset keeps its choices on append. Customs alone preserve classifications.
qualia dataset tags <dataset-uuid> --tag umi --tag real-world --tag human --tag gello
qualia dataset tags <dataset-uuid> --tag warehouse-a
# --clear clears customs and explicitly makes every collection dimension Unknown.
qualia dataset tags <dataset-uuid> --clear
# Unchanged classifications with edited customs change only customs. Echo the
# current classifications, when present, to remove customs while preserving inferred methods.
# The SDK reads the owner and fences the write with its etag unless --etag is supplied.
# The older `dataset methods` command edits the six-name compatibility view.

# Collection semantics: docs/operations/qds-service.md#collection-metadata
# Calibrated export: docs/operations/qds-service.md#calibrated-handheld-lerobot-state

# Cut episodes into child episodes at their markers, or, where the recorder
# marked nothing, at instants (seconds from the start of the recording, the
# same instants in each named episode). --dry-run plans without writing; a
# split is published when it answers and cannot be undone (curate a child by
# trimming or rejecting it). A trimmed episode is cut inside its trim. A
# request cuts at markers or at instants, not both.
qualia dataset split <episode> -d <dataset> --cut-at success --dry-run
qualia dataset split <episode> -d <dataset> --at 12.5 --at 31 --dry-run

# Edit many episodes in one call, all or none (up to 500 of one upload): the
# same fields on each, or per-episode edits from a JSON list (- reads stdin).
qualia dataset edit <episode>... -d <dataset> --tag slow --outcome FAILURE
qualia dataset edit -d <dataset> --from edits.json

# Import an exact Hugging Face dataset commit. HF_TOKEN is read from the
# environment or the Hub's protected local credential store, never an argv flag.
export HF_TOKEN="..."  # omit for public datasets
qualia dataset import-hf \
  qualia-robotics/openarm-cube-in-box-v1 \
  17c29c487d886878ddcb3c5649101b2860fbc047 \
  openarm-cube-in-box \
  --source-format lerobot_v3
```

### Tasks

Tasks say what a robot should do and how success shows, as five pieces of
prose: description, scene, steps (one per line), success and failure. They live
under your account: pass `--account <UUID>`, set `QUALIA_ACCOUNT`, or save it
with `qualia auth login --account <UUID>`.

```sh
qualia task create --name "Restock shelf" -d "Move every box from the tray to the shelf"
qualia task edit <task-id> --steps $'Pick a box from the tray\nPlace it upright on the shelf' \
  --success "The tray is empty and every box stands upright"
                                               # just those fields; "" clears one

# Or author the five fields as a file, as `qualia task get <id> --json` prints
# a task (displayName, etag, draft) or as a bare spec:
cat > shelf.yaml <<'EOF'
description: Move every box from the tray to the shelf
scene: A tray of six boxes beside a two-level wire shelf
steps: |
  Pick a box from the tray
  Place it upright on the shelf
success: The tray is empty and every box stands upright
failure: A box falls over or drops to the floor
EOF
qualia task edit <task-id> shelf.yaml          # replaces the whole draft

# A spec file may also hold an optional procedure: the task as a state machine of
# steps and transitions, checked when the task is published.
cat >> shelf.yaml <<'EOF'
procedure:
  steps:
    - {id: start, kind: START, description: Boxes in the tray}
    - {id: place, description: Place a box upright on the shelf, min_count: 6, max_count: 6}
    - {id: shelved, kind: SUCCESS, description: All boxes shelved}
    - {id: fallen, kind: FAILURE, description: A box fell over}
  transitions:
    - {source: start, target: place}
    - {source: place, target: shelved}
    - {source: place, target: fallen}
EOF
qualia task edit <task-id> shelf.yaml

qualia task get <task-id>                      # each field under its heading, then the procedure
qualia task publish <task-id> -m "first cut"   # needs a description and a success
qualia task revisions <task-id>
qualia task get <task-id> --revision 1
qualia task list
qualia task delete <task-id> [--force]         # account owners only
```

Link recorded data to the task it was recorded against (CLI 0.3.0rc3). The
label stays the text training reads; a link changes no revision or version, and
deleting the task unlinks.

```sh
qualia dataset link-task <upload-id> <task-id>             # every episode without its own link reads it
qualia dataset link-task <upload-id> <task-id> --relink    # also moves those linked to the old task; --unlink removes it
qualia dataset link-task <merged-id> <task-id>             # a merged dataset: every upload it holds
qualia dataset assign-task -d <upload-id> --task <task-id> --filter 'state = KEPT'
                                               # links and labels them with the task's name
qualia dataset assign-task <episode-id>... -d <upload-id> --label "restock shelf"
                                               # a label alone leaves links as they are
qualia task link-episodes <task-id> --dry-run  # unlinked labels that name it: exact and near misses
qualia task link-episodes <task-id> -l "restock shelf" -l "Restock shelf."
                                               # links those labels' episodes and uploads
```

Publishing a task links, on its own, the unlinked episodes and uploads whose
label is exactly its name. `task link-episodes` lists those beside the near
misses (case, spacing, punctuation) in your workspace and links the labels you
pass; a link already set never changes.

### Checks

Run a check over a dataset and read its findings. The VLM check reads each
episode against its linked, published task; `estimate` says what a run would
reserve without starting or charging anything.

```sh
qualia check estimate <dataset> --max-episodes 5 --max-cost 20  # estimate a small trial
qualia check run <dataset> --max-episodes 5 --max-cost 20 --wait  # same sample and credit ceiling
qualia check run <dataset> --model <model> --wait  # --check episode-rules|mixture|reach; - for defaults
qualia check status <run-name>                   # QUEUED, RUNNING, SUCCEEDED or FAILED, with counts
qualia check runs --check vlm -d <dataset> --state FAILED
qualia check findings <dataset>                  # issues and notes, with verdict, confidence and moments
qualia check reach-status <dataset>              # Run solver: its settings and how far the last run got
qualia check reach-cancel <dataset>              # stop the run under way
```

`--max-episodes` and `--max-cost` are positive VLM-only limits. Match both on
`estimate` and `run` to see what the trial reserves before it starts. Omit
them to check the whole eligible scope without a credit ceiling.

The checks catalog (versioned checks such as `task.graph`) runs a selection as
one run, one model call per episode for every selected VLM check:

```sh
qualia dataset checks list <dataset>                       # by category: runnable, last result
qualia dataset checks run <dataset> --check task.graph --category quality --validate-only
qualia dataset checks run <dataset> --all --max-episodes 50 --max-cost 120 --wait
```

`--check` and `--category` repeat and combine with `--all` as a union. A run
needs `--max-cost` at or above the bound `--validate-only` shows.

### Set up a handheld (UMI) dataset

Everything the dashboard's Setup strip does is a command: pick the robot and the
solver, move the poses to the robot's TCP, run the solver and follow it.

```sh
qualia dataset poses <dataset>                   # root | tcp | recorded, the calibration, the capture gripper
qualia dataset setup <dataset> --robot <robot> --solver pyroki   # or dls; robot follows the robot's model
qualia dataset setup <dataset> --base 0 0 0 --heading 0          # placement: metres, degrees
qualia dataset setup <dataset> --robot <robot> --wait            # stay for the resolve
qualia dataset setup <dataset> --run-solver                      # press Run solver (never started by itself)
qualia check reach-status <dataset>              # settings, last run, takes solved, stale
qualia check reach-cancel <dataset>              # stop it; solved takes keep their results
```

Only what you pass is written, and repeating a command writes nothing. Picking
a robot with `--robot` also **starts the resolve at the TCP** when the dataset
is an upload with handheld poses, every arm of the robot has a TCP, the
workspace has a gripper for the upload's rig with a calibration, and the poses
are not at the TCP yet (or are there with another calibration). The resolve
uses that capture gripper's calibration, not the robot's own gripper's; a robot
with no TCP leaves the poses at the gripper root and says so. `--no-resolve`
never resolves, `--resolve` resolves whatever the robot.

A resolve re-derives the whole upload (minutes to hours). Without `--wait` the
command prints the operation and returns; follow it later, or move the poses by
hand:

```sh
qualia dataset poses <dataset> --follow <operation-id>           # wait for a started resolve
qualia dataset poses <dataset> --at tcp --wait                   # resolve (again) at the TCP
qualia dataset poses <dataset> --at tcp --gripper <gripper-id>   # with another gripper's calibration
qualia dataset poses <dataset> --at root                         # back to the gripper root
```

Progress goes to stderr, so `--json` stays one document on stdout.

### Robots and their grippers

`qualia robot` registers robots, imports their URDFs and gives a robot a gripper of
its own to line up and set the jaw of; copy the robot to try another gripper.
Every subcommand and option is in the
[command reference](https://docs.qualiastudios.dev/cli/commands/#qualia-robot).

### JSON output

All commands support `--json` for machine-readable output:

```sh
qualia project list --json
qualia credit --json
```

## API

The CLI is a client for the public Qualia API. Request and response shapes for every command are
in the API reference: https://docs.qualiastudios.dev

Working in the repo instead? `sdk/cli/qualia-cli.spec.md` carries the same contract, and the
gateway generates the OpenAPI spec it is drawn from. Neither ships in the wheel.

## License

MIT, Qualia Studios.

A saved merge destination is used only with a known matching account, normalized
API host and workspace. An environment API key alone does not confirm the saved
account; supply the matching account configuration explicitly. Explicit
`--merge-target` and `--standalone` retain their per-call meaning.
