Command reference

Every anlyon CLI command, what it needs, and how writes are confirmed, made idempotent and reported.

Every command also accepts the global flags: --json, --profile, --environment, --input, --timeout and --no-input, and list commands accept --limit and --cursor. anlyon <command> --help describes each command.

Account

Command	What it does
`anlyon auth login`	Log in with your Anlyon account in the browser (OAuth + PKCE), or store an API key with `--api-key-stdin`. Add consent groups with `--scope`.
`anlyon auth status`	Show which profile, API and credential commands will use, and whether it works.
`anlyon auth logout`	Revoke this profile’s refresh token and delete its stored credential.
`anlyon auth scopes`	Show what the current credential is granted, and which commands it can run.
`anlyon profile list`	List profiles. The active one is what commands in this terminal will use.
`anlyon profile use <name>`	Set the default profile for new commands. `ANLYON_PROFILE` still wins per terminal.
`anlyon whoami`	Show who and where the current credential acts: user, workspace, environment.
`anlyon doctor`	Check the install, config, credential store, API reachability and credential. Exits 1 when a check fails, 0 otherwise.

anlyon auth login --scope anlyon:approvals.decide
anlyon profile use staging
anlyon whoami

See Log in and profiles.

Actions and invocations

Command	What it does
`anlyon actions list`	List the actions configured in this environment.
`anlyon actions get <ref>`	Show one action by name or `act_` id.
`anlyon actions versions <ref>`	Show an action’s version history.
`anlyon actions invoke <ref>`	Invoke an action. Policy and approvals apply exactly as for any other caller. Writes below.
`anlyon actions declare <ref>`	Set or remove what an action declares: its impact, its read-back, or governed alone. Writes below.
`anlyon invocations list`	List action invocations, newest first. Filter with `--action <ref>` and `--status <status>` (for example `unknown`, `failed`, `succeeded`).
`anlyon invocations get <id>`	Show one invocation by `inv_` id.

anlyon actions list
anlyon actions get refund_payment
anlyon actions invoke refund_payment --data '{"charge":"ch_123","amount":1200}'
anlyon invocations list --status unknown
anlyon invocations get inv_123

The action input for actions invoke is a JSON object, passed with --data '<json>', or read from a file or stdin with --input <file|->. Use one or the other, not both.

An invocation’s status is described in Receipts and grades. failed means the destination rejected the request, or it was never sent. unknown means it may have taken effect.

Governed actions

An action is governed when it declares an impact, a read-back, or --governed alone. actions declare sets and removes those declarations. A flag you leave out keeps what the action already declares.

# One call sends count(input.to) emails. Impact limits in the unit "emails" now apply.
anlyon actions declare send_email --dimension emails --amount 'count(input.to)' --bound exact --yes

# Money needs its currency. The amount is a ceiling here.
anlyon actions declare refund_payment --dimension money --unit usd --amount input.amount --bound upper_bound --yes

# Read the write back after dispatch. A match grades the effect confirmed.
anlyon actions declare send_email \
  --verify-url 'https://api.example.com/v1/messages/{{response.id}}' --verify-status 200 \
  --verify-match data.status=sent --yes

anlyon actions declare send_email --no-verify --yes    # remove the read-back
anlyon actions declare send_email --ungoverned --yes   # remove every declaration

actions declare flags:

--dimension: money, resource_mutations, or a unit you name such as emails.
--unit: the currency when the dimension is money, for example usd. Leave it out otherwise.
--amount: an integer, input.<path> or count(input.<path>), with an optional * <integer>.
--bound: exact or upper_bound.
--verify-url, --verify-status: a GET on the action’s own host and the HTTP status it must answer with. They go together.
--verify-match path=value: a check on the read-back body. It may be repeated, up to 10 times. A value that reads as a number, true, false or null is sent as that. Quote it as JSON to send a string: --verify-match 'id="42"'.
--governed: govern an action that declares neither an impact nor a read-back.
--no-impact, --no-verify: remove that declaration.
--ungoverned: remove every declaration. It cannot be combined with another declaration flag.

An impact needs --dimension, --amount and --bound together. Setting an impact replaces the whole impact, and the same holds for the read-back.

Declaring needs actions:write. Changing or removing what a governed action already declares also needs actions:govern, which no browser login grants. Use an operator API key for that. actions get shows governed, impact and verify.

For an API you declare, you write what the action counts, and Anlyon enforces it before dispatch. See Actions.

Runs

Command	What it does
`anlyon runs list`	List runs, newest first.
`anlyon runs get <id>`	Show one run with its span tree.

runs list filters:

--status: running, succeeded, failed or cancelled.
--search: substring match on run id, name or application.
--agent: only runs by this agent id.
--since, --until: only runs started at or after, or before, an ISO 8601 time.

anlyon runs list --status failed --since 2026-09-01T00:00:00Z
anlyon runs get <run-id>

Approvals

