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

# CLI reference

> Current Cyclops commands, common flags, and exit codes.

A bare `cyclops` opens the full-screen workspace. The commands below expose
the same system to terminals and scripts.

| Command                                                           | Purpose                                                                                                                                     |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `cyclops start`                                                   | Create or restore the default workspace and start the daemon if needed.                                                                     |
| `cyclops workspace save\|restore`                                 | Save or rebuild a tmux session's panes, sizes, names, and directories.                                                                      |
| `cyclops sizing release`                                          | Hand a session's window sizing back to tmux, and clear the ownership mark; safe to run twice.                                               |
| `cyclops status`                                                  | Show every watched pane's runtime state plus live composer, readiness, notification, and mailbox facts when they differ.                    |
| `cyclops health`                                                  | Inspect binaries, daemon identity, setup, and bounded state metadata without changing them.                                                 |
| `cyclops stop`                                                    | Stop Cyclops now; tmux panes and durable messages stay intact.                                                                              |
| `cyclops cleanup build-cache\|update-scratch`                     | Inventory named rebuildable assets; add `--apply` to remove exact validated assets.                                                         |
| `cyclops data inventory\|export\|forget`                          | Inventory retained durable records, export them to a new directory, or preview and confirm removing every retained journal.                 |
| `cyclops remove --all --confirm <token>`                          | Preview removal of the complete Cyclops state home, then require its exact confirmation token.                                              |
| `cyclops list`                                                    | Show every named agent, its state, and current detail.                                                                                      |
| `cyclops name <pane> <label>`                                     | Give a pane a stable address; `--clear` releases it.                                                                                        |
| `cyclops clear [<agent>] [--status]`                              | Quiet queued pane notifications for one agent, or cleanse status with `--status`.                                                           |
| `cyclops reset`                                                   | Reset status by clearing old, terminated, and stale processes and sessions.                                                                 |
| `cyclops flush [--prune]`                                         | Flush message ledgers, cleanse state, and reset sessions to start clean; `--prune` (default true) also drops dead panes and stale sessions. |
| `cyclops read <agent>`                                            | Read visible/recent pane output or the detection evidence.                                                                                  |
| `cyclops send <agent> --subject ... [--summary ...] [--raw]`      | Accept a durable message and print its wake receipt; `--raw` pastes the whole message with no composer check.                               |
| `cyclops inbox list`; `cyclops inbox claim <id>`                  | List pending metadata or claim one exact message.                                                                                           |
| `cyclops inbox next --timeout 30s`                                | Wait over the socket and claim at most one pending message without touching a composer.                                                     |
| `cyclops messages`                                                | Read body-free mailbox and notification state.                                                                                              |
| `cyclops reply [<message-id> \| <m-att_...>] [--last] [--raw]`    | Reply using the visible parent message; `--last` answers the most recently claimed one.                                                     |
| `cyclops requeue <message-id>`                                    | Requeue eligible unresolved notification alarms for a message.                                                                              |
| `cyclops notification withdraw <attempt-id> --recipient <key>`    | Withdraw one provably pre-write notification attempt.                                                                                       |
| `cyclops alarm preview --older-than <age>`; `cyclops alarm clear` | Preview or clear exact durable alarm attempts.                                                                                              |
| `cyclops wait <agent> --until idle\|turn-ended\|blocked`          | Wait for a pane state sequence without inferring task completion.                                                                           |
| `cyclops history`                                                 | Read messages from the append-only record.                                                                                                  |
| `cyclops thread <message-id>`                                     | Read one message, its replies, and delivery state.                                                                                          |
| `cyclops watch`                                                   | Open the admin, firehose, and Messages TUI (`--firehose` changes the starting view); `--json` emits one event per line.                     |
| `cyclops hook <event>`                                            | Vendor-hook receiver; silent and always exits 0.                                                                                            |
| `cyclops hooks install\|verify\|selftest`                         | Prepare and verify vendor hooks.                                                                                                            |
| `cyclops setup check`                                             | Inspect manifests, hook wiring, receipt capability, and installed skills without changing them.                                             |
| `cyclops setup plan`                                              | Preview create-only manifests and final skill files below accepted private consumer parents, without changing files.                        |
| `cyclops theme [name]`                                            | Preview themes or switch the active theme.                                                                                                  |
| `cyclops update`                                                  | Build, prove, and activate a matched pair; restart a running daemon and leave a stopped daemon stopped.                                     |
| `cyclops update --rollback`                                       | Reactivate a replay-proven retained pair without reverting state.                                                                           |
| `cyclops daemon status\|log\|stop\|restart`                       | Inspect, stop, or safely restart the exact daemon generation.                                                                               |
| `cyclops ping`                                                    | Measure a daemon round trip.                                                                                                                |
| `cyclops commands`                                                | Show workspace, operations, and diagnostic commands.                                                                                        |

