Arxi CLI and Operator Workflows Architecture

Audience: Engineers extending CLI behavior and operators automating Arxi with machine output.

Executive Overview
Command Surface and Routing
Runtime Resolution Model
Operational Workflows
Output and Localization Model
Input Hard Limits and Fail-Closed Behavior
Exit Code Semantics
File-by-File Cross Reference

Executive Overview

arxi is the operational boundary for local Arxi workflows. It orchestrates arxi-recorder and arxi-store with explicit command groups and deterministic JSON mode for automation.

F:crates/arxi-cli/src/main.rs L137-L187 F:crates/arxi-cli/src/main.rs L864-L909 F:crates/arxi-cli/src/commands.rs L19-L29 F:crates/arxi-cli/src/support.rs L19-L23

Command Surface and Routing

Top-level command groups:

recorder (segment + envelope operations),
recorder envelope record-with-attachments (attachment-aware ingest),
recorder signer (explicit signing-key rotation lifecycle),
query (envelope retrieval),
bundle (build/verify/inspect),
config (runtime config checks),
contract (generated contract artifact generate/check),
decision-gate (fixture ingest via production adapter),
doctor (store and active-segment diagnostics).

F:crates/arxi-cli/src/main.rs L137-L272

Dispatch architecture uses explicit subcommand routers rather than implicit handler matching, with command implementations split by workflow area. F:crates/arxi-cli/src/main.rs L913-L980 F:crates/arxi-cli/src/commands.rs L19-L29

Runtime Resolution Model

Runtime settings are resolved with precedence:

CLI flags,
optional config file,
defaults.

Important defaults:

store_path: arxi.db
recorder_id: arxi-cli
schema_version: current schema
auto_seal: none unless explicit count and/or duration provided
query.limit: default 1000, max 10000
security_profile: secure

Signer runtime model:

profile-aware signer loading (secure, standard, dev),
secure default requiring encrypted PKCS#8 key material,
explicit opt-down for plaintext/dev seed in dev,
persisted rotation metadata (store_meta) with consistency checks.

F:crates/arxi-cli/src/main.rs L102-L126 F:crates/arxi-cli/src/support/runtime.rs L20-L122 F:crates/arxi-cli/src/support/runtime.rs L247-L556

Store backend selection:

file-backed SQLite or in-memory SQLite. F:crates/arxi-cli/src/support/runtime.rs L124-L179

Operational Workflows

Representative workflows map directly to command handlers:

open/record/seal/status/list segment lifecycle,
record envelopes with attachment file and inline base64 inputs (record-with-attachments),
explicit key rotation (recorder signer rotate) with deterministic system.adapter.key_rotated evidence emission,
filtered envelope queries with cursor support,
bundle build from selector JSON, verify (optionally with trust root), and inspect,
contract projection generation/check (contract generate|check),
Decision Gate transcript/runpack fixture ingest through production adapter.

F:crates/arxi-cli/src/commands/recorder.rs L20-L524 F:crates/arxi-cli/src/commands/query.rs L20-L88 F:crates/arxi-cli/src/commands/bundle.rs L20-L170 F:crates/arxi-cli/src/commands/admin.rs L20-L194

Integration tests cover baseline workflows and fail-closed cases. F:crates/arxi-cli/tests/commands.rs L78-L191 F:crates/arxi-cli/tests/commands.rs L193-L219

Output and Localization Model

Output modes:

--json: structured deterministic payloads for automation,
text mode: localized operator messaging.

JSON-mode query contract now emits:

{"envelopes": [...], "next_cursor": ..., "applied_limit": ...}.

JSON-mode failures emit a deterministic envelope:

{"error": "<message>"}.

Locale resolution:

--lang overrides ARXI_LANG,
supported locales: en, ca,
fallback to English on missing keys.

F:crates/arxi-cli/src/main.rs L102-L103 F:crates/arxi-cli/src/support/util.rs L19-L31 F:crates/arxi-cli/src/support/util.rs L301-L345 F:crates/arxi-cli/src/i18n.rs L26-L63 F:crates/arxi-cli/src/i18n.rs L336-L356

Input Hard Limits and Fail-Closed Behavior

CLI enforces bounded file reads:

