Commands

Global Options

These flags can be used with any command:

Option	Description
`--token`	API key (overrides config file and env var)
`--base-url`	API base URL (overrides config file and env var)

qualia --token <API_KEY> credit
qualia --base-url http://localhost:8004 auth status

`qualia version`

Show CLI and SDK versions.

qualia version

`qualia auth`

`qualia auth login`

Save your API key for future use. Prompts for the key interactively.

qualia auth login

Option	Description
`--api-key`	API key (prompted if omitted)
`--base-url`	Override API base URL

`qualia auth status`

Check current authentication configuration.

qualia auth status

`qualia credit`

Show your current credit balance.

qualia credit
qualia credit --json

`qualia dataset`

`qualia dataset list`

List the datasets in your account, in stable name order.

qualia dataset list
qualia dataset list --search openarm --dataset-type lerobot_v3
qualia dataset list --limit 50 --json

Option	Description
`--limit`, `-n`	Page size, 1–100 (default 20)
`--cursor`	Pagination cursor printed by the previous page
`--search`, `-q`	Search dataset path
`--dataset-type`	Filter: `lerobot_v2_1`, `lerobot_v3`, or `mcap_ros2`

`qualia dataset upload`

Publish a local dataset directory as a pinned DatasetVersion. Bytes go straight to storage; Qualia verifies the manifest and publishes the two together. Episodes become visible only once that publication succeeds.

qualia dataset upload ./my-recording my-dataset --source-format lerobot_v3

--source-format is required and takes lerobot_v2_1, lerobot_v3, or mcap_ros2. LeRobot 2.1 is never aliased or converted to v3 — name it explicitly so its source provenance stays distinct.

An mcap_ros2 upload expects a recorded session: one subdirectory per episode, each holding a single .mcap and, optionally, an episode.json sidecar carrying task and mode fallbacks.

Option	Description
`--source-format`	Source layout (required)
`--upload-workers`	Files read and chunked concurrently (default 4)
`--chunk-threads`	Native chunk/hash threads (default ≈ half your cores)
`--quiet`	Silence the live per-phase progress on stderr

Progress is written to stderr, so --json output stays pipeable. The server-side phases are bounded by silence rather than elapsed time: ingest parses every bag and transcodes every camera, so a large upload is free to take as long as it takes. See Configuration for the two environment variables that govern that wait.

`qualia dataset download`

Download a dataset’s published files into a local directory.

qualia dataset download my-dataset
qualia dataset download my-dataset ./somewhere-else

DEST defaults to ./<name>. To render one immutable pin as a verified LeRobot v3 tree instead, use qualia dataset materialize.

`qualia dataset import-hf`

Import one exact Hugging Face dataset commit server-side. The command confirms the pinned coordinates, submits them once, and polls while Hub bytes stream straight into storage. Success creates a pinned immutable DatasetVersion.

export HF_TOKEN="..." # optional for public datasets
qualia dataset import-hf \
  qualia-robotics/openarm-cube-in-box-v1 \
  17c29c487d886878ddcb3c5649101b2860fbc047 \
  openarm-cube-in-box \
  --source-format lerobot_v3

The revision must be lowercase 40-hex; branches, tags, URLs, and embedded credentials are rejected. HF_TOKEN is read only from the environment and is never accepted as a command-line option, printed, or sent in poll requests. Local file/byte/work-directory switches do not exist because no dataset body or scratch file touches the CLI machine. --json requires --yes so stdout stays valid JSON.

`qualia dataset curation-suggest`

Explain bad-data recommendations for immutable DatasetVersions without mutating them. Use --page-token to continue the result set.

qualia dataset curation-suggest <DATASET_VERSION_UUID>
qualia dataset curation-suggest <DATASET_VERSION_UUID> --json

`qualia dataset curate`

Publish the reviewed analysis’s sealed recommendation set as a new immutable DatasetVersion. Supply a stable idempotency UUID. Source bytes and Git history are not deleted.

qualia dataset curate <DATASET_VERSION_UUID> \
  --definition-id <DATASET_DEFINITION_UUID> \
  --idempotency-key <OPERATION_UUID> \
  --yes

Omit --yes for an interactive confirmation.

`qualia dataset materialize`

