> ## Documentation Index
> Fetch the complete documentation index at: https://docs.circuit.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Operations

> CLI commands for creating, approving, and tracking reviewed money operations without a chat session.

The `circuit operations` namespace drives Circuit's reviewed-operation surface
headlessly: you submit a structured intent, the server quotes it and captures a
reviewed operation, and nothing moves until you approve it. Creation never
moves money - approval is the only step that admits an operation for
execution.

All commands need a signed-in session (`circuit auth login`,
[details](./authentication#sign-in)) or `CIRCUIT_TOKEN` captured via
[`circuit auth token`](./authentication#token). `--env` selects the target
deployment as usual.

### Create Operation

```bash theme={null}
circuit operations create --file swap.json
circuit operations create --file - < swap.json     # read the intent from stdin
circuit operations create --file swap.json --approve --wait
```

Reads a structured operation intent (JSON) from the file, or from stdin with
`--file -`. The CLI validates the intent against the strict wire schema before
anything leaves your machine, so a malformed file fails loudly with no network
round trip.

Do not put an `idempotencyKey` in the file - the CLI rejects one. It mints the
key itself and retains it until the server's durable answer arrives, so a
retried create rejoins the same operation instead of minting a duplicate.

| Flag               | Description                                                                                                                |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `--file <path\|->` | Structured intent JSON file, or `-` to read stdin                                                                          |
| `--approve`        | Approve the operation right after creation                                                                                 |
| `--wait`           | After `--approve`, poll until the operation settles. Rejected without `--approve` - an unapproved operation never settles. |

A swap intent (tokens are contract addresses; `null` means the network's
native asset; `quoteFloor` is the reviewed worst case in base units):

```json theme={null}
{
  "kind": "swap",
  "walletId": 12,
  "swapIntent": {
    "from": { "network": "ethereum:8453", "token": null },
    "to": { "network": "ethereum:8453", "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
    "amount": "0.25",
    "quoteFloor": { "sellRaw": "250000000000000000", "receiveRaw": "912000000" }
  }
}
```

A send intent (the recipient is an owned wallet id or a pasted address;
`"max"` resolves from the live balance at approval, never a client snapshot):

```json theme={null}
{
  "kind": "send",
  "walletId": 12,
  "sendIntent": {
    "token": { "network": "solana", "token": null },
    "amount": "max",
    "to": { "address": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin" }
  }
}
```

`perp` and `prediction` intents follow the same shape: `{ "kind": "perp",
"walletId": …, "perpIntent": … }` and `{ "kind": "prediction", "walletId": …,
"order": … }`.

Text output prints `id`, `kind`, `state`, and one line per reviewed action
label - the exact actions the operation will execute once approved. With
`--wait`, it prints the terminal state rather than the earlier working state.
`--json` prints the captured resource under `operation` and the settled resource
under `terminal`. If automatic approval fails after creation, the error document
still includes `operation`, so its ID is never lost.

### Approve Operation

```bash theme={null}
circuit operations approve <operation-id>
circuit operations approve <operation-id> --wait
```

Admits an operation that is awaiting approval. This is the step that moves
money. `--wait` polls until the operation settles.

If the approval request fails, the CLI re-reads the canonical resource. When the
operation remains `awaitingApproval`, the CLI exits nonzero with
`OPERATION_APPROVAL_PENDING`; retry `circuit operations approve <operation-id>`
for the same operation. A dismissed or canceled operation returns its terminal
resource and fails instead of claiming that approval succeeded.

### Get Operation

```bash theme={null}
circuit operations get <operation-id>
```

One current-state read of the canonical resource. Same output shape as
`create`. A read never maps the operation's state to the exit code - only a
`--wait` settlement does that.

### Discard Operation

```bash theme={null}
circuit operations discard <operation-id>
```

Dismisses an operation before admission. A discarded operation never moved
money and never will.

### Waiting and exit codes

`--wait` (on `create --approve` and `approve`) polls the action sequence until
it settles. Only `done` exits `0`. `dismissed`, `canceled`, `failed`, and
`failed_before_effect` exit nonzero; failure states print the operation's stored
error in full (`failed_before_effect` proves nothing moved).

Under `--json` the settled resource is included under `terminal` even when the
command exits nonzero, so scripts can inspect the failure without a second
read.