CLI Reference¶
Complete reference for all grace commands, arguments, and options.
This page is auto-generated from the Typer application source code. It is always in sync with the installed version.
grace¶
Operator CLI for Cyber Grace workflows.
Usage¶
grace [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--env, -e |
Target environment name. | No | - |
--output, -o |
Output format: table or json. | No | table |
--verbose, -v |
Enable verbose output. | No | False |
--quiet, -q |
Suppress non-essential output. | No | False |
--version |
Show version. | No | - |
--install-completion |
Install completion for the current shell. | No | - |
--show-completion |
Show completion for the current shell, to copy it or customize the installation. | No | - |
Commands¶
| Name | Description |
|---|---|
auth |
Authentication management. |
device |
Device operations. |
data |
Cross-environment data operations. |
reclaim |
Storage-reclaim planning (read-only; emits... |
steps |
Video-step operations (supervisor). |
segmentations |
Segmentation result sets (read-only). |
Subcommands¶
auth¶
Authentication management.
Usage¶
grace auth [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
login¶
Store credentials for an environment.
Usage¶
grace auth login [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--env |
Environment to authenticate against. | No | - |
logout¶
Remove stored credentials for an environment.
Usage¶
grace auth logout [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--env |
Environment to remove credentials for. | No | - |
status¶
Show credential and connectivity status for all environments.
Usage¶
grace auth status [OPTIONS]
Arguments¶
No arguments available
Options¶
No options available
device¶
Device operations.
Usage¶
grace device [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
list¶
List devices with optional filtering.
Usage¶
grace device list [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--page, -p |
Page number. | No | 1 |
--size, -s |
Page size. | No | 20 |
--filter, -f |
Filter expressions (key:op:value). | No | - |
get¶
Get detailed info for a single device.
Usage¶
grace device get [OPTIONS] DEVICE_ID
Arguments¶
| Name | Description | Required |
|---|---|---|
DEVICE_ID |
Device UUID. | Yes |
Options¶
No options available
register¶
Register a new device.
Usage¶
grace device register [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--name, -n |
Device name. | Yes | - |
--type, -t |
Device type. | Yes | - |
--device-no |
Device number. | No | - |
--vendor-id |
Vendor UUID. | No | - |
--readable-name |
Human-readable name. | No | - |
--info-file |
JSON file with device info. | No | - |
update¶
Update an existing device with diff preview and confirmation.
Usage¶
grace device update [OPTIONS] DEVICE_ID
Arguments¶
| Name | Description | Required |
|---|---|---|
DEVICE_ID |
Device UUID to update. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--name, -n |
New device name. | No | - |
--device-no |
New device number. | No | - |
--vendor-id |
New vendor UUID. | No | - |
--readable-name |
New readable name. | No | - |
--info-file |
JSON file with updated device info. | No | - |
--yes, -y |
Skip confirmation. | No | False |
data¶
Cross-environment data operations.
Usage¶
grace data [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
copy¶
Additive copy of records from source to target environment.
Creates new records in target. Skips records that already exist (by UUID). Does NOT update, delete, or reconcile existing records.
Usage¶
grace data copy [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--source, -s |
Source environment name. | Yes | - |
--target, -t |
Target environment name. | Yes | - |
--entity |
Entity type to copy (devices, locations, vendors, videos). | Yes | - |
--filter, -f |
Filter expressions (key:op:value). | No | - |
--limit, -l |
Max records to copy. | No | - |
--dry-run |
Show what would be copied without executing. | No | False |
--clear-storage-meta |
Null out storage_meta on videos. | No | False |
download-qc¶
Download annotation inputs and QC metadata for videos.
Usage¶
grace data download-qc [OPTIONS] [VIDEO_IDS]...
Arguments¶
| Name | Description | Required |
|---|---|---|
VIDEO_IDS |
Video UUIDs to download. | No |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--source, -s |
Source environment name. | No | - |
--uuid-file |
File containing one video UUID per line. | No | - |
--output-dir |
Directory for downloaded data and QC metadata. | Yes | - |
--model-name |
QC model name, or 'none' for human QC. | No | none |
download-video¶
Download annotation inputs and full-length metadata for videos (no QC data).
Writes a single metadata segment per video spanning 0..duration (nanoseconds), with env/task set to "-". A summary table and download_report.csv are produced.
Usage¶
grace data download-video [OPTIONS] [VIDEO_IDS]...
Arguments¶
| Name | Description | Required |
|---|---|---|
VIDEO_IDS |
Video UUIDs to download. | No |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--source, -s |
Source environment name. | No | - |
--uuid-file |
File containing one video UUID per line. | No | - |
--output-dir |
Directory for downloaded data and metadata. | Yes | - |
transfer¶
Transfer videos and their related data between environments.
Copies videos plus segmentations and video_steps. Resolves devices by device_no and collectors by name. Optionally copies GCS files with --copy-files.
annotation_runs are planned and listed but NOT transferred: the service has no batch-create route for them, only the typed POST /annotation_runs/segmentation handlers, which a record replay cannot drive. The command warns when it skips them.
With --update, existing video records are compared against source and patched if they differ. Other entity types are always create-or-skip.
Usage¶
grace data transfer [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--source, -s |
Source environment name. | Yes | - |
--target, -t |
Target environment name. | Yes | - |
--filter, -f |
Filter expressions (key:op:value). | No | - |
--limit, -l |
Max videos to transfer. | No | - |
--dry-run |
Show what would be transferred without executing. | No | False |
--verbose, -v |
Show detailed record and file lists. | No | False |
--copy-files |
Also copy GCS blobs to target bucket. | No | False |
--target-gcs-bucket |
Override target GCS bucket (default: auto-derive by replacing env in bucket name). | No | - |
--update |
Compare existing videos field-by-field and update those that differ. | No | False |
--rewrite-existing-gcs |
With --copy-files --update, rewrite GCS URIs on existing matched records. | No | False |
backfill-provenance¶
Stamp provenance on videos already transferred to the target environment.
Reconciles target videos against the source by preserved id and stamps collection_meta.extra_info.provenance on transferred rows that lack it. Dry-run by default; pass --yes to apply.
This is a bulk patch meant for prod->dev provenance, so it refuses to run when --source and --target are the same, or when --target is a production-like environment (unless --allow-prod-target is given).
Usage¶
grace data backfill-provenance [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--source, -s |
Source (prod) environment name. | Yes | - |
--target, -t |
Target (dev) environment name. | Yes | - |
--yes |
Apply patches (default: dry run). | No | False |
--allow-prod-target |
Override the safety check that refuses a production-like --target. | No | False |
reclaim¶
Storage-reclaim planning (read-only; emits manifests, never deletes).
Usage¶
grace reclaim [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
candidates¶
List storage-reclaim candidates (read-only, paged).
Pages the reclaim-candidates endpoint to exhaustion and renders a table or JSON. Optionally filters client-side by action type. Never writes or deletes anything.
Usage¶
grace reclaim candidates [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--env, -e |
Environment to query (default: active). | No | - |
--camera-model |
Exact camera_model filter (e.g. CyberCap1). | No | - |
--action |
Filter to one action: RAW+DEFACE | FULL_PURGE | skip. |
--max |
Stop after scanning this many candidate ROWS across pages (applied before the --action filter). Default: all. | No | - |
--page-size |
Per-request page size (1..5000). | No | 1000 |
plan¶
Build a reclaim plan and atomically publish artifacts to --out directory.
Fetches all eligible candidates (non-skip), retrieves each video's storage manifest, and writes (atomically; a completion marker is written LAST):
gcs_objects.txt— REVIEW-ONLY inventory of candidate GCS objects (if any)aliyun_objects.txt— REVIEW-ONLY inventory of candidate Aliyun objects (if any)db_plan.json— the machine plan Phase-7 apply consumes (incl. excluded manifests)README.txt— operator instructionsRECLAIM_PLAN_COMPLETE— completion marker (absent ⇒ no valid plan)
Non-destructive: calls only read-only endpoints; emits NO executable script
and never calls a provider storage client — the operator runs the object
deletions manually (gsutil rm / ossutil rm), and the guarded Phase-7
grace reclaim apply later does DB cleanup only. Videos with incomplete
manifests (complete=false)
are EXCLUDED from the inventory but recorded in db_plan.json with a
prominent warning. Per-video manifest fetch errors are recorded and skipped;
other videos still proceed.
Exit 0 even when incomplete manifests, blocked videos, or fetch errors occur
— the artifacts and warnings convey the gaps, and a --max-truncated plan is a
valid, applyable subset. EXCEPTION: a cursor-stalled (partial) scan writes
its artifacts marked applyable:false and then exits NON-ZERO so automation
does not treat the untrustworthy scan as complete.
Usage¶
grace reclaim plan [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--out, -O |
Output directory for the manifest + plan artifacts. | Yes | - |
--env, -e |
Environment to query (default: active). | No | - |
--camera-model |
Exact camera_model filter (e.g. CyberCap1). | No | - |
--action |
Only plan this action: RAW+DEFACE | FULL_PURGE. | No |
--max |
Cap number of ELIGIBLE videos planned (non-skip, matching --action). Pages are consumed until this many planned videos are collected. | No | - |
--page-size |
Per-request page size (1..5000). | No | 1000 |
steps¶
Video-step operations (supervisor).
Usage¶
grace steps [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
reap¶
Preview stale running steps, then (on confirm) mark them failed with a reason.
Usage¶
grace steps reap [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--min-age |
Staleness threshold, e.g. 6h, 90m, 3600s. | Yes | - |
--reason |
Reason code (repeatable). | No | - |
--note |
Custom free-text reason. | No | - |
--step-key |
Filter by step key (repeatable). | No | - |
--task |
Filter by task name. | No | - |
--method |
Filter by method name. | No | - |
--video-id |
Filter by video id (repeatable). | No | - |
--status |
Stale status to sweep: running or pending. | No | ReapStatus.running |
--limit |
Safety cap on affected steps. | No | 500 |
--yes, -y |
Skip the confirmation prompt. | No | False |
segmentations¶
Segmentation result sets (read-only).
Usage¶
grace segmentations [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
runs¶
Select segmentation result sets (one immutable execution each) under an explicit policy.
Usage¶
grace segmentations runs [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--policy |
all: every matching set, newest first. latest_per_video: per video, the newest set AMONG those matching every other option. exact: the --run ids, in order. | No | SelectionPolicy.ALL |
--video, -V |
Video id; repeat or comma-separate (up to 100). Under exact, an expectation. | No | - |
--run, -r |
Run id to pin; repeat or comma-separate. Requires --policy exact. | No | - |
--step-key |
Producing step. Under exact, an expectation. | No | - |
--output-kind |
Result type, e.g. validation_span. Under exact, an expectation. | No | - |
--method-name |
Producing implementation name. | No | - |
--method-version |
Producing implementation version (matched exactly, never ordered). | No | - |
--source-system |
With --source-execution-id. | No | - |
--source-execution-id |
The producing execution, with --source-system. | No | - |
--created-after |
Inclusive lower bound; RFC3339 with an offset, e.g. 2026-09-20T00:00:00Z. | No | - |
--created-before |
Exclusive upper bound; RFC3339 with an offset. | No | - |
--page, -p |
Page number. | No | 1 |
--size, -s |
Page size (server clamps above 1000). | No | 100 |
--snapshot |
Page 1: keep a snapshot and print its id. | No | False |
--snapshot-id |
Continue a snapshot from page 1. | No | - |
--all |
Read every page on one stable snapshot. | No | False |
query¶
Query the segmentations of explicitly selected result sets, filtered server-side.
Usage¶
grace segmentations query [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--policy |
all: every matching set, newest first. latest_per_video: per video, the newest set AMONG those matching every other option. exact: the --run ids, in order. | No | SelectionPolicy.ALL |
--video, -V |
Video id; repeat or comma-separate (up to 100). Under exact, an expectation. | No | - |
--run, -r |
Run id to pin; repeat or comma-separate. Requires --policy exact. | No | - |
--step-key |
Producing step. Under exact, an expectation. | No | - |
--output-kind |
Result type, e.g. validation_span. Under exact, an expectation. | No | - |
--method-name |
Producing implementation name. | No | - |
--method-version |
Producing implementation version (matched exactly, never ordered). | No | - |
--source-system |
With --source-execution-id. | No | - |
--source-execution-id |
The producing execution, with --source-system. | No | - |
--created-after |
Inclusive lower bound; RFC3339 with an offset, e.g. 2026-09-20T00:00:00Z. | No | - |
--created-before |
Exclusive upper bound; RFC3339 with an offset. | No | - |
--frames |
Frame range START:END (half-open). | No | - |
--frames-within |
Spans inside --frames, not overlapping. | No | False |
--timestamps |
Timestamp range START:END (half-open). | No | - |
--timestamps-within |
Spans inside --timestamps, not overlapping. | No | False |
--payload |
Payload key match: KEY=VALUE (string) or KEY:=JSON (typed scalar). Repeatable. | No | - |
--type |
normal | calibration. Repeatable. | No |
--env |
Environment. Repeatable. | No | - |
--task |
Task. Repeatable. | No | - |
--status |
inprogress | done. Repeatable. | No |
--include-deleted |
Include soft-deleted spans. | No | False |
--no-payload |
Lightweight records: no payload. | No | False |
--runs |
Show each result set's counts, including matched_count (its spans matching the query across all pages): a table, or {"record": "run"} lines with --all -o json. | No | False |
--size, -s |
Page size (default 500, max 2000). | No | - |
--cursor |
next_cursor from the previous page. | No | - |
--all |
Read every page on one stable resolution, streaming page by page (NDJSON with -o json); starts from --cursor when given. | No | False |