CLI how-to

The CLI is a protocol client. It does not build database connections, discover local runtimes, load dotenv profiles, cache bearer tokens, or accept credential and endpoint overrides.

Client-side checks

ahri-tre version --format json
ahri-tre doctor --strict --format json
ahri-tre --config /etc/ahri-tre/client.toml auth login --format json
ahri-tre --config /etc/ahri-tre/client.toml auth status --format json
ahri-tre --config /etc/ahri-tre/client.toml daemon start --format json
ahri-tre daemon version --format json
ahri-tre daemon doctor --format json
ahri-tre daemon status --format json
ahri-tre --config /etc/ahri-tre/client.toml auth logout --format json

auth login prints the browser authorization URL to standard error so JSON standard output remains one final safe status envelope. Upstream OIDC tokens, the polling capability, and the Runtime credential are excluded from normal output. auth status reports only safe Deployment, OIDC identity, and expiry metadata; auth logout revokes server authority before removing the ephemeral credential file.

Top-level version and doctor inspect only the local installation and do not select the Client document. daemon start selects and retains the immutable Client bootstrap; later daemon readiness commands inspect that local Managed runtime. Neither rendering the document nor local daemon diagnostics proves Client readiness. Record that only after a successful authenticated stable-protocol operation reaches the configured Trusted runtime. Failures are explicit; there is no local execution fallback.

Authenticated Sessions

With Runtime login and the Managed runtime active, select only logical profile and Session names:

ahri-tre execution-profile list
ahri-tre execution-profile select research
ahri-tre session open analysis
ahri-tre session status analysis
ahri-tre session close analysis

The Trusted runtime resolves the Execution profile and Datastore binding. The CLI receives safe identities, not database topology, Lake locations, Secret references, tokens, passwords, or reusable store handles.

Operator checks

Trusted operators use an Application document:

ahri-tre --config application.toml config validate
ahri-tre --config application.toml config show-effective \
  --for execution-profile --profile research
ahri-tre --config application.toml config preflight \
  --for execution-profile --profile research

Preflight reads only the target’s required Secrets and performs bounded checks. It never creates or repairs infrastructure.

Workflow commands

After profile selection and Session authorization, workflow commands operate on logical identifiers. Use the checked-in examples/cli_validation/governed-lifecycle-smoke.sh only against a disposable configured Datastore.