Contexta CLI Reference

This page documents the current embedded command-line surface for Contexta.

The canonical CLI name is contexta, and the command tree below uses that name throughout.

Recommended Reading Path

Use the CLI when you want to inspect, report, export, serve, or recover a local workspace from a shell. For write-path instrumentation, start with Python capture examples first:

1. Getting Started
2. Capture Evidence
3. Operations Guide

Scope Of This Reference

This page documents the command tree that is actually present in the repository today.

It does not document:

• future command groups proposed in migration planning but not yet implemented
• internal helper functions inside contexta.surfaces.cli
• hypothetical admin trees that are not part of the current parser

Global Options

The current parser supports these global options before the command:

Option	Meaning
--workspace <path>	workspace root, default .contexta
`--profile local	test`
--config <path>	external config patch file
--set key=value	direct config override, repeatable
`--format text	json`
--quiet	suppress non-result status lines where applicable

Example:

contexta --workspace .contexta --format json runs

Exit Behavior

Current CLI exit behavior is:

• 0 on success
• 1 on handled runtime errors
• 2 on argument parsing or usage errors

When --format json is used, handled errors are rendered as JSON on stderr.

Command Tree

contexta
|- runs
|- run
|  |- list
|  |- show
|  |- compare
|  |- compare-many
|  '- diagnose
|- lineage
|- search
|  |- runs
|  '- artifacts
|- compare
|- compare-multi
|- diagnostics
|- trend
|- aggregate
|- anomaly
|- alert
|- report
|  |- snapshot
|  '- compare
|- export
|  |- html
|  '- csv
|     |- runs
|     |- compare
|     |- trend
|     '- anomaly
|- serve
|  '- http
|- provenance
|  |- audit
|  '- diff
|- artifact
|  |- register
|  '- put
|- backup
|  '- create
|- restore
|  '- apply
|- recover
|  '- replay

Query And Investigation Commands

Examples in this section use canonical run refs where possible. The underlying implementation may also accept shorter run identifiers in some repository-local contexts, but canonical refs are the preferred public style.

runs

List runs directly from the current workspace.

contexta runs [--project NAME] [--status STATUS] [--after ISO] [--before ISO] [--limit N] [--offset N] [--sort started_at|ended_at|name] [--desc]

Alias:

• contexta run list

run show

Show one run snapshot.

contexta run show <run_id>

compare

Compare two runs.

contexta compare <left_run_id> <right_run_id>

Alias:

• contexta run compare <left_run_id> <right_run_id>

compare-multi

Compare multiple runs.

contexta compare-multi <run_id> <run_id> [...]

Alias:

• contexta run compare-many <run_id> <run_id> [...]

diagnostics

Diagnose one run.

contexta diagnostics <run_id> [--fail-on info|warning|error]

Alias:

• contexta run diagnose <run_id> [--fail-on ...]

lineage

Trace lineage for a subject reference.

contexta lineage <subject_ref> [--direction upstream|downstream|inbound|outbound|both] [--depth N]

Notes:

• upstream and downstream are accepted user-facing aliases
• the current implementation normalizes them onto inbound/outbound traversal directions

search

Search current workspace data.

Run search:

contexta search runs <text> [--project NAME] [--status STATUS] [--limit N]

Artifact search:

contexta search artifacts <text> [--kind KIND] [--limit N]

trend

Query a metric trend.

contexta trend <metric_key> [--project NAME] [--stage STAGE] [--status STATUS] [--after ISO] [--before ISO] [--limit N] [--offset N] [--sort started_at|ended_at|name] [--desc]

aggregate

Query an aggregate for one metric.

contexta aggregate <metric_key> [--project NAME] [--stage STAGE] [--status STATUS] [--after ISO] [--before ISO] [--limit N] [--offset N] [--sort started_at|ended_at|name] [--desc]

anomaly

Detect anomalies for one run.

