---
title: "Command reference"
description: "Every anlyon CLI command, what it needs, and how writes are confirmed, made idempotent and reported."
icon: "list"
---

Every command also accepts the [global flags](/cli/scripting#terminal-contract): `--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. |

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

See [Log in and profiles](/cli/authentication).

## 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](#writes) below. |
| `anlyon actions declare <ref>` | Set or remove what an action declares: its impact, its read-back, or governed alone. [Writes](#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. |

```bash
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](/execution/outcomes). `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.

```bash
# 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](/execution/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.

```bash
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](#writes) below. |
| `anlyon approvals deny <id>` | Deny a pending request. A denied action never runs. [Writes](#writes) below. |

`approvals list` filters:

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

```bash
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](/trust-control/approvals).

## 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. |

```bash
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](/trust-control/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.

```bash
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](/execution/governed-effects) and [Receipts and grades](/execution/outcomes).

## 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. |

```bash
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](/execution/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.

```bash
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 `-`.

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

See [Idempotency and retries](/execution/idempotency).

### 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.

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

### Deciding approvals needs `approvals:decide`

Log in with the decide consent group. The consent screen names it:

```bash
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](/cli/scripting#exit-codes).