CLI Reference

The devqubit CLI helps you inspect runs, compare results, manage baselines, and export portable bundles.

If you’re new, start with Quickstart.

Run identifiers: Most commands accept <run> which can be either a run ID (ULID like 01JD7X...) or a run name (like baseline-v1). When using names, provide --project for disambiguation.

Quick Start

# List recent runs
devqubit list

# Show run details (by name or ID)
devqubit show baseline-v1 --project myproject

# Compare two runs
devqubit diff baseline-v1 candidate-v2 --project myproject

# Verify against baseline
devqubit verify nightly-run --project myproject

# Recover stale runs and clean up
devqubit doctor --auto
devqubit gc --older-than 90d --status FAILED

# Launch web UI
devqubit ui

Run Management

list

List recent runs with optional filters.

devqubit list [OPTIONS]

Options:

Option	Short	Description
`--limit`	`-n`	Number of runs to show (default: 20)
`--project`	`-p`	Filter by project name
`--adapter`	`-a`	Filter by adapter (qiskit, braket, cirq, pennylane)
`--status`	`-s`	Filter by status (FINISHED, FAILED, RUNNING, KILLED)
`--backend`	`-b`	Filter by backend name
`--group`	`-g`	Filter by group ID
`--name`		Filter by run name (exact match)
`--since`		Show runs created after this date (ISO 8601)
`--until`		Show runs created before this date (ISO 8601)
`--tag`	`-t`	Filter by tag (repeatable)
`--format`		Output format: `table` (default) or `json`

Examples:

# List last 50 runs
devqubit list --limit 50

# Filter by project and status
devqubit list --project bell-state --status FINISHED

# Filter by backend
devqubit list --backend ibm_brisbane

# Filter by tags (can combine multiple)
devqubit list --tag experiment=bell --tag validated

# Filter by run name
devqubit list --name baseline-v1 --project bell-state

# Time range filtering
devqubit list --project vqe --since 2026-01-01 --until 2026-01-31

# Output as JSON for scripting
devqubit list --format json

search

Search runs using query expressions with field operators.

devqubit search QUERY [OPTIONS]

Options:

Option	Short	Description
`--limit`	`-n`	Max results (default: 20)
`--project`	`-p`	Filter by project first
`--sort`	`-s`	Sort by field (e.g., `metric.fidelity`)
`--asc`		Sort ascending (default: descending)
`--format`		Output format: `table` or `json`

Query Syntax:

field operator value [and field operator value ...]

Operators:

Operator	Meaning	Example
`=`	Equals	`status = FINISHED`
`!=`	Not equals	`status != FAILED`
`>`	Greater than	`metric.fidelity > 0.9`
`>=`	Greater or equal	`params.shots >= 1000`
`<`	Less than	`metric.tvd < 0.05`
`<=`	Less or equal	`params.depth <= 10`
`~`	Contains (string)	`backend ~ ibm`

Queryable Fields:

Field	Description
`params.<n>`	Run parameters
`metric.<n>`	Logged metrics
`tags.<n>`	Run tags
`status`	Run status
`project`	Project name
`adapter`	SDK adapter
`backend`	Backend name

Examples:

# Find high-fidelity runs
devqubit search "metric.fidelity > 0.95"

# Combined conditions (AND only)
devqubit search "params.shots >= 1000 and metric.fidelity > 0.9"

# Sort by metric
devqubit search "status = FINISHED" --sort metric.fidelity

# Find runs on IBM backends
devqubit search "backend ~ ibm and status = FINISHED"

show

Display detailed information about a run.

devqubit show <run> [OPTIONS]

Options:

Option	Description
`--project`	Project name (required when using run name)
`--format`	Output format: `pretty` (default) or `json`

Output includes:

Run ID, project, adapter, status
Created/ended timestamps
Group and parent run (if applicable)
Backend and provider info
Fingerprint for reproducibility
Git provenance (branch, commit, dirty state)
Parameter and metric summaries
Artifact count

Examples:

# By run name
devqubit show baseline-v1 --project bell-state

# By run ID
devqubit show 01JD7X...

# Full JSON for programmatic access
devqubit show baseline-v1 --project bell-state --format json

