CLI Reference

Runtime lifecycle

The --claude-auth flag only affects the claude agent; every other agent ignores it. An empty value (the default) prompts on a TTY and resolves to subscription off a TTY.

Sandbox composition

The sandbox group is aileron sandbox [init|plan|build|check|cache].

Docker is the only supported sandbox runtime in v4. Podman is planned but not yet supported (ADR-0014); passing --sandbox=podman or --runtime=podman fails with podman runtime is not supported yet (v4 is Docker-only); see ADR-0014.

See Sandbox Composition for the full workflow and Sandbox Agent Images for the support matrix and recipes.

Actions

MCP servers that cached the tool list at boot need to be restarted before an enable or disable toggle takes effect with the LLM.

aileron action run

aileron action run <name> [--arg k=v ...] [--args <json>] [--json] [--audit-id-out <path>]

<name> is the installed action name shown by aileron action list, such as sentry-organizations-list or linear-issues-create. The CLI posts to POST /v1/actions/{name}/run; there is no separate execution path or weaker approval path for terminal invocations.

Arguments can be supplied in either of two mutually exclusive forms:

aileron action run linear-issues-create \
  --arg team=ENG \
  --arg title='Smoke test'

aileron action run linear-issues-create \
  --args '{"labels":["bug","triage"],"priority":2}'

--arg k=v is repeatable and sends string values. --args <json> sends a raw JSON object for nested values, arrays, numbers, or booleans.

By default, successful calls print:

wrapped output:
<result>

Use --json to print the daemon response envelope exactly as returned, including audit_id and result. Use --audit-id-out <path> to write the successful execution’s audit_id to a file for follow-up audit-log tooling.

Approval-gated actions return an approval-pending message instead of running immediately. The CLI prints the review URL or aileron approval approve <id> command and exits with code 75 (EX_TEMPFAIL) so scripts can distinguish “approval needed” from ordinary failures.

Connectors

Keyring

The keyring is the v1 source of trust for connector signature verification. Every aileron connector install checks the binary’s signature against keys registered for the FQN’s authority; without an entry, install fails closed. The keyring file lives at ~/.aileron/keyring.json.

Hub

Secrets

Bindings

Sync and verify

Vault

The put and delete verbs talk to the running daemon and never open the vault file directly. put is agents-only: you create a binding with binding setup, not vault put, so it accepts only the agents/<name>/<purpose> namespace and rejects any other path. delete is symmetric with list: it classifies the path and dispatches to the matching namespace-scoped daemon endpoint, so anything list prints — an agent entry, a user/<service> entry, or a binding — is deletable. The tenant-keyed control-plane namespaces (connected-accounts/, llm-config/) are managed by the control plane, not this CLI, so delete rejects them with a message naming the supported paths. For agent entries the <purpose> segment must match ^[a-z0-9][a-z0-9_-]*$ and defaults to oauth for entries an older daemon returns without one. A listed line can be pasted straight into delete. An agent holding both an OAuth envelope and an API key surfaces as two distinct lines (agents/<name>/oauth and agents/<name>/apikey).

vault list itself is read-only and broader: the default (no --scope) walks the vault once and surfaces every locally-owned namespace, so connector and capability-binding credentials appear alongside the agent and user entries instead of being silently hidden. Listing works on a locked vault because it never decrypts a stored value (metadata is plaintext). The two tenant-keyed control-plane namespaces (connected-accounts/, llm-config/) are excluded unless --include-control-plane is passed. See Sandbox Agent Auth for the seeding and recovery flows.

Auth

aileron auth github is a one-time acquisition flow. The github verb resolves the shipped gh capture descriptor by name and drives the generic capture flow. That flow runs gh auth login and gh auth token in the same container, then PUTs the token to the user-level user/github vault namespace through the daemon. The provider knowledge ships as a trusted YAML descriptor in the auth domain, so adding another tool is a new descriptor rather than new code.

Approvals

Audit

Sessions

Browser

Utility

Architecture: CLI is an HTTP client

Every command above resolves to one or more HTTP operations against the Aileron server. The server may be:

• Local — a process the user started with aileron launch, listening on a daemon-advertised address (the v1 default).
• Hosted — a future Aileron Cloud deployment reachable over HTTPS (post-MVP).

The CLI doesn’t care which. It reads its target endpoint from configuration, opens HTTP, and invokes the spec’d operations. This separation means:

• New server functionality is added by extending internal/api/openapi.yaml ↗, regenerating Go stubs (task generate:api), and implementing the handler.
• New CLI commands are shells over those endpoints — argument parsing, output formatting, occasionally orchestrating multiple calls.
• The same CLI binary works against any conformant Aileron server.

The OpenAPI spec is the authoritative source of truth for every API change. CLI commands are documentation of which commands wrap which endpoints; the underlying contract lives in the spec.

For the full HTTP API, see API Reference.