Skip to content

CLI Surface

The bijux-canon-runtime CLI exposes init and the local-first v2 product surface in top-level help. Older manifest commands remain parseable for compatibility but are not advertised to new users.

The v2 group is the installed local-first product surface. Its evaluate-retrieval command accepts reviewed question and qrel files plus one persisted index artifact. It does not accept ranked hits: every result is generated by the configured installed retriever and retained as a RuntimeRun.

Command map

Command Purpose Required authority
init --workspace WORKSPACE [--model MODEL] Atomically initialize a model-free lexical workspace or bind a verified local model for dense/hybrid work. new workspace parent; optional materialized model
v2 ready --operation OPERATION [--profile PROFILE] Report only the dependencies required by the named operation and profile. initialized workspace
v2 ingest DIRECTORY Prepare and retain an immutable corpus. initialized workspace and readable documents
v2 index CORPUS_ID Build the index required by the selected profile. retained corpus and profile dependencies
v2 search QUERY --index-id INDEX_ID Retrieve bounded evidence; retrieve is an automation-compatible alias. retained index
v2 ask QUERY --index-id INDEX_ID --corpus-id CORPUS_ID Produce a citation-required grounded answer. retained corpus and index
v2 research QUERY --index-id INDEX_ID --corpus-id CORPUS_ID Perform bounded counterevidence research. retained corpus and index
v2 run QUERY (--source-directory DIRECTORY | --corpus-id CORPUS_ID) Execute one linked ingest/index/retrieve/reason/agent workflow. initialized workspace and selected input
v2 status JOB_ID [--follow] / v2 result JOB_ID Inspect durable work or wait for terminal state, then resolve its result. retained job
v2 inspect RUN_ID Inspect a bounded summary page of the authoritative run record. retained run
v2 artifact-payload ARTIFACT_ID Deliberately read one checksum-bound payload page. retained artifact identity
v2 replay RUN_ID --source-attempt-id ATTEMPT_ID Submit a linked replay with explicit network policy. retained run and attempt
v2 compare BASELINE_RUN CANDIDATE_RUN ... Compare selected immutable attempts and dimensions. retained attempts
v2 backup BACKUP_ID / v2 restore GENERATION ROOT Back up or relocate the verified Runtime authority, including its database, admitted CAS inventory, workspace controls, indexes, and replay state. configured quiescent source workspace or absent restore root
v2 evaluate-retrieval Run reviewed questions through the installed persistent index and report exact retrieval evidence. initialized workspace, model, index artifact, cases, and qrels
v2 search-retrieval-configurations Execute the same installed development questions, then compare bounded identity-free RRF configurations without consulting held-out labels. initialized workspace, model, index artifact, development cases, and qrels

Operator workflow

bijux-canon-runtime init --workspace ./canon-workspace --json
export BIJUX_CANON_RUNTIME_WORKING_ROOT=./canon-workspace

bijux-canon-runtime v2 run \
  "What evidence does this corpus support?" \
  --source-directory ./documents \
  --profile offline-lexical \
  --wait \
  --wait-timeout-seconds 30

bijux-canon-runtime v2 result JOB_ID
bijux-canon-runtime v2 inspect RUN_ID --attempt-id ATTEMPT_ID --limit 20
bijux-canon-runtime v2 replay RUN_ID \
  --source-attempt-id ATTEMPT_ID \
  --network-policy disabled \
  --wait
bijux-canon-runtime v2 compare RUN_ID RUN_ID \
  --baseline-attempt-id ATTEMPT_ID \
  --candidate-attempt-id REPLAY_ATTEMPT_ID \
  --dimension outcome \
  --dimension claims \
  --dimension citations

Submission commands return immediately by default. --wait and status --follow use worker notification with an explicit timeout; they do not poll in an unbounded loop. A terminal job status deliberately remains separate from v2 result, so scripts never receive an unexpectedly large result document. By default, v2 successes and failures are a single JSON document; the explicit --human options on capability and evaluation reports select text instead. Exit 2 identifies an invalid request, 3 a missing capability, 4 an execution failure, and 5 an unready operation.

Run inspection returns counts for every collection and at most five items from each collection by default; an explicit page may request at most 100. Arbitrary persisted values larger than 512 bytes are represented by type, byte length, and SHA-256 rather than inlined. Use v2 artifact-payload ARTIFACT_ID with --offset and --max-bytes to read immutable payload bytes deliberately. Each payload page is at most 65,536 bytes and is base64 encoded with total size, digest, and continuation offset. HTTP uses the same bounds at GET /api/v2/artifacts/{artifact_id}/payload.

The top-level provenance object is a bounded, fail-closed traversal result. For each citation it identifies the parent durable job, run, execution configuration, optional model lock, index, corpus snapshot, retained source archive, document, chunk, portable relative source name, source digest, and verified source-byte spans. A verified status applies only when every causal dependency and retained payload resolves; runs created before source-archive retention report legacy-unresolved instead of claiming equivalent evidence.

Every submission command accepts strict --request FILE JSON as an alternative to direct options. backup authenticates an existing generation when the same identity is reused. A backup refuses queued or running jobs, missing admitted payloads, external model state, symlinks, or workspace files that change during capture. restore verifies every database, artifact, and workspace-file checksum, rewrites only governed machine-local workspace locations, preserves the logical workspace identity, and requires a destination that does not already exist. Direct directory copies remain unsupported.