delete

Delete a run from the workspace.

devqubit delete <run> [OPTIONS]

Options:

Option	Short	Description
`--project`	`-p`	Project name (required when using run name)
`--yes`	`-y`	Skip confirmation prompt

Example:

# Interactive confirmation
devqubit delete old-experiment --project myproj

# Non-interactive (for scripts)
devqubit delete 01JD7X... --yes

projects

List all projects in the workspace.

devqubit projects [OPTIONS]

Options:

Option	Description
`--format`	Output format: `table` (default) or `json`

Shows project name, run count, and baseline status.

Run Groups

Groups organize related runs (parameter sweeps, experiments).

groups list

List run groups.

devqubit groups list [OPTIONS]

Options:

Option	Short	Description
`--project`	`-p`	Filter by project
`--limit`	`-n`	Max results (default: 20)
`--format`		Output format: `table` or `json`

groups show

Show runs within a group.

devqubit groups show GROUP_ID [OPTIONS]

Options:

Option	Short	Description
`--limit`	`-n`	Max results (default: 50)
`--format`		Output format: `table` or `json`

Artifacts

artifacts list

List artifacts in a run.

devqubit artifacts list <run> [OPTIONS]

Options:

Option	Short	Description
`--project`	`-p`	Project name (required when using run name)
`--role`	`-r`	Filter by role (program, result, device_raw, envelope)
`--kind`	`-k`	Filter by kind substring
`--format`		Output format: `table` (default) or `json`

Example:

# List all artifacts
devqubit artifacts list baseline-v1 --project bell-state

# Filter by role
devqubit artifacts list baseline-v1 --project bell-state --role program

# Filter by kind
devqubit artifacts list baseline-v1 --project bell-state --kind openqasm

artifacts show

Display artifact content.

devqubit artifacts show <run> SELECTOR [OPTIONS]

Selector formats:

Index number: 0, 1, 2
Kind substring: counts, openqasm3
Role:kind pattern: program:openqasm3, result:counts

Options:

Option	Description
`--project`	Project name (required when using run name)
`--raw`	Output raw bytes to stdout (for piping)
`--format`	Output format: `pretty` (default) or `json`

Examples:

# Show by index
devqubit artifacts show baseline-v1 0 --project bell-state

# Show by kind
devqubit artifacts show baseline-v1 counts --project bell-state

# Show by role:kind
devqubit artifacts show baseline-v1 program:openqasm3 --project bell-state

# Export raw content
devqubit artifacts show baseline-v1 results --project bell-state --raw > output.json

artifacts counts

Display measurement counts from a run.

devqubit artifacts counts <run> [OPTIONS]

Options:

Option	Short	Description
`--project`	`-p`	Project name (required when using run name)
`--top`	`-k`	Show top K outcomes (default: 10)
`--experiment`	`-e`	Experiment index for batch jobs
`--format`		Output format: `table` (default) or `json`

Example:

# Show top 5 outcomes
devqubit artifacts counts baseline-v1 --project bell-state --top 5

# Show counts for second circuit in batch
devqubit artifacts counts baseline-v1 --project bell-state --experiment 1

Tags

Tags are key-value pairs for organizing and filtering runs.

tag add

Add tags to a run.

devqubit tag add <run> TAG [TAG ...] [OPTIONS]

Options:

Option	Short	Description
`--project`	`-p`	Project name (required when using run name)

Tags can be key=value pairs or just key (value defaults to “true”).

Examples:

# Add key=value tag
devqubit tag add baseline-v1 experiment=bell --project bell-state

# Add multiple tags
devqubit tag add baseline-v1 validated production device=ibm_brisbane --project bell-state

tag remove

Remove tags from a run.

devqubit tag remove <run> KEY [KEY ...] [OPTIONS]

Options:

Option	Short	Description
`--project`	`-p`	Project name (required when using run name)

Example:

devqubit tag remove baseline-v1 temp debug --project bell-state

tag list

List all tags on a run.

devqubit tag list <run> [OPTIONS]

Options:

Option	Description
`--project`	Project name (required when using run name)
`--format`	Output format: `pretty` (default) or `json`

