CLI reference

• aarmos init

  Scaffold a policy, config, and demo agent.

• aarmos doctor

  Diagnose configuration, environment topology (loopback, durability, exclusivity, clock), runtime session, and instance identity continuity.

• aarmos doctor --sovereignty

  Print the sovereignty manifest: declared claims (what the runtime asserts about local authority) alongside observed evidence collected on this machine. Attach the output to a procurement or audit review.

• 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 identity

  Show and manage the workspace identity.

• aarmos device

  Register and list trusted devices.

• aarmos invite

  Create and redeem workspace invites.

• aarmos enroll

  Prove the workspace is actually governed: resolve the policy set, send a live probe through the runtime, and report the enrollment state (DISCOVERED / CONFIGURED / ENROLLED / GOVERNED).

• aarmos dev

  Guided workspace walkthrough — set up, run something governed, and see the evidence it produced.

• aarmos run <target>

  Run a command with the policy gate attached.

• aarmos proxy

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

• aarmos env

  Print authenticated HTTPS_PROXY/HTTP_PROXY exports for the running session.

• aarmos daemon

  Run the local runtime as a background service.

• aarmos serve

  Run the runtime in the foreground (deployment mode): noninteractive identity, /healthz and /readyz, SIGTERM drains then flushes evidence before exit.

• aarmos demo

  Run the bundled demo agent end to end.

• aarmos resume

  Resume a suspended governed session. Approvals and facts are revalidated at resumption, not only when first accepted.

• aarmos admit

  Admit an external trigger as a governed Invocation, or refuse it with a stated reason. Aarmos is not a scheduler; this is the door your scheduler knocks on. admit log shows past admissions.

• aarmos approvals

  Human contributions to a paused attempt: list, show, approve, reject, revoke. Each contribution is bound to the attempt digest and the policy version in force.

• aarmos participants

  External systems that contribute facts to a decision (list, add, check, ask). Aarmos never hosts their rules and never fetches policy from them.

• aarmos status

  Report whether known runtimes are governed right now, and why not when they are not. --actors adds per-actor coverage, --require-governed turns a condition into a failing exit code. Also reports a measured governance-independence result: the same governed decision is executed under every entitlement state and the outcomes are compared (machine-readable under `governanceIndependence` in --json).

• 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 policy impact

  Re-judge recorded Decisions against a candidate policy before you promote it. Exit 0 no change, 2 changed, 3 insufficient evidence (--allow-insufficient downgrades that to a pass).

• aarmos lint

  Validate ASP policy YAML.

• aarmos test

  Run policy test cases.

• aarmos eval

  Evaluate a request against the active policy.

• aarmos activity

  Read-only view of recent governed actions from local receipts. Filters: --since, --status, --runs, --follow, --json.

• aarmos verify <path>

  Verify a receipt or .avar.zip bundle offline. --explain prints the plain-English rationale, --json emits the machine-readable report, --quiet leaves only the exit code. Same verification core the browser verifier runs.

• aarmos observe

  Start the loopback observation service (default port 7682, change with --port) and print an 8-digit pairing code plus the destination URL. --open launches the browser, observe status shows what is paired, --forget-clients revokes every registered client.

• aarmos replay

  Deterministically replay a recorded decision.

• aarmos lineage

  Multi-agent lineage inside one invocation: declare an adapter-observed spawn edge, observe an active actor, show the actor tree, or list invocations with lineage. Declared edges are attribution claims and are marked as such.

• aarmos anchor

  Anchor evidence to an external transparency log.

• aarmos attest

  Produce a signed attestation for CI.

• aarmos trust

  Inspect trust roots and their lifecycle.

• aarmos entitlement

  Manage the signed entitlement artifact offline: import pins it and its key, status shows the local state, verify checks the signature, forget removes both.

• aarmos login

  Associate this installation with a workspace. Prints a short code you approve in the browser. 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. --json for machine-readable output.

• aarmos logout

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

• aarmos preflight

  Pre-merge governance checks.

• aarmos governed-action (alias ga)

  Operate Governed Actions — one class of consequence at a time. list, show <id> (all five state dimensions), enable <id> --policy-digest (shadow-first; --enforce is refused without a recorded shadow review), shadow <id> --review, promote <id> (refused on definition drift), rollback <id>, drift. Adds no fields to receipts.

• aarmos grp

  Create and inspect Governance Recovery Points.

• aarmos backup

  Replicate evidence to your own storage sink.

• aarmos restore

  Restore governance state from a recovery point.

• aarmos governance

  Inspect change sets and authority state.

• aarmos authority

  Manage authority succession and forks.

• aarmos delegate

  Bounded, durable delegation of authority between actors: grant, list, show (chain to root plus the decisions that relied on it), and revoke — revocation cascades to every grant carved out of it.

• aarmos evidence

  Evidence lifecycle: list segments, apply retention (declarations are written before any byte moves), hold and release legal holds, restore archived segments, show declared gaps, and verify the corpus — distinguishing COMPLETE from a declared retention gap.

• aarmos org

  Organizational governance: install signed topology and membership, explain a scope, resolve identity links, issue and revalidate org-scoped grants, and run bounded break-glass under dual control (open, list, reconcile).

• aarmos boundary

  Inspect trust boundaries and credential custody.

• aarmos incident

  Assemble an incident evidence package.

• aarmos contracts

  Show operational contracts and current posture.

• aarmos soak

  Long-running load and stability check.

• aarmos telemetry

  Inspect or disable local telemetry settings.

Local runtime flags

aarmos proxy and aarmos daemon start share the same local-runtime flags. The runtime binds loopback (or a Unix socket / named pipe) only, and every local client connection is authenticated against the current session.

• --listen <addr>

  Listen address, or a socket/pipe path. Local endpoints only — non-loopback addresses are refused.

• --transport auto|tcp|ipc

  Local transport. auto prefers a Unix socket / named pipe where available and falls back to loopback TCP.

• --auth required|compat

  Local client authentication. required is the default; compat exists only for legacy clients during migration.

• -p, --port <port>

  TCP port for loopback transport (default 7681).

Starting a listener mints a runtime session; stopping it revokes the session. Because authentication is mandatory, a bare HTTPS_PROXY=http://127.0.0.1:7681 returns 407. Enroll a shell with eval "$(aarmos env)", or let aarmos run inject credentials into the child process for you. aarmos doctor prints the active session id, transport, and exposure class. Port 7681 is the default; use --port or --listen to change it.

Runtime sessions expire. A session is valid for 12 hours by default and 24 hours at most; set AARMOS_SESSION_TTL_MINUTES to shorten it. After expiry the credential stops authenticating even if the listener is still up — restart the runtime to mint a fresh one. aarmos doctor shows the expiry alongside the session id.

Related

• Quickstart — first governed call in 60 seconds.
• AVAR specification — the receipt wire format.
• ASP specification — the policy language.
• Error codes — what each refusal means.