Command	What it does
`anlyon approvals list`	List approval requests. `--status pending` is the inbox.
`anlyon approvals get <id>`	Show one approval by `apr_` id.
`anlyon approvals approve <id>`	Approve a pending request. For a gated action, Anlyon runs the reviewed request once enough approvers agree. Writes below.
`anlyon approvals deny <id>`	Deny a pending request. A denied action never runs. Writes below.

approvals list filters:

--status: pending, approved, denied or expired.
--origin: only decisions of this origin: human, policy, system, unknown, assistant or automated.

anlyon approvals list --status pending
anlyon approvals get apr_123
anlyon approvals approve apr_123 --note "checked with the customer"
anlyon approvals deny apr_456 --note "amount does not match the ticket"

--note is recorded with the decision. See Approvals and policies.

Policies

Command	What it does
`anlyon policies list`	List approval policies for this environment. Filter with `--action <name>`.
`anlyon policies get <id>`	Show one approval policy.
`anlyon policies versions <id>`	Show a policy’s version history, newest first.

anlyon policies list --action refund_payment
anlyon policies versions apol_123

Policy commands need policies:read, which no browser consent group grants. Use an operator API key. The CLI reads policies. To configure policies from deployment code, see Policy as code. The SDK’s anlyon-policy executable is unchanged and keeps working.

Effects

Command	What it does
`anlyon effects list`	List governed effects with their receipt grades, newest first.
`anlyon effects get <id>`	Show one governed effect by `eff_` id, with its receipt grade and evidence.

effects list filters:

--action <name>: effects of this action (name or act_ id).
--outcome <o>: not_dispatched, pending, succeeded, failed or unknown.
--grade <g>: confirmed, acknowledged, unknown, failed, refused, denied or pending.
--unresolved: effects still holding impact-limit capacity: pending, unknown or possibly partial.

anlyon effects list --unresolved
anlyon effects list --action send_email --grade refused
anlyon effects list --grade acknowledged --json
anlyon effects get eff_123

Every governed call leaves an effect with a receipt grade. effects list has a GRADE column, and effects get prints what the grade means.

Grade	Meaning
`confirmed`	A read-back matched the request. On a declared action that is the verify rule the workspace wrote.
`acknowledged`	The provider accepted the request. Nothing read it back.
`unknown`	No usable response. Anlyon does not send it again. It stays unknown until a read-back or an operator settles it.
`failed`	The provider rejected the request, or it never left Anlyon.
`refused`	Anlyon refused it at dispatch.
`denied`	The approval was denied.
`pending`	No receipt yet.

See Governed effects and Receipts and grades.

Impact limits

Command	What it does
`anlyon impact-limits list`	List the impact limits shared by every agent in this environment. Add `--include-archived` to include archived limits.
`anlyon impact-limits get <id>`	Show one impact limit by `lim_` id.

anlyon impact-limits list
anlyon impact-limits get lim_123

Both commands show the unit each limit counts: the currency for money, the declared unit otherwise. The CLI reads limits. It does not create or change them.

See Impact limits.

Writes

actions invoke, actions declare, approvals approve and approvals deny change things. They behave as follows.

They confirm first

Interactively, the CLI asks you to confirm, naming the workspace and environment the credential is bound to. Anywhere else (scripts, CI, an agent’s shell) pass --yes. Without it, nothing is sent.

anlyon actions invoke refund_payment --data '{"charge":"ch_123","amount":1200}' --yes

They carry an idempotency key

Every write carries an idempotency key: yours, passed with --idempotency-key <key>, or one the CLI generates and prints. Re-running with the same key returns the recorded result and does not run the action again. That is what makes an interrupted command safe to repeat. For approvals approve and approvals deny, a re-run after the decision was recorded exits 6, because the approval is no longer pending. A key is 8 to 255 characters of letters, digits, ., _, : or -.

anlyon actions invoke refund_payment --data '{"charge":"ch_123","amount":1200}' \
  --idempotency-key refund-ch_123 --yes

See Idempotency and retries.

Policy and approvals apply as for any caller

An invoke that needs approval exits with code 12 and prints the approval id. --wait <duration> follows it to its outcome, for example --wait 10m.
An action that is still running when the command returns also exits 12.
An outcome the destination could not confirm, such as a timeout after it received the request, exits 13. Do not retry with a new key. Reconcile with the destination first. Re-running with the same --idempotency-key is safe: it returns the recorded result.
An action that failed, was denied, or whose approval expired exits 14.

If --timeout or Ctrl-C cuts off a write before a reply arrives, the request may already have reached Anlyon, so the command also exits 13 and prints the key that reads the recorded result back.

anlyon actions invoke refund_payment --data '{"charge":"ch_123","amount":1200}' --wait 10m

Deciding approvals needs `approvals:decide`

anlyon auth login --scope anlyon:approvals.decide

A credential can never decide an approval it requested: not the requesting API key, and not the OAuth app (such as a CLI login) that made the request for you. Decide those from the dashboard or a separate login.

Approving or denying an approval that is no longer pending exits with code 6. If an approved action then runs and its outcome cannot be confirmed, approvals approve exits 13.

The full exit code table is in Scripting and CI.