CLI reference
The axtary CLI is the local enforcement plane. It normalizes an agent action,
evaluates policy before execution, issues or verifies payload-bound authority,
calls an enabled connector, and records evidence. Provider credentials remain in
the local runtime or credential broker; they are not sent to the hosted dashboard.
This page is a task-oriented command map. Run axtary <command> --help for the
current flags and examples. The published @axtary/*@0.6.1 line includes
axtary --version; use it to confirm the installed CLI before a demo or support
run. Commands fail closed when required configuration, credentials, trust, or
an injected network transport is missing.
Start and diagnose
| Command | Use it for |
|---|---|
axtary init | Scaffold axtary.yml, starter policies, and local .axtary/ state. Add --template <name> for a reusable policy profile. |
axtary doctor connectors | Report each implemented connector as ready, disabled, or needing setup. This checks readiness; it does not prove a live provider mutation. |
axtary demo | Run the credential-free policy → ActionPass → connector → ledger loop. Add --approve-step-up to attach local exact-payload approvals. |
axtary proxy | Start the local enforcement endpoint used by hooks and governed clients. |
axtary smoke | Exercise an enabled connector against its configured smoke target. Use sandbox resources and inspect the proof label. |
The fastest first proof is:
axtary init
axtary doctor connectors --config axtary.yml
axtary demo --config axtary.yml --approve-step-up
Link a dashboard account
The local CLI does not require a hosted account. When you want a remote human to review step-up actions, link an already-provisioned dashboard membership:
axtary login
axtary account # `axtary whoami` is an alias
axtary proxy --config axtary.yml --hosted-approval
login opens a one-time browser confirmation, asks you to choose a workspace
when the account has more than one, and stores a revocable approval-only session
in the local credential broker. It never stores provider credentials in the
dashboard and never prints access or refresh tokens. An account without a
dashboard membership is told that it has no workspace; local CLI use continues
normally. Run axtary logout to revoke the session and remove it locally.
If the saved endpoint has been permanently retired and cannot accept that
revocation, run axtary logout --local-only. This deliberately removes only
the local credential; the remote session may remain active until it expires or
is revoked server-side.
Use --endpoint <origin> for a different deployment. HTTPS is required except
for loopback development, and the credential remains bound to that exact origin
and selected tenant. --no-browser prints the URL for a remote terminal.
Policy and ActionPass
| Command | Use it for |
|---|---|
axtary policy simulate <action.json> | Dry-run one normalized action and inspect matched rules, decision, reason, and obligations without executing it. |
axtary policy test <tests.yml> | Run a policy fixture suite in CI or locally. |
axtary test-policy <tests.yml> | Compatibility entry point for the policy test harness. Prefer axtary policy test in new automation. |
axtary revoke | Revoke an ActionPass or delegated authority in the configured trust/status state. |
axtary revocations | Inspect the local ActionPass revocation trust store without printing secrets. |
axtary issuer-keys | Inspect trusted issuer public-key metadata. |
axtary status | Inspect local Token Status List allocation and state. |
axtary caep-map | Map a CAEP session-revoked event into Axtary revocation state. Remote JWKS retrieval requires an explicit trusted transport. |
Local approval in demo --approve-step-up is useful for a reproducible proof.
For a real human decision, use the hosted approval flow: the local runtime sends
the exact payload and hash through a scoped runtime token, waits, and resumes
only if a signed-in reviewer approves that payload in the dashboard.
axtary login obtains and refreshes that token for interactive use. The legacy
AXTARY_APPROVAL_TOKEN environment variable remains available for deliberate
CI or break-glass operation.
Agent runtimes and MCP
| Command | Use it for |
|---|---|
axtary hook install <claude|cursor|codex> | Write an idempotent project hook configuration with resolved CLI paths. |
axtary hook claude-code | Consume a Claude Code PreToolUse payload from stdin. |
axtary hook cursor | Consume Cursor's beforeMCPExecution payload and return its permission response. |
axtary hook codex | Gate covered Codex shell, patch, and MCP filesystem tool calls. See the integration guide for coverage limits. |
axtary mcp serve | Expose Axtary as an MCP server or govern a wrapped stdio/remote MCP server. |
axtary mcp login/sessions/logout | Manage OAuth 2.1 + PKCE sessions for a remote MCP server in the local credential broker; bearer tokens are never printed. |
axtary mcp pins/review | Inspect and review persisted tool-definition hashes before use. |
axtary mcp trust-publisher/publishers/verify-definition | Register publisher public keys and verify signed tool definitions without trust-on-first-use. |
axtary mcp conformance | Run one live governed MCP call and collect pin, publisher, ledger, drift, and attestation evidence. |
axtary mcp drift-demo | Reproduce a tool-definition mutation and verify that the changed definition is quarantined. |
Read Integrate your agent and Signed MCP tool definitions before choosing a hook or MCP boundary. Coverage differs by client; Axtary does not claim to mediate calls that never reach the configured boundary.
Connect and execute
| Command | Use it for |
|---|---|
axtary connect <linear|slack|jira|drive> | Complete provider OAuth and store the resulting credential in the local broker. Slack, Jira, and Drive require an HTTPS callback URL; Linear supports loopback. |
axtary connections | List brokered connections by safe metadata, never token values. |
axtary disconnect | Remove a brokered provider connection. |
axtary run workflow github-pr-review | Execute the governed GitHub + Linear + Slack sandbox workflow. Add --hosted-approval after axtary login to pause step-up actions for dashboard review. |
axtary run workflow github-depth | Exercise governed GitHub PR, review, check-run, and issue-comment operations. |
axtary run workflow postgres-read | Execute one parameterized, bounded, read-only Postgres query through policy and ledger. |
axtary run workflow drive-read | Read one Picker-authorized Drive file within configured file and byte limits. |
Use --real only with an intentionally scoped sandbox configuration. A connector
being implemented or configured does not itself prove the provider call; use
doctor, smoke, and the resulting ledger evidence to distinguish those states.
Evidence and verification
| Command | Use it for |
|---|---|
axtary export-ledger | Export filtered ledger records without turning payload bodies or secrets into telemetry. |
axtary sync-ledger | Push a bounded local ledger slice with a scoped sync token and a signature from the runtime attestation key pinned into that token. Use --key <path> to select the private local key; otherwise the CLI loads or creates the owner-only key beside the ledger. |
axtary export-otel | Export payload-free governed-action spans to an OTLP collector. |
axtary attest-ledger | Create a signed attestation over a ledger export. |
axtary verify-export | Independently verify an exported attestation and its ledger chain. |
axtary prove-equivalence | Prove that approved and executed payload hashes match for eligible records. |
axtary prove-inclusion | Produce an RFC 6962 inclusion proof for a ledger record. |
axtary prove-consistency | Prove append-only consistency between ledger tree sizes. |
axtary verify-proof | Verify an inclusion or consistency proof outside the runtime that created it. |
axtary forensics | Inspect local evidence and integrity failures without trusting the hosted control plane. |
axtary acs | Run and inspect the Agentic Commerce/authorization conformance surface documented under standards. |
A typical independent verification sequence is:
axtary attest-ledger --ledger .axtary/actions.jsonl --out attestation.json
axtary verify-export attestation.json
axtary prove-equivalence --ledger .axtary/actions.jsonl
Hosted sync tokens are not standalone upload authority. An admin mints one for the runtime's public P-256 attestation key and issuer; the CLI must still prove possession of the matching private key over the exact export. Tokens expire within one hour. After the 2026-07 receipt hardening, pre-receipt hosted batches remain preserved but do not appear as trusted evidence until a fresh attested sync succeeds.
Local files and secrets
.axtary/ is runtime state, not source: ledgers, public trust metadata, status
state, OAuth broker state, and local keys can live there. Keep it out of version
control, do not record it in demos, and do not paste tokens or private-key values
into commands, logs, tickets, or support messages. Configuration should name an
environment variable or brokered connection; the agent should not receive the
secret value.
For guided flows, continue with the Quickstart, Dashboard guide, or Evaluate Axtary.