## Sending

```bash theme={null}
cyclops send reviewer --subject "Review the diff" \
  --body "Focus on retry ordering."
cyclops send --all --subject "Standup in 5" \
  --summary "Standup begins in five minutes; join when your current step is safe." --fyi
cyclops send reviewer --subject "Cyclops cannot read your composer" \
  --body "Reply with cyclops reply when you see this." --raw
```

`--summary` is optional: one line of at most 240 characters, derived from the
subject when omitted. `--to` adds recipients, `--body-file -` reads the body
from stdin, `--reply-to` links a reply, and `--all` broadcasts to every
adopted agent. `--raw` pastes the whole message into the recipient pane and
presses Enter with no composer check; the journal records it as an unverified
raw write, so use it only when Cyclops itself is broken for that pane or the
recipient is an unverified vendor. Name `admin` explicitly to send to the
durable operator inbox. By default a durably accepted send exits 0 even when
its terminal wake needs attention. Add `--require-wake` when every recipient
must currently prove a mailbox wake at `submitted` or `notified`. Earlier,
blocked, human-required, missing, and unknown states exit 1.

The flag evaluates the daemon's one bounded current receipt. It does not poll
or wait again. Exit 1 does not revoke durable acceptance, so inspect the
message and never use an unkeyed resend as recovery.

A successful default send or reply proves durable acceptance, not recipient
claim or task completion, and exits 0. If the response is lost, inspect current
state and retry only with the same explicit client key. The client first
validates the response's message id, positive journal sequence, and deliveries
array. A wake receipt state added by a newer daemon does not erase that proof:
plain output prints acceptance with a compatibility warning, while JSON
preserves the raw response. An incomplete acceptance envelope exits 1 in both
modes.

## Caller identity and administrator commands

Cyclops authenticates every local socket caller as the operating-system user
that owns the daemon. A same-UID shell with no admitted agent-vendor ancestor
is the workspace administrator, including a shell opened inside a watched
pane. It does not need a pane label or manifest. A process descended from an
admitted agent resolves to that agent's durable mailbox identity instead.

`admin` is the durable operator mailbox, not a pane name. Operator recovery
commands such as alarm clearance, requeue, and pre-write notification
withdrawal require the administrator identity. Agent
mailbox commands remain scoped to the authenticated agent. Running a command
with `sudo` does not elevate Cyclops authority: a root process is a different
UID from a user-owned daemon and is refused.

## Reading and filtering

```bash theme={null}
cyclops history --with reviewer --limit 20
cyclops watch --from implementer --to reviewer
cyclops read reviewer --source detection --raw
```

## Global output flags

* `--json` requests machine-readable results on commands with structured
  output. With `watch`, it prints an NDJSON event stream instead of opening
  the TUI. `update`, `daemon log`, and the interactive UI remain text.
* `--plain` disables color and glyph animation while preserving the words.
* `NO_COLOR` disables color on every surface.

## Exit codes

* `0`: the command succeeded; for sends, the message was accepted or an exact
  client-key retry found the existing message.
* `1`: no successful response. With `send --require-wake`, it can instead mean
  the message is durable while at least one recipient lacks current proof of a
  submitted or notified wake. It does not authorize an unkeyed resend. A send
  may also already be durable if its response was lost.
* `2`: usage error, or `wait` timed out.
* `3`: the waited-on pane died or changed occupant.

Run `cyclops <command> --help` for every flag accepted by that command.

See [Health inspection](/docs/reference/health) for the report schema, safety
boundary, and the difference between a stopped daemon and a mismatched build.
See [Cleanup](/docs/reference/cleanup) for the closed asset classes, dry-run
contract, and descriptor-bound removal rules.