CLI reference

CLI reference

The CLI is not publicly distributed. Commands on this page are reference examples, not instructions you can run today. This page is a command overview, not the complete command reference: it lists the commands used most in evaluation. Settings and precedence live in the configuration reference. Current acquisition status is described on the installation page.

Approved Aarmos users, evaluators and customers alike, have the complete usage for their installed release built into the CLI — aarmos help and aarmos <command> --help — and in the Aarmos Technical Reference, which Aarmos provides to approved users.

Set up

Get a workspace, keys, and device identity in place.

  • aarmos init

    Scaffold a policy and configuration, and set up the workspace publisher identity.

  • aarmos doctor

    Diagnose configuration, environment, and the runtime session.

  • aarmos config explain

    Show every recognised setting, its resolved value, and where it came from — flag, env var, workspace file, user file, or default.

  • aarmos keys

    Generate and inspect signing keys.

  • aarmos login

    Associate this installation with a workspace. Association records where an installation belongs — it returns no capabilities, no entitlement, and no token, and a machine that never logs in governs identically.

  • aarmos whoami

    Show the local workspace association, if any.

  • aarmos logout

    Remove the local workspace association. Governance on this machine is unaffected.

Run under policy

Put real agent traffic through the gate.

  • aarmos run <target>

    Run a command with the policy gate attached.

  • aarmos proxy

    Start the hostname-scoped egress proxy (loopback-only).

  • aarmos env

    Print authenticated proxy exports for the running session.

  • aarmos approvals

    Human contributions to a paused attempt: list, show, approve, reject, revoke.

  • aarmos status

    Report whether known runtimes are governed right now, and why not when they are not.

Author policy

Record what your agent does, then turn it into enforceable rules.

  • aarmos record -- <cmd>

    Observe a run in shadow mode.

  • aarmos synth --from <file>

    Synthesize a candidate policy from a recording.

  • aarmos policy promote

    Sign and promote a reviewed candidate.

  • aarmos lint

    Validate ASP policy YAML.

  • aarmos test

    Run policy test cases.

  • aarmos eval

    Compare a baseline policy and a candidate policy offline over recorded receipts, and report where the two would decide differently.

Prove

Verification and replay — offline-capable.

  • aarmos activity

    Read-only view of recent governed actions from local receipts.

  • aarmos verify <path>

    Verify a receipt or .avar.zip bundle offline. Same verification core the browser verifier runs.

  • aarmos incident

    Assemble an incident evidence package.

  • aarmos replay

    Deterministically replay a recorded decision.

Local runtime

The runtime binds loopback (or a Unix socket / named pipe) only; non-loopback addresses are refused. Every local client connection is authenticated against the current runtime session, and sessions expire. aarmos doctor shows the active session.

Exit codes

Fatal startup failures the runtime recognizes exit with one of the codes below, prints what it found, and names the next action instead of a stack trace. These numbers are stable; scripts and CI can depend on them.

  • exit 10

    Configuration is invalid — an unrecognised or unparseable setting.

  • exit 11

    The requested port is unavailable — something else holds it.

  • exit 12

    The runtime is not permitted to bind there.

  • exit 13

    A required certificate is unavailable.

  • exit 14

    The workspace is unavailable — missing, read-only, or not writable.

  • exit 15

    A required identity is unavailable.

  • exit 16

    Evidence could not be durably committed — nothing was recorded.

  • exit 17

    Another runtime already governs this evidence corpus.

  • exit 18

    Evidence is not ready to govern a consequence — the evidence obligation cannot be satisfied right now.

  • exit 19

    The execution attempt could not be entered — the decision stood, but the runtime did not enter the execution boundary. Nothing was sent.

  • exit 20

    An unresolved prior execution blocks this dispatch — the runtime does not repeat an attempt whose outcome is not yet known.

aarmos verify carries the verification result in its exit code instead — the same result the browser verifier produces for the same receipt.

  • exit 0

    Verified.

  • exit 1

    Failed — a signature, hash chain, fingerprint, or content digest did not hold.

  • exit 2

    Unable — the requested file was not found, so no verification result was stated.

  • exit 3

    Failed — a pre-execution obligation aborted the action, or the required origin did not match.

  • exit 4

    Failed — the recorded action was denied by policy.

  • exit 5

    Failed — governance reconciliation did not hold.

  • exit 6

    Unable — input was unreadable or malformed, or its spec major is unsupported; no verification result was stated.

Related