Retrieval evaluation

bijux-canon-runtime v2 evaluate-retrieval \
  --cases examples/ancient-dna-research/truth/evaluation-cases.jsonl \
  --qrels examples/ancient-dna-research/truth/qrels.jsonl \
  --index-id sha256:INDEX_ARTIFACT \
  --split development \
  --mode local-hybrid-ann

The JSON report includes every raw ranked hit and exact locator segment, generation/model/configuration and VEX identities, Runtime run/attempt lineage, per-query arithmetic, macro distributions, pooled qrel counts, refusal/failure counts, stage-by-stage relevant-chunk ranks and loss classifications, and worst queries. --human prints the same report's denominators, headline metrics, and one compact stage line per reviewed question. A sealed held-out case is rejected rather than silently exposing release labels.

CLI and HTTP adapters pass only paths, identities, mode, split and bounds to the shared Runtime application operation. That operation loads reviewed truth, invokes the configured Index evaluator, and owns development configuration search. Transports neither construct evaluation truth nor rerank observations.

Use the same arguments with v2 search-retrieval-configurations to retain the installed observations and search candidate depth, symmetric lexical admission, RRF rank constants, and channel weights. The integrity-bound report keeps every configuration's per-query tradeoffs and applies the fixed 0.90 Recall@5, 0.85 MRR@10, and 0.85 nDCG@10 floors. It selects no configuration when none passes; the command never weakens thresholds, removes qrels, or uses query, source, or document identities as ranking features.

unsafe-run is present in the parser but is not currently executable through the CLI: unsafe execution requires a verification policy, while the subcommand does not accept --policy. Use the Python ExecutionConfig surface only when unsafe authority is explicitly required and governed.

Plan

bijux-canon-runtime plan \
  packages/bijux-canon-runtime/examples/boring/flow.json \
  --json

--db-path is optional and unnecessary for planning. Plan mode resolves and validates the manifest, prints the plan, and returns no trace or run ID. JSON output is the serialized execution plan; plain output reports flow, step count, and dataset.

Dry run

bijux-canon-runtime dry-run \
  packages/bijux-canon-runtime/examples/boring/flow.json \
  --db-path artifacts/bijux-canon-runtime/runs.duckdb \
  --json

Dry run requires a writable execution store but not a verification policy. It allocates a run, uses the dry-run executor, finalizes a trace, and persists the trace records. JSON output is the trace object. --strict-determinism is accepted, but the environment setting BIJUX_CANON_RUNTIME_STRICT=1 forbids dry-run entirely.

Live run

bijux-canon-runtime run \
  packages/bijux-canon-runtime/examples/boring/flow.json \
  --policy packages/bijux-canon-runtime/examples/boring/policy.json \
  --db-path artifacts/bijux-canon-runtime/runs.duckdb \
  --strict-determinism \
  --json

The manifest determines the effective determinism level. The policy determines verification rules, failure behavior, arbitration, evidence requirements, and cost limits. Live execution requires exactly one verification result per step unless a terminating verification failure is recorded.

Plain output reports run ID and aggregate counts. JSON output contains the trace, dataset identity, determinism profile, entropy use, replay confidence, artifacts, retrieval requests and evidence, reasoning claims, and verification summaries, but it currently omits the run ID. Use plain output when the caller must capture the identifier, then use inspect run --json for the persisted trace.

Configuration contract violations exit 2; classified execution failures exit 1. Manifest or policy parsing errors that occur before guarded execution may surface directly.

Replay

bijux-canon-runtime replay \
  packages/bijux-canon-runtime/examples/boring/flow.json \
  --policy packages/bijux-canon-runtime/examples/boring/policy.json \
  --run-id "$RUN_ID" \
  --tenant-id tenant-a \
  --db-path artifacts/bijux-canon-runtime/runs.duckdb \
  --strict-determinism \
  --json

Replay loads the stored trace, dataset descriptor, and replay envelope; resolves the supplied manifest; then performs a new live execution into the same store. It validates replay constraints and compares the new trace semantically with the stored trace. The new execution receives its own run ID.

JSON output normalizes timestamps and contains diff, the replay trace, and the new run ID. A non-empty diff prints its first reason code to stderr and exits 2. Plain output reports either Replay clean or the first reason code.

Read-side commands

bijux-canon-runtime inspect run "$RUN_ID" \
  --tenant-id tenant-a \
  --db-path artifacts/bijux-canon-runtime/runs.duckdb \
  --json

bijux-canon-runtime diff run "$RUN_A" "$RUN_B" \
  --tenant-id tenant-a \
  --db-path artifacts/bijux-canon-runtime/runs.duckdb \
  --json

bijux-canon-runtime explain failure "$RUN_ID" \
  --tenant-id tenant-a \
  --db-path artifacts/bijux-canon-runtime/runs.duckdb \
  --json

bijux-canon-runtime validate db \
  --db-path artifacts/bijux-canon-runtime/runs.duckdb \
  --json

diff run reports differences but does not fail the process when differences exist. explain failure returns only the last event among the recognized step, retrieval, reasoning, verification, tool, and interruption failure kinds. validate db proves that the store can be opened and its schema initialized; it is not a row-by-row integrity or semantic audit.

DuckDB access is single-writer. Do not run concurrent mutating commands against the same database path.