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

​
Sending

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

​
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 for the report schema, safety boundary, and the difference between a stopped daemon and a mismatched build. See Cleanup for the closed asset classes, dry-run contract, and descriptor-bound removal rules.