Comparison & Verification

diff

Compare two runs or bundles comprehensively.

devqubit diff <run_a> <run_b> [OPTIONS]

<run_a> and <run_b> can be run names, run IDs, or bundle file paths.

Options:

Option	Short	Description
`--project`	`-p`	Project name (required when using run names)
`--output`	`-o`	Save report to file
`--format`		Output: `pretty` (default), `json`, or `summary`
`--no-circuit-diff`		Skip circuit semantic comparison
`--no-noise-context`		Skip bootstrap noise estimation (faster)
`--item-index`		Result item index for TVD (default: 0, use -1 for all)

Comparison includes:

Parameter differences
Circuit/program changes (structural and parametric hashes)
Device drift analysis (calibration deltas)
Total Variation Distance (TVD) with bootstrap-calibrated noise context

Examples:

# Compare two runs by name
devqubit diff baseline-v1 candidate-v2 --project bell-state

# Compare two runs by ID
devqubit diff 01JD7X... 01JD8Y...

# Compare bundles
devqubit diff experiment1.zip experiment2.zip

# Save report as JSON
devqubit diff baseline-v1 candidate-v2 --project bell-state --format json -o report.json

# Quick comparison (skip noise estimation)
devqubit diff baseline-v1 candidate-v2 --project bell-state --no-noise-context

# Compare all result items in batch
devqubit diff baseline-v1 candidate-v2 --project bell-state --item-index -1

verify

Verify a run against baseline with full root-cause analysis.

devqubit verify <run> [OPTIONS]

Options:

Option	Short	Description
`--baseline`	`-b`	Baseline run (name or ID; default: project baseline)
`--project`	`-p`	Project for baseline lookup (required when using run name)
`--tvd-max`		Maximum allowed TVD
`--noise-factor`		Fail if TVD > noise_factor × noise_p95 (recommended: 1.0-1.5)
`--program-match-mode`		`exact`, `structural`, or `either` (default)
`--no-params-match`		Don’t require parameters to match
`--no-program-match`		Don’t require program to match
`--strict`		Require fingerprint match
`--promote`		Promote to baseline on pass
`--allow-missing`		Pass if no baseline exists
`--junit`		Write JUnit XML report
`--format`		Output: `pretty` (default), `json`, `github`, or `summary`

Program Match Modes:

exact: require identical artifact digests
structural: require same circuit structure (VQE/QAOA friendly)
either: pass if exact OR structural matches (default)

Examples:

# Verify by run name against project baseline
devqubit verify nightly-run --project bell-state

# Verify against explicit baseline (by name)
devqubit verify candidate-v2 --baseline baseline-v1 --project bell-state

# With TVD threshold
devqubit verify nightly-run --project bell-state --tvd-max 0.05

# Bootstrap-calibrated threshold (recommended)
devqubit verify nightly-run --project bell-state --noise-factor 1.0

# VQE-friendly (ignore parameter values in circuit)
devqubit verify nightly-run --project vqe-h2 --program-match-mode structural

# Strict mode (fingerprint must match)
devqubit verify nightly-run --project bell-state --strict

# CI integration with JUnit output
devqubit verify nightly-run --project bell-state --junit results.xml

# GitHub Actions format
devqubit verify nightly-run --project bell-state --format github

# Promote on success
devqubit verify nightly-run --project bell-state --promote

# Relaxed verification (only check TVD)
devqubit verify nightly-run --project bell-state \
  --no-params-match --no-program-match --noise-factor 1.5

Bundles

Bundles are portable ZIP archives containing a run and all its artifacts.

pack

Create a bundle from a run.

devqubit pack <run> [OPTIONS]

Options:

Option	Short	Description
`--project`	`-p`	Project name (required when using run name)
`--out`	`-o`	Output file path (default: `<run_id>.devqubit.zip`)
`--force`	`-f`	Overwrite existing file
`--format`		Output format: `pretty` (default) or `json`

Examples:

# Pack by name
devqubit pack baseline-v1 --project bell-state

# Specify output path
devqubit pack baseline-v1 --project bell-state -o experiment.zip

# Pack by ID
devqubit pack 01JD7X... -o experiment.zip