config: 1 MiB,
payload JSON: 4 MiB,
attachment file/inline payload: 16 MiB,
Decision Gate fixture JSON: 8 MiB,
selector JSON: 1 MiB,
bundle JSON: 32 MiB,
trust-root JSON: 1 MiB,
signer key file: 64 KiB,
signer passphrase material: 1 KiB.

F:crates/arxi-cli/src/main.rs L108-L123

Oversized inputs are rejected before parsing/processing. F:crates/arxi-cli/src/support/util.rs L225-L277

bundle verify can load an explicit trust root and route it to Verifier::with_trust_root, enabling in-CLI signature trust-policy checks. F:crates/arxi-cli/src/commands/bundle.rs L74-L116

System-test coverage now validates:

oversized config/selector/bundle/trust-root input rejection,
oversized signer key/passphrase input rejection,
malformed identifier fail-closed behavior with no recorder mutation,
recorder-id shape validation parity in JSON-mode config validate,
auto-seal duration and combined lifecycle behavior via real CLI workflows,
record-with-attachments success roundtrip and hostile-input fail-closed behavior with no recorder mutation,
query JSON pagination contract (applied_limit + next_cursor) and over-limit fail-closed guardrails,
Decision Gate CLI ingest-fixture success and strict-fail mismatch behavior,
secure signer-file policy enforcement (symlink + permissions),
signer-rotation recovery and corrupted metadata fail-closed behavior,
contract CLI symlink output-root rejection,
hostile bundle-verify parse-boundary rejection for invalid attachment content type. F:system-tests/tests/suites/operations.rs L238-L570 F:system-tests/tests/suites/recorder.rs L333-L678 F:system-tests/tests/suites/security.rs L267-L1024 F:system-tests/tests/suites/integration_decision_gate.rs L935-L1161

Exit Code Semantics

General command errors return exit code 1 via emit_error.
JSON-mode command errors still return exit code 1 with machine-parseable {"error": ...} payload.
bundle verify returns exit code 2 when verdict status is Invalid.

F:crates/arxi-cli/src/support/util.rs L343-L345 F:crates/arxi-cli/src/commands/bundle.rs L112-L114

File-by-File Cross Reference

Area	File	Notes
CLI entry and dispatch	`crates/arxi-cli/src/main.rs`	Clap model, locale/bootstrap flow, top-level dispatch routing.
Command handlers	`crates/arxi-cli/src/commands.rs`	Aggregates command-group handler modules.
Recorder handlers	`crates/arxi-cli/src/commands/recorder.rs`	Segment/envelope operations and signer rotation logic.
Query and bundle handlers	`crates/arxi-cli/src/commands/query.rs`, `crates/arxi-cli/src/commands/bundle.rs`	Query filters and bundle build/verify/inspect workflows.
Admin handlers	`crates/arxi-cli/src/commands/admin.rs`	Config validate, doctor diagnostics, contract commands.
Runtime and utility helpers	`crates/arxi-cli/src/support.rs`, `crates/arxi-cli/src/support/runtime.rs`, `crates/arxi-cli/src/support/util.rs`	Runtime resolution, signer policy, parsing, bounded IO, output helpers.
i18n catalog	`crates/arxi-cli/src/i18n.rs`	Locale resolution and message template infrastructure.
CLI integration tests	`crates/arxi-cli/tests/commands.rs`	End-to-end workflow coverage for CLI semantics.
Contract generator integration	`crates/arxi-contract/src/lib.rs`	Deterministic generated artifact authority consumed by CLI contract commands.
System-test operations suite	`system-tests/tests/suites/operations.rs`	Validates config-validate parity checks and query JSON pagination/limit contract behavior.
System-test recorder suite	`system-tests/tests/suites/recorder.rs`	Validates auto-seal count/duration/combined lifecycle and attachment-recording roundtrip behavior.
System-test security suite	`system-tests/tests/suites/security.rs`	Validates fail-closed CLI boundary behavior across limits, attachment hostility, signer policy, rotation recovery, contract path safety, and hostile bundle inputs.
System-test Decision Gate CLI suite	`system-tests/tests/suites/integration_decision_gate.rs`	Validates production-adapter CLI ingest-fixture success and strict-fail mismatch behavior.