Render and download one immutable DatasetVersion as a verified LeRobot v3 directory. Transfer bytes go directly from object storage; the CLI validates every artifact and atomically publishes a new destination.

qualia dataset materialize <DATASET_VERSION_UUID> ./training-set-v7
qualia dataset materialize <DATASET_VERSION_UUID> ./training-set-v7 --json

Argument	Description
`DATASET_VERSION_ID`	Immutable dataset-version UUID (required)
`DEST`	New destination directory; must not already exist

`qualia dataset training-features`

Show the exact camera, stream, timebase, and frame-timestamp descriptors for one immutable DatasetVersion.

qualia dataset training-features <DATASET_VERSION_UUID>
qualia dataset training-features <DATASET_VERSION_UUID> --json

Argument	Description
`DATASET_VERSION_ID`	Immutable dataset-version UUID (required)

`qualia dataset markers`

Show the recorder markers inside one episode, in time order. Every edit command below cuts on these labels, so this is how you find out what a recording actually wrote.

qualia dataset markers <EPISODE_UUID>
qualia dataset markers <EPISODE_UUID> --json

An ingest that carried no marker topic reports that instead of an empty table.

`qualia dataset split`

Cut episodes into children at their own markers. Additive and exactly reversible: children are new episodes, the parents are untouched, and dataset unsplit removes them again.

qualia dataset split <EPISODE_UUID> --cut-at grasp
qualia dataset split <EPISODE_UUID> <EPISODE_UUID> --cut-at grasp --dry-run

Option	Description
`--cut-at`	Marker label to cut at, as the recording wrote it
`--start-at-first`	Drop the lead-in, up to the FIRST marker so labelled
`--end-at-last`	Drop the run-out, after the LAST marker so labelled
`--dry-run`	Plan the cuts without writing them

Name at least one label across --cut-at, --start-at-first or --end-at-last. The narrowing options apply before the cut, which is how a lead-in is dropped; given alone, each episode becomes one trimmed child. All three accept repeats.

`qualia dataset unsplit`

Delete the children of split episodes, undoing the split exactly.

qualia dataset unsplit <PARENT_EPISODE_UUID>

`qualia dataset trim`

Trim episodes to their own markers, reversibly. Each episode is narrowed to start at ITS first named marker and end at ITS last. The base extent never changes, so --clear restores it.

qualia dataset trim <EPISODE_UUID> --start-at-first ready --end-at-last done
qualia dataset trim <EPISODE_UUID> --clear

Option	Description
`--start-at-first`	Trim the lead up to the FIRST marker so labelled
`--end-at-last`	Trim the tail after the LAST marker so labelled
`--clear`	Restore the full extent instead of trimming
`--note`	Commit message for the revision

--clear restores the full extent and takes no labels; passing both is an error.

`qualia dataset subtasks`

Name each episode’s subtask spans from its own markers — the same boundary rule dataset split cuts on, used to label a span instead of carving it, so a whole selection can be named at once.

qualia dataset subtasks <EPISODE_UUID> --at grasp --at place
qualia dataset subtasks <EPISODE_UUID> --at grasp --starts-at

Option	Description
`--at`	Marker label whose presses bound a subtask (required, repeats)
`--starts-at`	Each marker OPENS the span it names (default: it closes it)
`--note`	Commit message for the revision

`qualia git`

`qualia git install`

Enable fast large-file transfer for a cloned Qualia dataset repo. Run it once inside the clone; it configures the Git filter and adds the tracked patterns to .gitattributes, after which large files sync chunk-by-chunk instead of moving whole.

git clone https://api.qualiastudios.dev/git/<org>/<name>.git
cd <name>
qualia git install

Option	Description
`--path`	Path to the cloned dataset repo (default `.`)

Tracked by default: *.safetensors, *.gguf, *.parquet, *.mp4, *.mcap, *.bag, *.npz, *.npy, *.pt, *.bin, *.tar, *.zip. Patterns already present in .gitattributes are left alone.

The clone’s origin must be the same endpoint the CLI is configured against — the filter refuses a repo whose remote points somewhere other than the configured base URL, so a repo cloned from one environment cannot be pushed to another by changing the URL.

Without an API key the filter cannot move data; qualia git install says so rather than failing later inside a git command.