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. Published 0.3.0 predates the new --version flag,
so use npm ls -g @axtary/cli to identify that global install; the flag ships in
the next coordinated release. 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
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.
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, optionally pausing for hosted approval. |
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 to the hosted tenant with a scoped sync token. |
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
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.