contexta anomaly <run_id> [--metric KEY ...] [--project NAME] [--stage STAGE]

alert

Evaluate one threshold alert against one run.

contexta alert <run_id> --metric <metric_key> --operator gt|lt|gte|lte|eq|ne --threshold <value> [--stage STAGE] [--severity LEVEL]

Report And Export Commands

report snapshot

Build a report for one run snapshot.

contexta report snapshot <run_id> [--render markdown|json|html|csv] [--output PATH]

report compare

Build a report for one run comparison.

contexta report compare <left_run_id> <right_run_id> [--render markdown|json|html|csv] [--output PATH]

export html

Export HTML from either one run or one comparison.

contexta export html --run <run_id> [--output PATH]
contexta export html --left <left_run_id> --right <right_run_id> [--output PATH]

export csv

The current CSV export surface supports four subcommands.

Run list CSV:

contexta export csv runs [--project NAME] [--status STATUS] [--after ISO] [--before ISO] [--limit N] [--offset N] [--sort started_at|ended_at|name] [--desc] [--output PATH]

Comparison CSV:

contexta export csv compare <left_run_id> <right_run_id> [--output PATH]

Trend CSV:

contexta export csv trend <metric_key> [--project NAME] [--stage STAGE] [--status STATUS] [--after ISO] [--before ISO] [--limit N] [--offset N] [--sort started_at|ended_at|name] [--desc] [--output PATH]

Anomaly CSV:

contexta export csv anomaly <run_id> [--metric KEY ...] [--project NAME] [--stage STAGE] [--output PATH]

Delivery And Provenance Commands

serve http

Start the embedded HTTP server.

contexta serve http [--host HOST] [--port PORT]

Important note:

• the current command group is serve http
• there is no separate top-level ui group in the current parser

provenance audit

Audit one run for reproducibility-oriented provenance signals.

contexta provenance audit <run_id>

provenance diff

Compare run environments.

contexta provenance diff <left_run_id> <right_run_id>

Artifact Commands

The current artifact surface is intentionally narrow.

artifact register

Register an artifact into the artifact store.

contexta artifact register <artifact_kind> <source_path> --run <run_ref> [--stage <stage_ref>] [--artifact-ref <artifact_ref>] [--mode copy|move|adopt]

artifact put

Alias for artifact register.

contexta artifact put <artifact_kind> <source_path> --run <run_ref> [--stage <stage_ref>] [--artifact-ref <artifact_ref>] [--mode copy|move|adopt]

Important note:

• the current parser does not yet expose separate artifact verify, artifact export, or artifact import-package commands
• those broader flows belong to future CLI alignment work, not to the current embedded command surface

Backup, Restore, And Replay

backup create

Create a workspace zip backup.

contexta backup create [--label LABEL] [--output PATH_STEM]

Current behavior:

• the current CLI writes a zip archive
• when --output is provided, the archive is created at <PATH_STEM>.zip
• this is a lightweight workspace-level CLI helper in the prototype

restore apply

Restore or verify a backup archive.

contexta restore apply <backup_archive_path> [--target-workspace PATH] [--verify-only]

Important note:

• although the internal argument name is backup_ref, the current command expects a backup archive path

recover replay

Replay records from the record plane.

contexta recover replay [--mode strict|tolerant] [--run <run_ref>] [--stage <stage_ref>] [--record-type event|metric|span|degraded]

Output Modes

The global --format option controls whether command results are emitted as text or JSON.

contexta --format json runs
contexta --format json diagnostics run:demo.run-01

Some report and export commands also support command-local render choices such as --render html or --render json.

Current Prototype Notes

At the current prototype stage:

• public docs use the canonical command name contexta
• the current launcher is contexta
• the current parser supports the command groups documented here
• source-tree workflows may still need repository-local setup while packaging and console-script alignment is in progress

That means this page should be read as the current command contract for the embedded CLI surface, with honest acknowledgment that the final published launcher name is still catching up.