# Overwrite existing
devqubit pack baseline-v1 --project bell-state -o experiment.zip --force

unpack

Extract a bundle into a workspace.

devqubit unpack BUNDLE [OPTIONS]

Options:

Option	Short	Description
`--to`	`-t`	Destination workspace
`--force`	`-f`	Overwrite existing run
`--verify/--no-verify`		Verify digests (default: verify)
`--format`		Output format: `pretty` (default) or `json`

Examples:

# Unpack to current workspace
devqubit unpack experiment.zip

# Unpack to specific workspace
devqubit unpack experiment.zip --to /path/to/workspace

# Skip verification (faster)
devqubit unpack experiment.zip --no-verify

info

Show bundle metadata without extracting.

devqubit info BUNDLE [OPTIONS]

Options:

Option	Description
`--format`	Output format: `pretty` (default) or `json`
`--objects`	List all object digests
`--artifacts`	List artifact details

Examples:

# Show basic info
devqubit info experiment.zip

# Show with artifact list
devqubit info experiment.zip --artifacts

# Full details as JSON
devqubit info experiment.zip --format json --objects --artifacts

Baselines

Baselines are reference runs for verification.

baseline set

Set the baseline run for a project.

devqubit baseline set PROJECT <run> [OPTIONS]

Options:

Option	Description
`--project`	Project context (required when using run name and it differs from PROJECT)

Examples:

# Set baseline by run name
devqubit baseline set bell-state baseline-v1

# Set baseline by run ID
devqubit baseline set bell-state 01JD7X...

baseline get

Get the current baseline for a project.

devqubit baseline get PROJECT [OPTIONS]

Options:

Option	Description
`--format`	Output format: `pretty` (default) or `json`

baseline clear

Clear the baseline for a project.

devqubit baseline clear PROJECT [OPTIONS]

Options:

Option	Short	Description
`--yes`	`-y`	Skip confirmation

baseline list

List all project baselines.

devqubit baseline list [OPTIONS]

Options:

Option	Description
`--format`	Output format: `pretty` (default) or `json`

Storage Management

storage gc

Garbage collect unreferenced objects.

devqubit storage gc [OPTIONS]

Options:

Option	Short	Description
`--dry-run`	`-n`	Preview without deleting
`--yes`	`-y`	Skip confirmation
`--project`	`-p`	Limit to specific project
`--format`		Output format: `pretty` (default) or `json`

Examples:

# Preview what would be deleted
devqubit storage gc --dry-run

# Delete orphaned objects
devqubit storage gc --yes

# Limit to specific project
devqubit storage gc --project myproject --dry-run

storage prune

Delete old runs by status.

devqubit storage prune [OPTIONS]

Options:

Option	Short	Default	Description
`--status`	`-s`	FAILED	Status to prune
`--older-than`		30	Days old threshold
`--keep-latest`		5	Keep N most recent matching runs
`--project`	`-p`		Limit to specific project
`--dry-run`	`-n`		Preview without deleting
`--yes`	`-y`		Skip confirmation
`--format`			Output format: `pretty` (default) or `json`

Examples:

# Preview pruning failed runs
devqubit storage prune --status FAILED --dry-run

# Prune runs older than 7 days, keep latest 3
devqubit storage prune --older-than 7 --keep-latest 3 --yes

# Prune only in specific project
devqubit storage prune --project old-experiments --yes

storage health

Check workspace health and integrity.

devqubit storage health [OPTIONS]

Options:

Option	Description
`--format`	Output format: `pretty` (default) or `json`

Reports:

Total runs and objects
Referenced vs orphaned objects
Missing objects (integrity issues)

Health & Maintenance

doctor

Detect and recover stale runs (stuck in RUNNING after a crash, OOM, or SSH disconnect).

devqubit doctor [OPTIONS]

Options:

Option	Short	Default	Description
`--older-than`		6h	Age threshold (e.g., `6h`, `30m`, `2d`)
`--auto`			Automatically mark stale runs as KILLED
`--project`	`-p`		Limit to specific project
`--dry-run`	`-n`		Preview without changing anything
`--format`		`pretty`	Output format: `pretty` or `json`

Examples:

# Preview stale runs (older than 6h by default)
devqubit doctor --dry-run

# Auto-recover stale runs
devqubit doctor --auto

# Custom threshold
devqubit doctor --auto --older-than 2h --project nightly-ci

gc

All-in-one cleanup: optionally prune old runs, then collect orphaned objects.

devqubit gc [OPTIONS]

Without --older-than, only orphaned objects are cleaned (safe default). With --older-than, old runs are pruned first, then orphans are collected.

Options:

Option	Short	Default	Description
`--older-than`			Prune runs older than this (e.g., `90d`, `24h`)
`--keep-last`		10	Always keep N most recent runs per project
`--status`	`-s`		Only prune runs with this status (e.g., FAILED)
`--project`	`-p`		Limit to specific project
`--dry-run`	`-n`		Preview without deleting
`--yes`	`-y`		Skip confirmation
`--format`		`pretty`	Output format: `pretty` or `json`

Examples:

# Clean orphaned objects only (safe)
devqubit gc

# Preview what would be pruned
devqubit gc --older-than 90d --dry-run

# Prune old failed runs, then clean orphans
devqubit gc --older-than 30d --status FAILED --yes

# Keep at least 50 runs per project
devqubit gc --older-than 7d --keep-last 50 --project nightly-ci

Configuration

config

Display current configuration.

devqubit config [OPTIONS]

Options:

Option	Description
`--format`	Output format: `pretty` (default) or `json`

Shows:

Workspace path
Storage and registry URLs
Capture settings (pip, git)
Validation and redaction settings

Web UI

ui

Launch the local web interface.

devqubit ui [OPTIONS]

Options:

Option	Short	Default	Description
`--host`		127.0.0.1	Host to bind to
`--port`	`-p`	8080	Port to listen on
`--workspace`	`-w`		Workspace directory
`--debug`			Enable debug mode

Note: Requires the devqubit-ui package (pip install devqubit[ui]).

Examples:

# Start on default port
devqubit ui

# Custom port
devqubit ui --port 9000

# Bind to all interfaces (for remote access)
devqubit ui --host 0.0.0.0

# Specify workspace
devqubit ui --workspace /path/to/.devqubit

Global Options

These options apply to all commands:

devqubit --root /path/to/.devqubit <command>

Option	Short	Description
`--root`	`-r`	Workspace root directory (default: ~/.devqubit)
`--quiet`	`-q`	Less output
`--version`		Show version
`--help`		Show help

Environment Variables

Variable	Description
`DEVQUBIT_HOME`	Default workspace root path
`DEVQUBIT_PROJECT`	Default project name
`DEVQUBIT_LOG_LEVEL`	Logging level (DEBUG, INFO, WARNING, ERROR)

Exit Codes

Code	Meaning
0	Success (or verification passed)
1	Failure (verification failed, run not found, etc.)
2	Error (invalid arguments, I/O error)

Common Workflows

CI/CD Verification

# Run experiment (in your code)
# ...

# Verify against baseline with bootstrap-calibrated threshold
devqubit verify nightly-run \
  --project $PROJECT \
  --program-match-mode either \
  --noise-factor 1.0 \
  --junit results.xml

# Exit code determines CI pass/fail

Workspace Maintenance

# Check health
devqubit storage health

# Recover stale runs
devqubit doctor --auto

# One-command cleanup: prune old failures + collect orphans
devqubit gc --older-than 30d --status FAILED

# Or step-by-step:
devqubit storage prune --status FAILED --older-than 30
devqubit storage gc

CLI Reference

Quick Start

Run Management

list

search

show

delete

projects

Run Groups

groups list

groups show

Artifacts

artifacts list

artifacts show

artifacts counts

Tags

tag add

tag remove

tag list

Comparison & Verification

diff

verify

Bundles

pack

unpack

info

Baselines

baseline set

baseline get

baseline clear

baseline list

Storage Management

storage gc

storage prune

storage health

Health & Maintenance

doctor

gc

Configuration

config

Web UI

ui

Global Options

Environment Variables

Exit Codes

Common Workflows

CI/CD Verification

Sharing Experiments

Workspace Maintenance