Reference
Command Line (CLI)
Install the cyborg CLI, log in to the relay, and drive workspaces, agents, tasks and terminals on any daemon you have access to.
The cyborg CLI lets you work from a terminal: log in to the relay and drive workspaces, channels, agents, persistent agents, tasks, and terminals running on any daemon you have access to. Anything you can do in the app, you can script from the shell.
Install
On Linux the CLI ships with the headless daemon installer (it bundles its own runtime, so no system Node is required):
curl -fsSL https://raw.githubusercontent.com/Cyborg7-com/cyborg7-releases/main/cyborg-cli/install.sh | sh
On macOS and Windows the desktop app bundles the same cyborg binary: Settings → System → Command line → Command-line tool → Install links ~/.local/bin/cyborg to it (if ~/.local/bin is not on your PATH yet, click Add to PATH), so the CLI and the app’s daemon are always the same version. See Manage sessions from the CLI for a walkthrough.
Authenticate
cyborg login signs in with a 6-digit code sent to your email, the same way the app does, and saves the result locally. Point at a self-hosted relay with --url.
cyborg login # prompts for your email, then for the code
cyborg login --email you@example.com # prompts only for the code
Without a terminal (a script, CI), sign in in two steps: the first run only sends the code, the second redeems it without asking for a new one.
cyborg login --email you@example.com # sends the code
cyborg login --email you@example.com --code 123456 # redeems it
On a computer where the Cyborg app is already signed in, sign the CLI in through the app instead: in the app open Settings → Sessions & devices → Sign in the CLI, run the command it shows, and paste the link when the CLI asks for it (or pipe it in on stdin). The CLI prints a 2-digit code; type it in the app to approve. The CLI then has its own session, tied to the app’s: signing the app out signs it out too.
cyborg login --from-app # asks for the link, so it stays out of your shell history
A link is single use: the first claim takes it, within 2 minutes, and only that claimant can finish the sign-in (within 5 minutes). cyborg login --from-app '<link>' also works, but leaves the spent link in your shell history.
If you already hold a relay token, pass it together with the id of its user; both are required:
cyborg login --token-stdin --user-id <user-id> < token.txt
For a single command you can also supply the token through CYBORG_TOKEN or --token-stdin (see Where commands connect).
Check who you are logged in as and the daemon and relay connectivity:
cyborg whoami # show the logged-in user
cyborg status # show daemon + relay status
Check this computer’s install
cyborg doctor checks everything that can make the CLI misbehave on this computer and prints a fix for each problem:
cyborg doctor # one row per check: ok, warn, fail or skip, with a fix
cyborg doctor --json # [{ "check", "outcome", "detail", "fix" }], one per check, always in this order
cyborg doctor --fix # repair what the Cyborg app owns; print the command for the rest
--fix changes only what the Cyborg app owns: it rewrites the app’s ~/.local/bin/cyborg (recognized by its marker) and adds the app’s PATH line to your shell’s rc once, after saving a backup next to it. It never edits, moves or deletes anything else. A file it did not create, an rc that is a link, and another cyborg that runs first are left as they are, and it prints the command to run (for a pnpm link --global: pnpm rm --global @getpaseo/cli). Sign-in, daemon and relay problems are printed too.
It checks which cyborg your shell runs first and where it came from (the Cyborg app, the curl install, a development checkout, pnpm, npm or Homebrew), its version against the app’s, other copies on your PATH, the relay, your clock, your sign-in (including an account secured with “Not me”), the daemon, and the saved credentials. It reads the other copies’ package.json and never runs them, every check has a timeout, and the token is never printed. It exits 1 when a check fails, and 2 when the only failure is your sign-in being refused.
Once a day, before a command, the CLI runs the local part of these checks (no network, no other program) and warns on stderr when another cyborg runs ahead of the app’s, when a development build has not been updated in 14 days, when it is older than the app, or when it is older than the minimum the relay asks for (learned on token refreshes and by cyborg doctor). CYBORG_NO_SELF_CHECK=1 turns that off.
What this install sends
cyborg telemetry status # one row per channel: direct_export, daemon_relay_reports, daemon_relay_operational
cyborg telemetry status --json # [{ "channel", "sends", "why" }]
Each row says whether that channel sends anything from this install and why, judged from this shell’s environment and this computer’s daemon home. It opens no connection. CYBORG_TELEMETRY=off stops the first two; the operational events a connected daemon sends to its relay are not telemetry exports and keep flowing. The full description is TELEMETRY.md at the repository root.
Global flags
Every command accepts these output controls, which make the CLI scriptable:
| Flag | Purpose |
|---|---|
-o, --format <table|json|yaml> | Output format (default table) |
--json | Shorthand for -o json |
-q, --quiet | Minimal output, IDs only |
--no-headers | Omit table headers |
--no-color | Disable colored output |
Exit codes
A script can tell from the status alone why a command did nothing:
| Status | Meaning | Codes, for example |
|---|---|---|
0 | Done | |
1 | Failed: an error, bad input, an unknown command or flag, or any code not listed below | TASK_LIST_FAILED, DAEMON_TIMEOUT, INVALID_ARGUMENT, NOT_FOUND, RATE_LIMITED |
2 | Refused: you may not do this (not signed in, no permission, plan or seat limit), or you said no at a prompt | FORBIDDEN, OWNER_OR_ADMIN_ONLY, AGENT_COMMAND_UNAVAILABLE, CYBORG_NOT_LOGGED_IN, PRO_REQUIRED, CONFIRMATION_DECLINED |
3 | Needs approval: nothing ran, because the command needs a confirmation it did not get | CONFIRMATION_REQUIRED (re-run with --yes), APPROVAL_REQUIRED (re-run with --execute), RPC_NEEDS_YES, APPROVAL_PENDING (inside an agent: held for its owner’s OK) |
4 | Conflict: the target’s state or version is not what the command expected (it changed since you read it, it is already done, a name is taken, or the relay or machine is too old for the command); re-read, then decide | CONFLICT, STALE, PAGE_STALE, NOT_SUPPORTED, DAEMON_OUTDATED |
The error itself goes to stderr; with --json it is { "error": { "code", "message", "details" } }. Until October 2026 every failure exited 1; a script that only checks for a non-zero status keeps working. cyborg daemon start, cyborg terminal capture, cyborg terminal send-keys and cyborg terminal watch come from the daemon’s own tooling and still exit 1 on every failure.
Lists
ch:list, member:list, cybo:list, skill:list, machine:list, project:list, page:list, webhook:deliveries and webhook:outgoing:list take --limit <n> and --cursor <cursor>. Without them they print the whole list as before. With either, --json prints { <rows>, nextCursor } (for example { "channels": [...], "nextCursor": "ch_…" }; nextCursor is null on the last page), and a table or -q prints the rows with the next page’s full command on stderr. The relay answers these lists whole and the CLI cuts the pages, so a cursor is the id of the last row printed; a cursor whose row is gone is refused (INVALID_ARGUMENT). webhook:deliveries pages the 30 most recent deliveries, which is all the relay keeps.
Plan, approve, execute
A command that runs something or can’t be undone shows its plan first: webhook:redeliver, webhook:rotate-secret --clear, trigger:test, trigger:replay, schedule:run, agent:rewind --mode files (and both), skill:files:rm and task:bulk-update --archived. Inside an agent schedule:run runs the agent’s own schedule without a plan (see Schedules and skill writes inside an agent).
- At a terminal, the CLI prints the plan and asks before it runs. A no (or Ctrl-C) sends nothing.
- In a script (no terminal on stdin), nothing is sent: the command prints the plan in the error’s
details, with the exact command to re-run, and exits 3 (needs approval). Add--executeto run it. - Inside an agent an agent never approves its own, and each command answers differently:
agent:rewind --mode files(orboth) andskill:files:rmstop at the plan and exit 3; the plan names the command for the person to run with--execute. The agent’s own tools refuse the same thing (cyborg7_session_controlrewinding files,cyborg7_manage_skillremoving a bundled file).agent:rewind --dry-runand a conversation-only rewind still run.- Webhook execution commands (including
webhook:retryandwebhook:replay) andtrigger:*are a person’s commands: refused, exit 2. The channel-scopedwebhook:activityread is available to agents as described below. task:bulk-update --archivedis refused by name, exit 2.schedule:runinside an agent runs only the agent’s own schedules (see Schedules and skill writes inside an agent).
The statuses are the ones under Exit codes.
Where commands connect
After cyborg login, workspace commands go through the relay with your saved login, with no --host and no --token. The local daemon is used only by cyborg daemon … and by cyborg terminal … without --workspace.
--relay-url <url>(on the relay commands:agent:alias,agent:aliases,rpc) points one command at a different relay, such as a dev or staging one; your saved login is sent only to the relay that issued it.--host <host>overrides the target: a relay URL (wss://relay.example.com/api/ws) or a daemon (host:port,tcp://host:port?ssl=true&password=…). Your saved login is sent only to the relay you logged in to, never to another host.- Credentials, in order:
--token-stdin(reads the first line of stdin) or the deprecated--token, theCYBORG_TOKENenvironment variable, then the saved login (the default one, or a named profile). A saved login that the relay rejects is refreshed once automatically. --tokenstill works but is deprecated: argv is visible to other users inps, in shell history and in CI logs. Every use prints a warning on stderr, except with--json/-o json|yaml(stderr then carries only the machine-readable error); every use is still counted. UseCYBORG_TOKEN,--token-stdinor a profile instead.agent:aliasandagent:aliasesno longer take--tokenat all.- Named profiles keep several logins apart, such as your own and a CI account.
cyborg login --profile cisaves a login under~/.cyborg/profiles/ci/, and--profile ci(orCYBORG_PROFILE=ci) on any later command uses it instead of your default login. A profile name is 1-32 lower-case letters, digits,-or_.--profileis refused next to a token (--token,--token-stdinorCYBORG_TOKEN), because the token would win and the profile would be ignored.CYBORG_PROFILEgoes through the same checks as the flag. A profile that holds no usable login (never logged in, or an unreadableauth.json) is refused withCYBORG_NOT_LOGGED_INand thecyborg login --profile <name>to run; the command never falls back to another login or the local daemon. Machine-local commands (loginitself,daemon,whoami,status,hooks, andterminalwithout--workspace) are exempt.loginalso takes a token next to a profile (cyborg login --profile ci --token-stdin --user-id <id>), since that token is what it saves into the profile.--profileis refused inside an agent, which always acts as itself, and an inheritedCYBORG_PROFILEis not read there. - Before a command that changes something runs, it prints one line on stderr saying who it acts as and where, for example
acting as ana@example.com (profile ci) on workspace ws_123,acting as bot@example.com (token from CYBORG_TOKEN) on workspace ws_123or, inside an agent,acting as agent <agent-id> on workspace <workspace-id>. A token’s name comes from the token’s own claim and is for display only; the relay verifies it. Reads (*:list,*:get,*:search, …) and machine-local commands (daemon,login,whoami,status, andterminalwithout--workspace) print no such line. The line names the credential the command really presents:--email(dev login) before a saved login, and nothing when an explicit daemon--host/CYBORG_HOSTtakes no relay login. With--jsonor-o json|yamlno line is printed, so stdout and stderr stay machine-readable. --emailon workspace commands logs in to a local development daemon. It only appears in--helpwhenPASEO_NODE_ENV=development.- Environment:
CYBORG_HOST(same as--host),CYBORG_TOKEN,CYBORG_PROFILE(same as--profile),CYBORG_DAEMON_HOME(the daemon’s state directory).CYBORG_HOMEis the directory holding your login (~/.cyborg), not the daemon’s.
Manage the daemon
A daemon is the agent host. It runs agents and terminals on a machine and connects them to your workspaces through the relay. On a server, manage it with the cyborg daemon group:
cyborg daemon start --replace --foreground # run in the foreground (systemd, containers)
cyborg daemon status # running? which port/home?
cyborg daemon doctor # version, relay link, online state, update available, keep awake (checked against pmset / systemd-inhibit / powercfg)
cyborg daemon restart
cyborg daemon reload # re-read config.json without restarting
cyborg daemon stop
Who the daemon trusts on this machine
A program that connects to the daemon’s local socket (ws://127.0.0.1:<port>/ws) gets full control (agents, terminals, files, stop) only if it proves it belongs to the machine’s owner. It does that with one of:
- the daemon’s local credential, the file
local-credentialin the daemon home (default~/.cyborg7). The daemon writes a new one, readable only by your OS user, every time it starts. ThecyborgCLI and the Cyborg app read it for you, but only for the daemon recorded in that home. - the daemon password, if one is set (
PASEO_PASSWORD).
A program with neither (another OS user, a web page, any process that can’t read the file) still connects, but gets no daemon permission: every daemon command (cyborg agent ls included) answers “Update the cyborg CLI (or the Cyborg app) and try again”. Only the Cyborg app’s own update check (“is an agent busy?”) gets an answer, and it is just busy or idle. A wrong or outdated credential is refused (close code 4401). An older global cyborg CLI that can’t read the credential gets that same update message.
cyborg --host ssh://…reaches a remote daemon through a tunnel, where the remote credential can’t be read. That daemon needsPASEO_PASSWORD.- Agents: CYBORG-1683 (not shipped yet) will stop agents from reading
local-credentialon macOS and on Linux withbwrap. Until then, any agent process running as your OS user can read the file, and so gets owner-level control. On Windows and on Linux withoutbwrapthere is no sandbox, even after 1683: your own private agent sessions can read the file, while sessions for other people run contained or talk-only (no file or shell tool).
Useful start flags: --port <port> / --listen <target> (listen target), --home <path> (state directory, default ~/.cyborg7), --replace (take over from an already-running daemon after an update), --relay / --no-relay (enable or disable the relay connection; --no-relay is fully local), --relay-use-tls (wss:// relay connection), --no-mcp (turn off the agent MCP HTTP endpoint), --no-inject-mcp (do not auto-add that MCP to new agents), and --hostnames <hosts> (comma-separated hostnames the daemon accepts).
Update
cyborg daemon update
Pulls the latest published bundle (or the latest code, in a source checkout), restarts the daemon onto it, verifies it comes back online, and rolls back if it doesn’t. If the Cyborg desktop app manages the daemon in this home, the command refuses: update the app instead. Live terminals survive the restart because they run in a detached pty host process, not in the daemon itself.
Flags: --force (update and restart even when already on the latest version), --no-build (skip the build step in a source install), --timeout <seconds> (how long to wait for the old daemon to stop, default 15), --verify-timeout <seconds> (how long to wait for the new one to come online before rolling back, default 30), plus --home, --port and --listen.
Claim a daemon
claim attaches a headless daemon to your account and points it at the Cyborg relay. It writes daemon-owner and cyborg-relay-url into the daemon home. The relay is resolved once, at boot, so restart the daemon after claiming it.
cyborg daemon claim # claim it for the currently logged-in user
cyborg daemon restart # required: the relay is resolved at boot
cyborg daemon set-password # protect direct (non-relay) connections
Claiming is how a headless daemon shows up in the app’s machine list. If the daemon is already claimed by another user, cyborg daemon claim --force reassigns it to you. See Add a daemon for the full walkthrough.
Join with a setup code
A workspace machine (internally a “Worker”) serves one workspace and runs agents for its members. A machine becomes one only by redeeming a one-time setup code (CYB-XXXX-XXXX); a workspace admin makes the code, and redeeming it needs no account and no login on that machine:
cyborg machine:invite-worker <workspace-id> --label "Rack 4" --role operator # admins; prints the code once
CYBORG_SETUP_CODE=CYB-XXXX-XXXX cyborg daemon join # on the new machine (or --code, visible in ps)
cyborg daemon restart
machine:invite-worker takes --role viewer|operator|restricted (what every member gets on the machine; default restricted, no access until granted) and --label (shown while it joins). The code is valid for 24 hours and once only, and it is never shown again: a lost one is cancelled in the app and replaced. -q prints only the code, and --json returns it with its invite id and expiry. daemon join takes --relay <url> (another relay), --home <path> (the state directory) and --force (rebind a home that is already claimed; it keeps its machine id, so the relay still refuses one that belongs to another account).
One step, on the machine itself. A workspace admin signed in on the new machine (cyborg login) can do both halves at once:
cyborg daemon add-worker --workspace <workspace-id> --role operator --service
It creates the code and redeems it straight away into a daemon home and port of its own (default ~/.cyborg7-worker, and the first free port after the personal daemon’s, which it saves in that home’s config.json), so a personal daemon on the same machine keeps running untouched. It first prints its plan and asks; --execute carries it out without asking, and with no terminal and no --execute it changes nothing. It refuses before creating anything when:
--homeis the personal daemon’s home, also through a symlink or as a copy with the same machine id (always, even with--force);--homealready belongs to a claimed daemon (--forcere-enrolls it, for a workspace machine you are setting up again);--portis taken, by another daemon on the machine or by any other program;--serviceis asked for where there is neither systemd nor launchd, or its service file already exists: a file that runs this same home is rewritten only with--replace-service, and one that runs any other daemon never is.
If the code is refused, it is cancelled again, so no unused code is left behind, and the error says so. A failure after the machine joined (saving its port, writing the service) says that it joined and how to finish by hand. Other flags: --label, --home <path>, --port <port>, --memory-max <size> (default 4G), --json. It always talks to the relay you are signed in to, never to a daemon.
--service installs and starts it as a systemd user unit on Linux or a launchd agent on macOS. The name comes from the home’s whole path (cyborg7-worker-<hash> for ~/.cyborg7-worker), so it is never the personal daemon’s cyborg7-daemon unit and two homes never share one; the command prints the exact name and how to check it. The systemd unit has --replace, KillMode=process, MemoryMax, Restart=on-failure, StartLimitBurst=5, and an optional EnvironmentFile (~/.config/cyborg7/<unit>.env, created once, 0600, never rewritten) for secrets such as CYBORG7_CRED_KEY, as the installer’s own unit has. launchd enforces no memory cap and reads no env file. Check it with systemctl --user status <unit> and journalctl --user -u <unit> -f (Linux), launchctl print gui/$(id -u)/com.cyborg7.<unit> (macOS), and cyborg daemon status --home ~/.cyborg7-worker. On Linux, run sudo loginctl enable-linger $USER once so it starts at boot without a login. The installer restarts only the personal daemon after an update; restart the workspace machine with systemctl --user restart <unit>.
The CLI does not turn an existing personal machine into a workspace machine in place. From the CLI a machine becomes one only by redeeming a code into a home of its own. A code redeemed by a daemon that is already the inviter’s personal machine is refused (daemon_is_personal) and stays unused. The Cyborg desktop app can convert such a computer from its join screen: it redeems the same setup code under a new machine id, moves the personal state into an archive folder and turns the old sign-in off. A daemon that belongs to another account is refused (daemon_owned_elsewhere), and daemon join never gives a home that already has an owner a new machine id to get past that, even with --force. daemon add-worker refuses the personal home before it even makes a code. machine:workers <workspace-id> lists a workspace’s workspace machines with their online state and default role.
cyborg daemon pair is retired in the cyborg command: it prints a pointer to claim and exits with status 1. Use claim or join.
Workspaces & channels
Most commands take a workspace id as their first argument. Get one with ws:list.
cyborg ws:list
cyborg ws:create "My Team"
cyborg ch:list <workspace-id>
cyborg ch:create <workspace-id> engineering
cyborg ch:update <workspace-id> <channel-id> --name ops --description none --private
cyborg ch:archive <workspace-id> <channel-id> # --unarchive to bring it back
cyborg ch:delete <workspace-id> <channel-id> --yes
cyborg ch:members <workspace-id> <channel-id> # people and agents (KIND: person / agent)
cyborg ch:add-member <workspace-id> <channel-id> <user-id> # a person, or an agent (cybo_…)
cyborg ch:remove-member <workspace-id> <channel-id> <user-id> --yes # an agent (cybo_…) too; fails if it stays
ch:add-member also takes an agent id (cybo_…) and adds that agent to the channel, with the same rule as adding it in the app: a workspace owner or admin, a channel admin, or any member of a public channel (for a private channel you must be in it).
Outbound event subscriptions
With relay flag CYBORG7_OUTBOUND_SUBSCRIPTIONS=1, workspace members with manage_webhooks can
manage their own subscriptions. These commands configure only; they do not send test events.
cyborg webhook:outgoing:list <workspace-id>
cyborg webhook:outgoing:create <workspace-id> --file subscription.json
cyborg webhook:outgoing:replace <workspace-id> <subscription-id> --file subscription.json
cyborg webhook:outgoing:delete <workspace-id> <subscription-id> --yes
The JSON contains name, public HTTPS url, and events (for example ["task.created"]), with
optional filter (mingo JSON), active and legacySignatures. Replacement supplies the complete
configuration and revokes pending deliveries. Creation prints a signing secret once. Both signature
formats remain enabled unless the owner explicitly sets legacySignatures: false.
Agents may read safe metadata with cyborg7_manage_webhook action outgoing_list; creating,
changing or deleting outbound destinations remains person-only. The tool never returns secrets,
URLs or filters.
Channel webhooks
Inbound webhooks post to a channel (the same ones as the channel’s Webhooks settings). A workspace owner or admin manages them, and so does an admin of the channel who is a workspace member or above. A workspace viewer cannot, even with a channel-admin seat.
cyborg webhook:list <workspace-id> <channel-id>
cyborg webhook:action-plan <workspace-id> <channel-id> --source <id> --plan <json> [--json]
cyborg webhook:sources <workspace-id> <channel-id> [--source <id>] [--json]
cyborg webhook:rule:state <workspace-id> <channel-id> --source <id> --rule <id> [--mode observe|active] [--pause|--unpause] [--confirm]
cyborg webhook:rules <workspace-id> <channel-id> [--source <id>] [--rule <id>] [--json]
cyborg webhook:rule:create <workspace-id> <channel-id> --source <id> --plan '<json>' [--json]
cyborg webhook:activity <workspace-id> [channel-id] [--source <id>] [--event <id>] [--limit <count>] [--outcome pending|succeeded|failed|ignored] [--cursor <cursor>] [--json]
cyborg webhook:retry <workspace-id> <channel-id> <event-id> --source <id> --execute [--yes] [--run <id>] [--action <id>] [--idempotency-key <uuid>] [--json]
cyborg webhook:replay <workspace-id> <channel-id> <event-id> --source <id> --execute [--yes] [--idempotency-key <uuid>] [--json]
cyborg webhook:cutover <workspace-id> [--on|--off] [--yes] [--json]
cyborg webhook:legacy-signatures <workspace-id> <webhook-id> [--on|--off] [--yes] [--json]
cyborg webhook:create <workspace-id> <channel-id> --events all [--name CI] [--signed] [--agent <cybo>] [--instructions <text>] [--inactive]
cyborg webhook:create <workspace-id> <channel-id> --events select --event push --event release
cyborg webhook:create <workspace-id> <channel-id> --events select --event pull_request --actions opened,ready_for_review
cyborg webhook:update <workspace-id> <webhook-id> [--name] [--events all|select|release] [--event <name> ...] [--actions <event.action,...> | --all-actions] [--agent <cybo> | --no-trigger-agent] [--instructions <text> | --no-instructions] [--active | --inactive]
cyborg webhook:delete <workspace-id> <webhook-id> --yes
cyborg webhook:rotate-secret <workspace-id> <webhook-id> [--clear [--execute]]
cyborg webhook:deliveries <workspace-id> <webhook-id>
cyborg webhook:redeliver <workspace-id> <delivery-id> [--execute] [--idempotency-key <key>]
webhook:create prints the Payload URL to send to (https://<relay>/api/webhooks/<channel-id>). With --signed, and on webhook:rotate-secret, the signing secret is printed once: save it then, it cannot be read back. --clear removes the secret, so deliveries are no longer signature-checked; it shows its plan first and needs --execute in a script (see Plan, approve, execute). --events release accepts only release events. --agent (alias --trigger-agent) takes an agent’s id or slug; you must be allowed to run that agent yourself. --instructions tells it what to do with each event (at most 4,000 characters); webhook:update --no-instructions clears them, as does an empty --instructions "".
With an agent set, each webhook event becomes a task assigned to that agent, with the instructions and the event attached. For now every webhook task reads and reports: the agent reads the event and puts what it found in the task result, and it does not change code. Write access for webhook tasks comes back with repo verification. Only the webhook’s creator may change its instructions, agent or secret.
--actions narrows an event to some of its GitHub action values, for example pull_request.opened,pull_request.ready_for_review. A bare action such as opened belongs to the single --event of the same command. The filter replaces the previous one, and --all-actions clears it. Only GitHub’s own events and actions are accepted: a misspelt name is refused, and the refusal lists the valid ones. Any other action of a listed event, or a delivery of it with no action, is ignored: it posts no card and wakes no agent. Events you don’t list keep every action. Once an agent is set, only the webhook’s creator can change its actions, as with its events.
webhook:sources and webhook:rules inspect the managed shadow projection of existing channel webhooks. --json includes rule filters and action configuration. These commands use the same workspace member floor and channel-admin gate as channel webhook configuration. Shadow rules never dispatch actions; existing delivery behavior remains authoritative. Agents inspect the same source and rule model with cyborg7_manage_webhook actions sources and rules, scoped by channel, sourceId and ruleId. The JSON source record includes its stable principal reference, frozen-v1 alias and owner pause state.
webhook:rule:create saves a named rule on the existing --source in the given channel. --plan is a JSON draft containing name, filter, actions and optional dailyCap; preview it first with webhook:action-plan. New rules start in observe mode, without executing actions. The CLI command is person-only and requires the channel configuration permission. Agents use cyborg7_manage_webhook action rule_create instead; their rules start paused and they cannot activate or unpause them. The owner confirms future execution separately with webhook:rule:state.
webhook:activity reads authenticated receipts, processing outcomes and ignored reasons. A person may omit the channel for workspace Activity; channel reads require the channel configuration permission. --source, --event and --outcome filter the results; --limit defaults to 50 and accepts 1–100, and --cursor continues a page. --json includes the receipt data and pagination cursor. Inside an agent this command routes through its own cyborg7_manage_webhook read tool: the workspace must match the agent credential and a channel is required. It cannot read an unscoped workspace feed or act as the person.
webhook:retry resumes failed work on a retained real event using its original action keys; --run selects the failed run and --action selects one failed action. webhook:replay processes a retained real event in a new run and may produce new effects. Both require the channel and --source, current person authorization, and --execute even at a terminal. Without it they return APPROVAL_REQUIRED and do nothing. Execution also requires confirmation: answer the terminal prompt, or pass --yes (required for scripts). Reuse --idempotency-key <uuid> when retrying the same operation request; otherwise the CLI generates one. Neither command accepts an agent credential, even with --execute --yes; agents cannot Retry or Replay through their tool either.
webhook:cutover reads whether the workspace’s incoming webhooks use the rules model, when it was enabled and whether rules are in sync. It is person-only; a workspace member can read, and a workspace admin can switch with --on or --off. A switch asks for confirmation; scripts need --yes. The default is off. Enabling requires synchronized, backfilled rules; --off restores the existing per-webhook path. Passing both switch flags is invalid.
webhook:legacy-signatures reads the legacy-signature setting for an outgoing webhook or agent trigger. It is person-only, and only that webhook’s owner can change it. --off stops the legacy X-Cyborg7-Signature headers and asks for confirmation (--yes in scripts); --on restores them. Standard Webhooks signatures remain enabled, legacy signatures default on, and there is no automatic cutoff. Passing both switch flags is invalid.
These six commands follow C5 exit codes: success exits 0, bad arguments or operational failures exit 1, permission or agent-scope refusals exit 2, missing execution approval or confirmation exits 3, and state/version conflicts exit 4. In particular, agent Retry/Replay returns AGENT_COMMAND_UNAVAILABLE, a cross-workspace Activity read returns CROSS_WORKSPACE, and an unscoped agent Activity read returns FORBIDDEN, all with exit 2. Refusing confirmation returns CONFIRMATION_DECLINED (exit 2); omitting confirmation in a script returns CONFIRMATION_REQUIRED (exit 3). --json preserves the error code on stderr.
webhook:list shows each webhook’s events, its action filter, whether it is signed, its agent, active state, the agent’s access (read_only for now) and its instructions.
webhook:redeliver posts a stored delivery to its channel again, so it shows its plan first and needs --execute in a script. Only an original delivery can be redelivered: a delivery that is itself a redelivery (REDELIVERY OF in webhook:deliveries) is refused with IS_REDELIVERY. Each person may redeliver at most 10 times a minute (RATE_LIMITED past that). With --idempotency-key <key> (1-128 letters, digits, ., _, : or -), running the same command again answers the first redelivery’s message instead of posting twice, while that redelivery is still in the webhook’s delivery log (its 50 newest). Every redelivery is in your Logs with who sent it.
Agent triggers
An agent trigger calls your bot’s URL when one of your agents is mentioned or messaged (see Agent triggers). The agent’s owner or a workspace admin manages them.
cyborg trigger:create <workspace-id> <agent> --url <https-url> --on mention,dm[,thread] [--from-agents] [--rate <n>] [--name <name>] [--auth-header-stdin | --auth-header-env]
cyborg trigger:list <workspace-id> [<agent>]
cyborg trigger:update <workspace-id> <trigger-id> [--url] [--on] [--from-agents | --no-from-agents] [--rate <n>] [--name] [--auth-header-stdin | --auth-header-env | --clear-auth-header] [--rotate-secret] [--active | --inactive]
cyborg trigger:delete <workspace-id> <trigger-id> --yes
cyborg trigger:test <workspace-id> <trigger-id> [--execute]
cyborg trigger:deliveries <workspace-id> <trigger-id> [--limit <n>]
cyborg trigger:replay <workspace-id> <trigger-id> <delivery-id> [--execute]
<agent> is an agent’s id or slug. --on lists what fires the trigger: mention, dm, and thread (replies in a thread the agent already spoke in). --rate is how many deliveries the trigger may start a minute, 1 to 60 (default 10). trigger:create prints the trigger’s id and its signing secret, once.
The Authorization value your bot expects (for example Bearer <key>) is never an argument, so it stays out of your shell history: pipe it in with --auth-header-stdin, or put it in CYBORG_TRIGGER_AUTH_HEADER and pass --auth-header-env. trigger:list shows only its last four characters. A new --url, or --rotate-secret, drops the stored value unless the same command sends a new one.
trigger:test sends one synthetic agent.triggered with "test": true and prints your bot’s HTTP status; it counts against the trigger’s rate, and each test is in Logs with who sent it and what the bot answered. trigger:test and trigger:replay call your bot with its stored key, so both show their plan first and need --execute in a script. trigger:deliveries lists the latest deliveries (20 by default, --limit up to 100): time, reason (mention, dm, thread_followup or test), status (success, failure, rate_limited for a match that was over the rate, or dropped for a delivery dropped because the trigger was repointed, re-keyed or switched off before it was sent), HTTP code, attempt, the X-Cyborg7-Sequence it carried (SEQ) and whether it was dead-lettered (DEAD). trigger:replay sends one dead-lettered delivery (its DELIVERY id) once more: the original body, signed fresh, under the same delivery id and a new sequence; it never switches the trigger back on (see Replay).
External agents
cyborg agent:external:create <workspace-id> --name <name> --handle <handle> --channels <channel,...>
cyborg agent:external:connect-message <workspace-id> <agent>
cyborg agent:external:sign-in-link <workspace-id> <agent>
cyborg agent:external:status <workspace-id> <agent>
cyborg agent:external:presence <workspace-id>
cyborg agent:external:test <workspace-id> <agent> --channel <channel>
The terminal side of New agent → Connect an external agent (see Connect Grok Bot). An external agent is a member whose replies come from a bot outside Cyborg: it has no provider, no model and no machine, and Cyborg never runs a turn for it. agent:external:create makes one, seated in the channels you list (names, with or without #, or ids; you must be allowed to add an agent to each). agent:external:connect-message prints the message to send the bot: the workspace’s MCP address and the agent to pick on the Cyborg sign-in, never a token. agent:external:sign-in-link is for a sign-in that failed: for 30 minutes your Cyborg consent screen preselects this agent (you still confirm it), and it prints what to tell the bot. agent:external:status shows its channels, whether a bot is connected as it and when it was last used, and its trigger. agent:external:presence lists every outside bot of the workspace with the state the app shows: online (its trigger is on and its last call worked, or it used its key in the last 15 minutes), paused (its owner switched the trigger off), error with why (its last call failed, or its sign-in was removed) or offline (not called yet); any member may read it. Then wake it with trigger:create (Agent triggers) and run agent:external:test: it mentions the agent once in a channel you are both in, as you, and waits up to two minutes for four checks (the routine was called, the bot read as the agent, it replied in the thread, and nothing else answered), each with what to do when it fails. trigger:test still sends a synthetic call without posting anything. Creating one follows the agent-creation permission; the rest is for the agent’s owner or a workspace admin. All six are refused inside an agent.
MCP keys
cyborg mcp-token:list <workspace-id> [--acting-as <agent> | --person <user-id>]
cyborg mcp-token:create <workspace-id> --name <name> [--acting-as <agent>] [--scope read|write|read,write] [--expires-in-days <n>]
cyborg mcp-token:revoke <workspace-id> <key-id> [--acting-as <agent> | --person <user-id>] --yes
mcp-token:list shows your keys and who each one acts as: you, or an agent ((deleted) once that agent is gone). With --acting-as or --person it lists the keys acting as that agent or person with a CREATED BY column, the same list as the Access tab of their profile: every key for the agent’s owner, the person themself or a workspace admin; for anyone else, only the agent keys they made themselves (and they can revoke those). --person takes a user id, not an email. mcp-token:create makes a key that acts as you, or as an agent you may run with --acting-as, and prints it once. If the relay does not answer in time, it tries once more with the same request: a key the first try created but could not show is replaced, never left behind as a second key, and the command says so. Use it with the workspace’s MCP connection URL from Settings → API & MCP. mcp-token:revoke revokes one of your keys, or, with --acting-as / --person, any key acting as that identity that you may see; whatever uses it stops working at once.
Your signed-in devices
cyborg device:list
cyborg device:revoke <session-id> --yes
cyborg device:revoke-others --yes
cyborg device:events [--range today|yesterday|7d|30d]
cyborg device:quarantine <event-id>
cyborg device:restore <event-id> (--item <id>... | --all-before-alert) [--code <code>]
device:list shows your signed-in devices with place, network and a masked IP (the full IP is only in the app, never in a terminal). device:revoke signs out one device; device:revoke-others signs out every device except the one you are on, and says so plainly if your relay is too old to do that (exit 4, NOT_SUPPORTED). device:events lists security events such as new sign-ins (default --range 7d); its NOT ME column says what “Not me” did on that alert (frozen, restored, deleted after 14 days, removed). device:quarantine lists what one “Not me” froze and until when it can be restored. device:restore restores it with the same code from your email that Logs in the app asks for, in two steps:
- Run it without
--codeto have the code emailed to you. - Run it again with
--code <code>to restore.
Name what to restore with --item <id> (repeatable, ids from device:quarantine) or with --all-before-alert (everything made before the alert, like the app’s “Restore everything made before the alert”; anything made after the alert must be named with --item). The result lists each item as restored or refused, with the app’s reason. A wrong or used code is refused (CODE_REJECTED): run it again without --code for a new one. Run both steps from the same login, because the code is tied to the session that asked for it. --json prints the same rows. These are yours alone: they are refused inside an agent.
Their first names, sessions:list, sessions:revoke, sessions:revoke-others, sessions:events, sessions:quarantine and sessions:restore, still work as aliases. They are not session:list, which lists agent sessions on machines (see Sessions on any machine).
Members and invitations
cyborg member:list <workspace-id>
cyborg member:invite <workspace-id> someone@example.com [--role admin|member|viewer] [--channel <channel-id>]
cyborg member:role <workspace-id> <user-id> admin # owners only
cyborg member:remove <workspace-id> <user-id> --yes
cyborg memory:purge-person <workspace-id> <user-id> --yes # admins: erase a person's memory, counts only
cyborg memory:purge-person <workspace-id> <user-id> --dry-run [--offboard] # preview the counts; changes nothing
cyborg cockpit:revoke <workspace-id> <agent-id> <user-id> --yes # take back a teammate's cockpit access to a live session
cyborg invite:list <workspace-id> # pending invitations
cyborg invite:resend <workspace-id> <invitation-id>
cyborg invite:cancel <workspace-id> <invitation-id>
cyborg join:list <workspace-id> [--status pending] # requests from your claimed email domain
cyborg join:approve <workspace-id> <request-id> [--role viewer]
cyborg join:reject <workspace-id> <request-id>
cyborg onboarding:arrival <workspace-id> # your own arrival: agents, channels, where you land
Commands that cannot be undone from here (ch:delete, ch:remove-member, webhook:delete, trigger:delete, member:remove, cockpit:revoke, memory:purge-person, msg:delete, schedule:delete, machine:revoke, machine:remove, cybo:delete, task:delete, task:view-delete, page:delete, skill:delete) ask for confirmation at a terminal; in a script (stdin is not a terminal) they refuse with CONFIRMATION_REQUIRED unless you pass --yes, and a “no” at the prompt exits with CONFIRMATION_DECLINED. The relay decides who may do what; its refusal exits non-zero with its code (FORBIDDEN, PRO_REQUIRED, SEAT_LIMIT_REACHED, …). See Exit codes for which status each one leaves with.
memory:purge-person and the compliance delete in Settings remove the memory at once. Deleted memory is removed immediately; encrypted database backups keep copies for up to 14 days before they expire.
Messaging
cyborg send <workspace-id> <channel-id> "deploy is out" # waits for the relay to confirm (else SEND_UNCONFIRMED, exit 1)
# "queued" (exit 0, --json {"queued":true,…}): the relay delivers it; do not resend
cyborg listen <workspace-id> <channel-id> # stream messages live (Ctrl-C to stop)
cyborg slash <workspace-id> <channel-id> summarize # run a channel slash command, wait for the result
cyborg msg:list <workspace-id> <channel-id> [--limit 50] [--cursor <message-id>]
cyborg msg:search <workspace-id> "deploy" [--channel <channel-id>] [--from-me | --from <ids>] [--mentions | --mentioning <ids>] [--has-link | --has-file] [--limit 50]
cyborg msg:get <workspace-id> <message-id>
cyborg msg:attachment <workspace-id> <message-id> [--index 1] [--out <dir>] # download its attachments
cyborg present <path> --title "Q3 report" [--kind markdown] # inside an agent: show a file as a Preview card
cyborg msg:edit <workspace-id> <message-id> "fixed text" # your own messages
cyborg msg:delete <workspace-id> <message-id> --yes
cyborg msg:react <workspace-id> <message-id> 👍 # toggles your reaction
cyborg msg:pin <workspace-id> <channel-id> <message-id> # --unpin to undo
cyborg thread:list <workspace-id> [--unread] [--cursor <cursor>]
cyborg thread:get <workspace-id> <root-id>
cyborg thread:reply <workspace-id> <channel-id> <root-id> "on it" # waits for the relay to confirm
cyborg thread:follow <workspace-id> <root-id> # --off to stop
send posts to a channel only; it has no direct-message form. Inside a session, reach a person with send <workspace-id> <channel-id> "…" --mention <user-id>. A session sends no Cyborg direct message; in Slack it reaches a person only as the owner; the tool asks the session to show the owner the exact text and send only after their OK.
msg:search searches the messages you can see, newest match first, in one --channel or the whole workspace. The query is optional when a filter is given: --from-me / --from <ids> (who sent it), --mentions / --mentioning <ids> (who it @mentions), --has-link, --has-file; --limit is 1–100 (default 50).
msg:get and msg:list show each attachment’s name, type, size, width/height and key (a FILES count in the table, the list under attachments with --json); an oversize file is marked oversize: true, and one without a key cannot be downloaded. msg:attachment downloads them with your saved login: every downloadable attachment, or one by its 1-based --index, into --out (default the current directory). The relay decides who may read each one, and its refusal reads as NOT_FOUND. A file name is reduced to a basename every system accepts (no control, format such as bidi overrides or zero-width, or Windows-reserved characters or names, at most 200 UTF-8 bytes) and never overwrites an existing file: the next free name (n).ext is used, written with mode 0600 (an exclusive copy where the disk has no hard links, such as FAT). A slow download keeps going; one that sends nothing for two minutes stops as interrupted. It is refused inside an agent; an agent reads what it was sent through its cyborg7_* tools.
present runs only inside an agent session, as that agent (its cyborg7_present tool). It shows a file from the agent’s own folders as a card that opens in the side Preview panel, posted with the agent’s next message, so whoever can read that message can open it. The path is relative to the current directory; a file outside the session’s folders, reached through a symlink or .., or over its kind’s size limit is refused. --kind is one of html, image, markdown, json, yaml, mermaid, svg, csv, pdf, xlsx and defaults to the extension. Outside an agent it is refused.
msg:list and thread:list read a page at a time. With --json they print { messages | threads, nextCursor }; in a table or with -q the next page’s full command goes to stderr.
slash accepts --no-wait (dispatch only) and --timeout <seconds> (default 120). Set model preferences for channel AI commands like /summarize:
cyborg slash:model <workspace-id> <provider> <model> # your personal preference
cyborg ch:model <workspace-id> <channel-id> <provider> <model> # per-channel override
Run either without provider/model to see the current value; pass --clear to reset (back to auto-resolve / the inherited default).
Agents
An agent is a live AI session running on a daemon. Inside an agent these commands act as the agent, within its own permissions, and an agent with Spawn other agents can also create and delete agents; see Inside an agent.
cyborg agent:create <workspace-id> --provider claude --channel <channel-id> --cwd ~/repo
cyborg agent:create <workspace-id> --daemon <machine-id> # on another machine (cwd: its ~)
cyborg agent:list <workspace-id> [--daemon <machine-id>]
cyborg agent:prompt <workspace-id> <agent-id> "run the test suite and summarize failures"
cyborg message <workspace-id> <session> "the build is green" [--wait] [--timeout <s>] # one message to a session
cyborg agent:stop <workspace-id> <agent-id> # interrupt a stuck run
cyborg agent:mode <workspace-id> <agent-id> acceptEdits # Claude: plan | default | acceptEdits | auto | bypassPermissions (Codex: auto | auto-review | full-access | plan)
cyborg agent:model <workspace-id> <agent-id> <model> # 'default' clears the override
cyborg agent:alias <workspace-id> <agent-id> "Reviewer" # your own name for a session (on your own session: the name everyone sees); --clear removes it
cyborg agent:aliases # the names you have given
agent:prompt streams the reply. --wait prints only the final reply, --json prints { reply, promptId, promptAttemptId }, --timeout <seconds> bounds the wait (default 120), and --no-stream only dispatches. For a busy agent: by default the prompt is held and runs after the running turn, never interrupting it; --steer joins the running turn, and --queue makes the CLI wait for the turn to end before it sends. <agent-id> may be a unique id prefix.
cyborg message <workspace-id> <session> "<text>" sends one message to one of your sessions and returns once it is on its way; a busy session takes it after its running turn. <session> is a session id or a unique prefix of it. --wait prints that session’s reply, --timeout <seconds> bounds that wait (default 120), --daemon <machine-id> targets one machine, and --json prints the result as JSON. The command exits 0 when the message was sent, and otherwise with the status of its code (see Exit codes).
The same command works inside an agent, where it runs the agent’s own cyborg7_message tool and prints the tool’s one line; inside an agent agent:prompt does the same. There <session> may also be the session’s shared name, your alias for it, or the name or id of an agent of the workspace; the answer arrives in the agent’s session as a message, so --wait and --timeout are refused; and a message recorded for an offline machine or already sent counts as sent. See Message another session or agent.
Inside an agent
An agent can run cyborg in its own shell. There the CLI never uses your login: each command acts as the agent, through the agent’s own tools and permissions, or it is refused before it sends anything. A terminal you open yourself is unchanged.
Each command below is a front for one of the agent’s own cyborg7_* tools, and the tool is the agent’s first choice: it works on every provider, while a command that needs a turn works only in a shell that proves one (see the rules below).
What each permission unlocks inside an agent:
| Permission | What it unlocks |
|---|---|
| Manage tasks | Create, update, archive and delete tasks |
| Manage channels | Create, rename and archive channels, and change their members |
| Spawn other agents | Create, update, start and delete agents, change another agent’s schedules, seat an agent in a channel |
| Prompt your sessions | Send a prompt or a command (agent:mode, agent:command) to its owner’s own sessions, on a turn the owner asked for |
| Edit its own memory | Its own memory notes |
| Bypass permissions | Its own turns skip permission prompts, and terminals it opens inherit that; agent:mode acceptEdits when both agents hold it. An agent never puts another session in a bypass mode |
An agent that lacks one does not send you to settings: in its 1:1 DM with you it calls cyborg7_ask_for_permission, and you get a one-tap card in that DM. Only you, as the agent’s owner, can approve it there. A scheduled, task, watcher or Slack turn gets the plain refusal and no card.
These commands act as the agent. The agent’s own permissions decide each call, so a command may still answer with a refusal (for example, scheduling another agent needs the agent’s “spawn other agents” permission).
| Command | What it does inside an agent |
|---|---|
send, thread:reply, msg:list, msg:react | Post, reply, read and react in the agent’s channels |
message, agent:prompt | Send one message to a session or agent; the answer arrives in the agent’s session later |
ch:list, ch:create, ch:members, member:list, cybo:list | Channels and people of the agent’s workspace |
task:create, task:list, task:get, task:update, task:archive, task:delete, task:bulk-update, task:states, project:list | Tasks |
page:list, page:get, page:create, page:update, page:move | Pages |
schedule:list, schedule:create, schedule:update, schedule:pause, schedule:resume, schedule:delete | Schedules |
session:list, agent:list, agent:aliases, agent:history | The sessions of the person the agent is working for |
agent:state, agent:receipt, agent:context, agent:subagents, agent:wait, agent:follow | Read a session (see below) |
agent:stop, agent:model, agent:thinking, agent:alias, agent:archive, agent:restore, agent:reload, agent:clone, agent:rewind, agent:fork, agent:create | Control a session (see below) |
slash, listen | Run a channel slash command; wait for new messages in a channel |
skill:list, skill:get, skill:files:list | The skills assigned to the agent |
thread:get | Read a thread the agent may read, found from any of its messages |
memory:list, memory:show, reminder:list, reminder:cancel (promise:list, promise:cancel) | The agent’s own memory and reminders; <cybo> must be the agent itself |
terminal ls, create, kill, capture, send-keys, watch | The terminals the agent opened, with its “open terminals” permission |
whoami, status, ws:list, provider:acp-catalog | The agent’s own id and workspace, from its credential; the ACP catalog, from the CLI’s own copy |
ch:update, ch:archive, ch:delete, ch:add-member, ch:remove-member, ch:model | Administer a channel the agent is in (needs the agent’s “manage channels” permission) |
msg:get, msg:edit, msg:delete, msg:pin, thread:list | Read a message in the agent’s channels, edit or delete the agent’s own messages, pin, list the agent’s threads |
machine:list, machine:requests, machine:request, invite:list, join:list, skill:search | The workspace’s machines, invitations, join requests and public skills, as the person asking sees them |
provider:list, provider:check, provider:refresh | The providers of the machine the agent runs on (--daemon may only name that machine) |
memory:history | Who wrote each version of one of the agent’s own memory notes |
task:search, task:activity, task:links, task:attachments, task:comment | Search tasks, read a task’s activity, links and attachments, comment as the agent |
task:views, task:view-create, task:view-update, task:view-delete | A project’s saved views; the agent changes only views it made |
page:search, page:access, page:delete | Search pages, see who reads your own private page, delete a page |
project:create, project:update | Create, rename or recolour a project |
schedule:runs, schedule:run | A schedule’s run history, and one run now of the agent’s own schedule (see below) |
Inside an agent, ch:add-member with another agent’s id seats that agent only when the agent also holds “spawn agents”, a person is asking it now (a DM, mention or thread they typed), and that person could add the agent in the app.
Agent management for the person asking
These run only for a person asking the agent now (a DM they typed, a mention or a thread reply; never a schedule, a task, a watcher or another agent), only when that person may run agents on the agent’s machine, and only as far as that person could do it themselves. None of them gives any agent more than it already holds.
| Command | Inside an agent | Also needs |
|---|---|---|
cybo:update | Changes name, description, avatar, role, soul, provider or model of an agent the person may edit. A permission it adds must be one the agent holds. --home-daemon and --tool-grants are refused. | The Spawn other agents permission |
cybo:spawn | Starts a session of an agent whose home machine is the agent’s own machine (default directory: where the command runs). --daemon is refused. | The Spawn other agents permission |
agent:mode | Sets the mode of one of the person’s own sessions on the agent’s machine. Never above the agent’s own grant: acceptEdits needs the bypass grant on the agent and on that session’s agent, and bypassPermissions and full-access are always refused. | The Prompt sessions permission |
agent:command | Runs /goal, /compact, /clear, a skill or a custom command in one of the person’s own sessions on the agent’s machine. Commands that change permissions, the model, tools, login or setup (for example /permissions, /model, /mcp) are refused. | The Prompt sessions permission |
memory:undo-replace, memory:sensitivity | The person’s controls over the agent’s own memory. Sensitivity can only be raised; lower it yourself in the Memory tab. | The Manage memory permission |
skill:create, skill:update, skill:delete, skill:files:rm, and skill:import / skill:sync with --dry-run | The workspace’s skills, when the person may manage skills (owners and admins). skill:sync reads the folder in the agent’s shell. skill:files:rm stops at its plan for a person to run. An import, a real sync and any bundled file are a person’s (see below). | — |
skill:assign, skill:unassign | A skill the agent may use itself, to itself or an agent it created, when the person may edit that agent. | — |
slash:model | The asking person’s own model for channel AI commands. | — |
ws:create | A new workspace owned by the person asking. The agent stays in its own workspace. | — |
An agent without the permission a command needs is told which one and how to ask for it: Error (lacks_grant): this agent does not hold the spawn_agents permission that cyborg7_create_agent needs. Ask your owner for it with cyborg7_ask_for_permission ….
Rules that apply to all of them:
- The workspace must be the agent’s own; any other is refused.
- Inside an agent, call the CLI as
"$CYBORG_CLI"(the daemon’s own CLI) when a login or interactive shell may reorder PATH: a user’s~/.zshrcor~/.bashrcthat puts~/.local/binfirst can make barecyborgresolve an older CLI, and a CLI found elsewhere gets no turn. - A command acts on a turn only when its shell proves that turn: a Claude agent in bypass-permissions mode gets a proof for each Bash command, valid while that command runs, and a Pi agent one for each bash command, usable once. Elsewhere (Codex, OpenCode, ACP, other Claude modes, a detached process) a command that needs a turn is refused and names the
cyborg7_*tool to call instead. - An option the agent’s tool cannot carry out is refused by name, never ignored. For example
agent:prompt --wait,--steer,--queueand--timeout,session:list --archived,agent:history --fulland--raw,page:move --sort-order,task:bulk-update --archived,schedule:update --task,memory:show --venue,terminal capture --historyand--daemonon the schedule and terminal commands. task:delete,schedule:delete,ch:delete,ch:remove-member,msg:delete,page:deleteandtask:view-deleteneed--yes.terminal watchneeds--duration(an agent cannot press Ctrl-C) and prints the lines it saw once the terminal ends or the time is up.terminal send-keysstops working on a terminal once a person has typed into it; the agent opens a new one instead.terminal createopens the agent’s shell in its project directory.- A command that changes or lists something on a person’s behalf (channel administration, pins, machines, invitations, join requests, memory history, skill search, tasks, pages, projects, views) acts for the person talking to the agent on that turn, with that person’s own rights, and never beyond the agent’s own: on a scheduled run with nobody asking, for the agent’s owner; outside a turn it is refused. The agent never makes a channel public, writes a channel’s instructions (
ch:update --publicand--instructionsare refused), adds an agent to a channel, or edits or deletes anyone’s message but its own.machine:requestonly asks the machine’s owner; nothing is granted until they approve.thread:list --unreadand--cursorare refused. Tasks, pages, projects and views work the same way: the task, page or project must be one both the person and the agent can see, and comments, project names and view names pass the same privacy check as a post.page:accessonly reads who already has access to the person’s own page; it never grants. - A write succeeds only when the agent’s tool confirms it. The status comes from the tool’s typed answer, never its wording: a refusal the tool types as denied exits
2, a write held for its owner’s OK exits3(APPROVAL_PENDING; do not send it again), a conflict exits4, and a failure the tool does not type, or an answer without the tool’s success sentence (AGENT_TOOL_UNCONFIRMED), exits1. Each prints the tool’s own text.
Schedules and skill writes inside an agent
schedule:run(and the agent’scyborg7_schedule_run_nowtool) runs only the agent’s own schedules, at most once a minute per schedule. Another agent’s schedule is refused withError (owner_only), exit 2 (FORBIDDEN), whatever the agent’s permissions; the refusal names the command for a person to run (cyborg schedule:run <workspace-id> <schedule-id> --execute) or the app’s Run now. A session that is not an agent has no schedule of its own, so it is refused the same way.--executeis accepted inside an agent and changes nothing.- Changing another agent’s schedule (
cyborg7_schedule_update, or resuming it withcyborg7_schedule_set_enabled) takes what scheduling that agent takes: the Spawn other agents permission and a person asking now; an autonomous run is refused. Pausing it stays allowed. - Importing a skill (
skill:import), syncing skills (skill:sync) and adding or replacing a skill’s bundled file (skill:files:put, and the same file sent byskill:create --dirorskill:update --dir) are a person’s, never an agent’s. The relay refuses them withError (owner_only), exit 2 (FORBIDDEN), whether the agent uses the CLI or its tool, and asks a person to do it (cyborg skill:import,skill:sync,skill:files:put, or the Skills page).--dry-runof an import or a sync still runs: it writes nothing.
Every refusal is recorded in the workspace Logs as a refusal, never a failure. The import, sync and bundled-file refusals above stay refusals: no tap approves them. A skill change that waits for a person instead (changing another agent’s skills, or any change after the agent read outside content) is a one-tap card in that person’s DM with the agent, and nothing changes until they tap it.
Sessions and channels inside an agent
The session commands work inside an agent too, through the agent’s own session tools. The relay decides every call:
- The agent reads and controls its own session at any time, and the sessions of the person it is working for that run on the same machine. Another person’s session is answered like one that does not exist; a session on another machine is refused (message it with
cyborg messageinstead). - Reading (
agent:state,agent:receipt,agent:context,agent:subagents,agent:wait,agent:follow) works on any turn. - Changing a session (
agent:stop,agent:model,agent:thinking <level>,agent:alias,agent:archive,agent:restore,agent:reload,agent:clone,agent:rewind,agent:fork), creating one (agent:create) andslashneed that person to be asking now (their DM, a mention or a thread reply) and to be allowed to run agents on that machine. A schedule, a task or another agent’s ask is refused. The agent’s own session is the exception. - The agent acts with that person’s own rights, never an owner’s or an admin’s: a workspace admin’s agent cannot reach a colleague’s session.
agent:wait,agent:follow,slashandlistenwait at most 50 seconds per call; run them again to keep waiting. A--timeoutabove 50 is refused by name.agent:followreturns what the turn wrote once it ends;--foreveris refused.listenreturns the new messages of a channel the agent is in.agent:createcreates a session on the agent’s machine with the agent’s own provider and permission mode;--channel,--system-promptand--daemonare refused.agent:restore --modeis refused: an agent never picks a permission mode.slashruns on the agent’s machine (--daemonis refused).
Every other command is refused inside an agent with <command> is not available to agents; it would act as your owner. These are yours alone, and the refusal says why: the daemon (daemon), signing in (login), raw RPC (rpc), machine administration (machine:rename, lend, restart, grant, revoke, remove, restore, approve, deny, invite-worker, workers), installing, adding or signing in providers (provider:install, update, sign-in, add-acp), provider usage and its settings (provider:usage, usage-hook, org-key: they show the accounts on a person’s computers), people (member:invite, role, remove, invite:resend, cancel, join:approve, reject), memory:purge-person, giving agents away (cybo:transfer, transfers, transfer-accept, transfer-decline, transfer-cancel), thread:follow (your own notification preference), channel webhooks (webhook:list, create, update, delete, rotate-secret, deliveries, redeliver; an agent with Manage channels manages unsigned webhooks, their agent and instructions with its cyborg7_manage_webhook tool instead), agent triggers (trigger:create, list, update, delete, test, deliveries, replay: they call an outside service with its owner’s key), external agents (agent:external:create, connect-message, sign-in-link, status, test: connecting an outside bot is its owner’s setup) and MCP keys (mcp-token:list, create, revoke: a credential a person holds), downloading attachments (msg:attachment: it uses a person’s own saved login) and your signed-in devices (device:list, revoke, revoke-others, events, quarantine, restore, also under their old sessions:* names).
Every command run inside an agent, refused or not, is recorded in the workspace Logs under that agent: the command, the tool, the outcome and how long it took, never its arguments or text.
Sessions on any machine
Every command here takes a session id or a unique prefix (the first 8 characters are enough) and searches all your workspaces unless you pass --workspace <id>.
cyborg session:list [--workspace <id>] [--archived [--search <text>]] # your sessions, every machine
cyborg agent:history <agent> [--before <cursor>] [--full] [--raw]
cyborg agent:export [agents...] --out <file.jsonl> [--machine <id>] [--since 7d|<date>] [--page <n>] [--on-machine]
cyborg agent:follow <agent> [--forever] [--timeout <s>] # stream the live turn
cyborg agent:wait <agent> [--until idle|running] [--timeout <s>]
cyborg agent:state <agent> # status, model, mode, attention, context use
cyborg agent:changes <agent> [--diff] # git branch and changed files of the session's folder (the Changes tab)
cyborg agent:receipt <agent> <prompt-id> # did that prompt reach the model?
cyborg agent:context <agent> # context an ephemeral agent session started with
cyborg agent:subagents <agent>
cyborg agent:archive <agent>
cyborg agent:restore <workspace-id> <session-id> [--daemon <machine-id>]
cyborg agent:reload <agent> [--rehydrate] [--cwd <path>] # restart a stuck session in place: same id, same history
cyborg agent:clone <agent> [--title <t>] [--dry-run] # copy a session, history included, into a new one
cyborg agent:rewind <agent> <turn> [--mode conversation|files|both] [--dry-run] [--execute]
cyborg agent:fork <agent> <turn> [--title <t>] [--dry-run] # a new session of yours, up to before that prompt
cyborg agent:thinking <agent> [level] # set the thinking level; no level lists the model's levels
cyborg agent:command <agent> <name> [args...] # run /goal, /compact, /clear, /model, a skill or a custom command on your own session
--cwd changes an idle Claude or Codex session’s directory on its machine while preserving its native conversation; the directory must pass that daemon’s access rules. --rehydrate also re-reads the provider’s history, for a session that is out of sync. <turn> for agent:rewind is the prompt’s SEQ number in agent:history or its message id; --mode files (and both) rolls back files too and works with Claude only; it shows its plan first and needs --execute in a script. Who may rewind depends on the conversation: a DM only its person; a session one person started, that person or a workspace admin; a session in a room (a thread, group DM or channel) only the prompt’s author, and never when someone else wrote after that prompt (the refusal is rewind_would_erase_others): fork from that prompt instead with agent:fork, which leaves the original as it is. A channel @mention’s session is never rewound. agent:fork keeps the agent’s memory up to the prompt when the provider can cut its own copy (Claude); otherwise the new session shows the conversation but the agent starts without remembering it, and says so. --dry-run shows what would happen and changes nothing. agent:export writes every stored row of each session, older pages included, one JSON line per row (agentId, workspaceId, daemonId, seq, timestamp, item), and prints a summary per session. It reads only what agent:history would show you: a session you may not read is skipped and named in the summary, and the rest are still written. --machine adds every session on that machine; --since stops at older rows. A row the relay served from its copy while the machine was offline carries partial: true (that copy keeps only a session’s latest rows). With --on-machine the session’s own machine writes the rows as gzip JSONL straight to a private bucket, so nothing passes through the relay, and --out gets one line per session with a download link valid for an hour; the file is deleted a day after upload. agent:changes is the session view’s Changes tab: the session’s machine reads its folder’s branch and changed files in a sandbox, for the same people who may read the session; --diff adds each file’s unified diff to --json, except for files that look like secrets. session:list is also available as sessions, agent:list as agents and ws:list as ws; session:list takes --limit <n>. --archived lists every archived session, agents’ runs included; add --search <text> to get what /resume shows: only your own sessions, one row each, matching the title, first prompt, folder or id.
Approvals waiting on you
cyborg approvals:list <workspace-id> [--agent <id>]
cyborg approvals:answer <workspace-id> <request> allow|deny [--agent <session-id>] [--reason <text>] [--execute]
cyborg approvals:wait <workspace-id> [--agent <id>] [--any] [--timeout <seconds>]
approvals:wait blocks until something new waits on you, then lists only what arrived while it waited (same rows as approvals:list); --any returns at once when something already waits. It wakes on the relay’s alert push and re-reads every 5 s, and fails with APPROVALS_WAIT_TIMEOUT after --timeout (default 600 s). A tool permission answered from the CLI shows “Allowed from the CLI” (or “Denied from the CLI”) on its settled card, and its Logs row and approval_answered event carry answeredVia and the device session the answer came from.
approvals:list shows what the app’s Needs you shows: tool permissions raised on your sessions (tool_permission, answerable here) and consent cards addressed to you (card, answered only in the app). approvals:answer allows or denies one tool permission through the same relay check as the app’s Allow / Deny button: workspace membership, the agent’s real workspace, the session’s person or the workspace owner, re-checked by the session’s machine. It shows its plan first and needs --execute in a script. --agent answers a prompt on a session you control that is not addressed to you; the relay still decides. --reason goes with deny and reaches the agent.
Three answers are always refused (exit 2, APPROVAL_ANSWER_REFUSED, the reason in details):
needs_human: a consent card (tool approval card, share, integration, permission grant or guest ask). Holding the login token does not prove a person is there, so the CLI lists these but never answers them; open the app on your phone or desktop.self_session: the request was raised by the session the command runs in (PASEO_AGENT_ID). An agent never answers its own tool use.not_found: nothing by that id waits on you, usually because it was answered already.
Inside an agent both commands are refused: the cyborg7 MCP has no approval tool.
A workspace’s event log
cyborg state:log <workspace> [on|off] [--retention-days <n>]
cyborg state:events <workspace> [--after <ordinal>] [--limit <n>] [--all --out <file.jsonl>]
The event log is an ordered list of what changed in a workspace: tasks (created, updated, assigned, deleted), task comments, pages (created, updated, archived, restored, deleted) and members (joined, left, role changed). Each event holds ids only, never a title or a text. It is off by default. state:log with no state says whether it is on; on and off are for workspace admins, and every switch is itself an event. Events are kept 90 days unless --retention-days says otherwise.
state:events reads the log in order, at most 500 events per page, showing only the events you may see now (the rules a webhook subscriber is held to: project rooms, private pages, DM tasks); the summary counts the rest as hidden. --after takes the next of a previous read, so a reader resumes without loss or repeat. --all reads to the end and needs --out.
Exporting a thread
cyborg export:thread <chain-id> --workspace <id> --out <dir> [--anonymize] [--config <file.json>] [--key-file <file>] [--github [--repo <owner/repo>]]
export:thread rebuilds one thread: the chain of agent turns a request started, across sessions and machines. It reads the chain’s turns from the relay’s turn ledger and each session’s rows through the same read as agent:export, then writes thread.jsonl (every turn end and every row, in time order, each row with the origin of who produced it: a person, another agent, the model, a tool, a Cyborg tool or an integration) and trajectories/<session>.atif.json, one ATIF v1.8 trajectory per session. The agent team a turn of the chain started (the turns its messages reached, at any depth) is part of the thread: each such turn end carries teamOf, the chain turn that started it. A session in the chain that you did not start is counted in the summary and not read. --anonymize runs the same anonymizer as export:anonymize before anything is written. --config takes the same file; its topics, sensitiveLabels and sensitiveBranches (words matched whole in a PR label or a branch name) decide whether the thread is flagged sensitive, and with none of them nothing is. --github adds the pull requests the sessions opened or touched (found in their rows: PR links and gh pr … commands, --repo for a bare number): the PR, its comments, reviews, commits and merge, read with your own gh login and placed in the timeline by time.
Anonymizing an export
cyborg export:anonymize <workspace> --in <export.jsonl> --out <anon.jsonl> [--config <file.json>] [--report <file.json>] [--key-file <file>]
cyborg export:task <thread-dir> --out <task-dir> [--turn <turn_uid>] [--id <name>]
cyborg export:check-task <task-dir>
cyborg export:workspace <workspace> --machine <id> --out <dir> [--config <file.json>] [--key-file <file>]
cyborg export:channels <workspace> --out <dir> [--config <file.json>] [--key-file <file>] [--at-seq <n>] [--resume]
cyborg export:snapshot <workspace> --out <dir> [--config <file.json>] [--key-file <file>]
cyborg export:check-snapshot <dir>
export:anonymize reads a file written by agent:export and replaces the workspace’s own people and agents with stable pseudonyms (Person A, Agent 01), sessions and machines with session_… and machine-N, and ids, e-mails, secrets, links, addresses, cloud accounts and time zones with placeholders. It always cuts the lines of a git branch listing. Any other topic is the workspace’s own choice: topics in --config lists them, each an id and its phrases (literal text, matched as a whole word in any case), and a line holding one is cut. With no topics, nothing else is cut. A person is matched by their profile name, its first word and the nicknames in aliases, keyed by the member’s e-mail or user id ({"aliases": {"ana@corp.test": ["Anita"]}}); no name is guessed from an e-mail address. A name is also replaced inside a slug, a host name or a handle (ana-dev, Anas-MacBook.local). --config also adds names never to replace (neverReplace, e.g. an agent named after a product), places and phrases. Example: {"topics": [{"id": "investors", "phrases": ["term sheet", "valuation"]}]}. With "namePass": true (off by default), a second pass also looks for names of people who are not members (a customer, a contact) in what people and agents wrote, never in tool output, and replaces each with a stable Name_…; it runs on your machine and needs no network. --report writes, per session, how many lines and rows were cut and on which topic. The same --key-file gives the same pseudonyms across runs.
export:task turns one person’s request in a folder export:thread wrote into a draft task in the τ²-bench shape: task.json (the request, the clock, and as expected actions the cyborg7_* calls the agent made in that turn), instruction.md, and environment/prior-conversation.jsonl, every row of the thread before the request, so a request that answers an earlier turn stays solvable. The expected actions are what the agent did, not what was right: a person reviews them and adds state and reply checks. export:check-task says why a task cannot be trusted yet: a do-nothing agent would pass it (no expected action and no reply check), or only an unchanged state is checked.
export:workspace exports every session on one machine that you may read, the way agent:export --on-machine does, but the machine also tags each row with who produced it, replaces the workspace’s people and agents with pseudonyms and cuts the workspace’s red-line topics before it uploads anything. --config takes the same file as export:anonymize (its phrases are matched as literal text). One computer may export up to 1,000 sessions or 20 GB in an hour, and each upload must be exactly the size the computer declared. --out gets links.jsonl (one download link per session), cut-report.json (per session, counts only) and, unless you pass --key-file, the new pseudonym-key.txt.
cyborg export:channels <workspace> --out <dir> [--config <file.json>] [--key-file <file>] [--at-seq <n>] writes every channel and DM message you may read as messages.jsonl, oldest first per conversation: who sent it, the text, the thread it answers, its workspace sequence number and, for attachments, only name, type and size (never a link). It reads through the same rules the app does (a private channel only if you are in it, a DM only if it is yours) and runs the anonymizer with the same --config as export:anonymize before anything is written. --at-seq keeps only messages up to that workspace sequence number, the cut a snapshot records. Deleted messages are not exported. It writes one conversation at a time and records it in progress.json; after an interruption, the same command with --resume finishes the export with the saved pseudonym key and repeats nothing. --out also gets cut-report.json and, unless you pass --key-file, pseudonym-key.txt.
cyborg export:snapshot <workspace> --out <dir> [--config <file.json>] [--key-file <file>] is for workspace admins: everything the workspace holds at one point (members, agents, channels and their members, projects, tasks with their activity, pages, standing orders, schedules with their change history, connected integrations, workspace-wide memory notes, and the metadata of agent turns in sessions you started: no content, only who, when, outcome, tokens and cost), read by the relay in one consistent transaction. What you could not see in the app is left out and counted in hidden: private channels you are not in, tasks from other people’s DMs, private pages that are not yours, schedules set up in someone else’s DM, and who owns another person’s integration. An agent’s instructions are written as a fingerprint, not their text. The files are downloaded once through links that last an hour and are deleted from the bucket within a day; the anonymizer runs on your machine with the same --config as export:anonymize before anything is written. --out gets one <entity>.jsonl each, manifest.json (the cut: the event log position cut.stateOrdinal and the last message cut.messageSeq), cut-report.json and, unless you pass --key-file, pseudonym-key.txt. Messages are not in the snapshot: run export:channels --at-seq <cut.messageSeq> --key-file <the same key> for them. Of agents’ memory, only notes the whole workspace may read are exported (workspace-wide, normal sensitivity, current and not purged), with the body of their current version; the rest is counted in hidden. --out also gets schemas.json, the JSON Schema of each entity file’s rows. export:check-snapshot <dir> checks that such a folder is complete and loadable: the manifest’s shape, every entity file present, its row count as the manifest says and every row valid against its entity’s schema; it lists the problems and exits 1.
Logs
cyborg logs:export <workspace> --out <file.jsonl> [--since 7d|<date>] [--severity info|warn|error] [--cybo <id>] [--machine <id>] [--tab <tab>]
logs:export writes the workspace Logs rows you may read, one JSON line per row, through the same read as Logs → Export in the app: a member gets only their own rows, an owner or admin the workspace’s. It reads every page (the app’s Export stops at 200 rows per request) and never past the retention window it prints.
Grading and calibration
cyborg grade:thread <dir> [--logs <logs.jsonl>] [--grader <name...>]
cyborg calibration:show <workspace> [--since 30d|<date>]
grade:thread answers yes/no graders on a folder written by export:thread, from the product’s own records and without a model: every_turn_completed, no_turn_stopped, no_failed_tool_call, pull_request_merged and last_review_approved (with --github), no_permission_refusal and approval_before_action (with --logs from logs:export). Each answer carries the counts it read.
calibration:show (owners and admins) shows, for the window, how the workspace’s turns end by kind of turn (completed, failed, stopped) and how approvals are answered: how many, how many approved, and the median and 90th-percentile delay between the approval card and the decision. Counts only, never content.
Threads
cyborg threads:catalog <workspace> [--since 7d|<date>] [--out cards.jsonl]
cyborg threads:suggest-skills --in <export.jsonl> [--min <n>] [--out <dir>]
threads:catalog reads one card per thread (a chain of agent turns) from the relay’s turn ledger and prints a summary by shape: handoff_relay (agents handing work to each other), channel_swarm (agents answering in a channel), ask_reply, automation_fanout (schedules and tasks), person_dialogue (a person and one agent) and mixed, with how many have several agents, a person or two machines. A card holds counts only (turns, sessions, machines, depth, minutes, person turns, failures, cost), never text. Only the sessions you started are counted; the rest are reported as a number. The window is at most 31 days.
threads:suggest-skills reads a file agent:export wrote and finds what people keep asking: requests whose words mostly overlap, at least --min times (default 5). Each group is listed with its most typical request; --out writes it as a skill draft to edit and save with skill:create. Requests group across the export’s sessions (one agent runs many); --per-session keeps sessions apart. Nothing is read from the workspace or saved.
Machines
cyborg machine:list <workspace-id> # online, version, your access, run agents / terminal, recovery
cyborg provider:list <workspace-id> --daemon <machine-id> # what that machine can run
cyborg machine:rename <workspace-id> <machine-id> "Studio Mac"
cyborg machine:lend <workspace-id> <machine-id> on # your personal machine: agents working for others in that workspace may use its spare room
cyborg machine:keep-awake <workspace-id> --daemon <machine-id> on # or auto (while an agent works), off, default (on for a workspace machine); owner, or admin on a workspace machine
cyborg machine:auto-update <workspace-id> [on|off] # read, or (owner or admin) set: workspace machines install updates by themselves, within 2 hours
cyborg machine:restart <workspace-id> <machine-id> # owner or admin: it comes back on its own
cyborg machine:room <workspace-id> <machine-id> # memory history, top memory users, local models (what you may see)
cyborg machine:cleanup [--json] # this computer only: what self-cleaning would stop and why each process stays (dry run)
cyborg machine:leftovers [--json] # owner only, this computer: what self-cleaning left for you to decide (crash rows, trash, released TMPDIRs)
cyborg machine:leftovers:approve <id> # owner only: one item, checked again, then stopped, moved to trash or purged from trash
cyborg machine:models <workspace-id> # local models (Ollama, LM Studio, llama.cpp, vLLM, SGLang) on the machines you may see
cyborg machine:model <workspace-id> <machine-id> <model-id> load # or unload; Ollama only; owner or admin
cyborg machine:local-servers <workspace-id> <machine-id> # its model servers: kind, port, status, key set, detected or added, models
cyborg machine:local-server-add <workspace-id> <machine-id> http://127.0.0.1:8001 [--name "Spark thinker"] [--key-file '~/llm/.api_key'] # owner or admin; tested first
cyborg machine:local-server-remove <workspace-id> <machine-id> <server-id> --yes # owner or admin; added servers only
cyborg machine:ask-owner <workspace-id> <machine-id> # ask the owner to fix it (once an hour)
cyborg machine:request-cancel <workspace-id> <request-id> # withdraw your own pending access request
cyborg subscription:list <workspace-id> # subscriptions on the machines you may see, as Home shows them
cyborg subscription:history <workspace-id> <subscription-id> # one subscription's weekly usage history
cyborg machine:grant <workspace-id> <machine-id> <user-id> --scopes chat,spawn # full access: --scopes admin
cyborg machine:revoke <workspace-id> <machine-id> <user-id> --yes
cyborg machine:remove <workspace-id> <machine-id> --yes # admins: take a machine out of the workspace
cyborg machine:restore <workspace-id> <machine-id> # admins: put a removed machine back
cyborg machine:requests <workspace-id> # pending access requests you can see
cyborg machine:request <workspace-id> <machine-id> --scopes chat
cyborg machine:approve <workspace-id> <request-id> [--scopes chat]
cyborg machine:deny <workspace-id> <request-id>
cyborg machine:invite-worker <workspace-id> [--label <label>] [--role viewer|operator|restricted] # admins: a setup code
cyborg machine:workers <workspace-id> # workspace machines: online state, default role
cyborg provider:refresh <workspace-id> [provider...] --daemon <machine-id>
cyborg provider:install <workspace-id> opencode --daemon <machine-id> # claude, codex, copilot, opencode, pi
cyborg provider:update <workspace-id> codex --daemon <machine-id> [--force] # with the tool that installed it
cyborg provider:sign-in <workspace-id> claude --daemon <machine-id> # prints the link, waits
cyborg provider:acp-catalog # ACP agents: id, version, what to install
cyborg provider:add-acp <workspace-id> grok --daemon <machine-id> # turn one on for that machine
cyborg provider:usage <workspace-id> [--daemon <machine-id>] [--org] # accounts, windows, resets, month spend
cyborg provider:usage <workspace-id> --refresh --all # read every online computer again
cyborg provider:usage-hook <workspace-id> --daemon <machine-id> --on # terminal readings on (--off: off)
cyborg provider:switch <workspace-id> --daemon <machine-id> --account <name> [--yes] # switch with claude-swap (Codex accounts are switched on the computer); the computer's owner, or an admin on a workspace computer
cyborg provider:accounts <workspace-id> --daemon <machine-id> [--provider claude|codex] # the accounts each provider's switcher keeps there, and its version
cyborg provider:account-install <workspace-id> --daemon <machine-id> --provider claude|codex # install the switcher (claude-swap / codex-auth), latest release
cyborg provider:account-update <workspace-id> --daemon <machine-id> --provider claude|codex # update it to the latest release
cyborg provider:account-add <workspace-id> --daemon <machine-id> --provider claude|codex # save the account that provider is signed in to there
cyborg provider:account-switch <workspace-id> --daemon <machine-id> --provider claude|codex --account <email> [--yes]
cyborg provider:account-remove <workspace-id> --daemon <machine-id> --provider claude|codex --account <email> --yes # never the active one
cyborg provider:account-auto-switch <workspace-id> on --daemon <machine-id> # Claude: switch to the account with the most left when one runs low (off: stop)
cyborg provider:org-key <workspace-id> anthropic --stdin < admin-key.txt # connect the organization admin key
cyborg provider:org-key <workspace-id> openai --remove # remove it
machine:models lists the models on every kind of local model server Cyborg finds; machine:model load|unload applies to Ollama only, and on any other server it prints the machine’s answer (vLLM keeps its models loaded while it runs; there's nothing to load or unload.) and exits non-zero. machine:local-servers needs full access to the machine and lists each server with its status (running, starting, needs-key, key-rejected, key-unreadable, down), whether a key file is set, and whether it was detected or added; a row from an offline machine says (stale). It never shows an address, a key or a key-file path. machine:local-server-add sends the address and the key-file path to the machine, which checks the address (its own computer only, unless allowLan is set there), reads the key file on its own disk and tests the server before it saves anything; the answer is the server’s id, name, status and model count. When the test fails nothing is saved and the command exits non-zero with the status it found (down, not-model-server, key-rejected or key-unreadable); a server that asks for a key, added without --key-file, is saved with the status needs-key; a refusal before the test (a bad or duplicate address, too many servers) prints the machine’s own sentence. machine:local-server-remove removes only servers someone added; for a detected one the machine answers Only servers someone added can be removed. The key file path is read on that machine, so ~ is that machine’s home; quote it (--key-file '~/llm/.api_key') so your own shell leaves ~ alone instead of replacing it with your home directory. See Run agents on local models.
machine:grant refuses without --scopes: an omitted flag never becomes full access. provider:install installs a key other than claude/codex only on a machine whose daemon offers it (PROVIDER_NOT_INSTALLABLE otherwise). provider:sign-in supports --no-wait, --operation <id> --code <code> (paste the code the provider’s page shows), --operation <id> --cancel, and --verify (exits 1 when the machine is not signed in); Ctrl-C cancels the sign-in on the machine. provider:update updates a provider’s installed CLI on that machine with the tool that installed it; while sessions of that provider run it refuses unless you pass --force. provider:check compares a copy with the version its own installer would install: npm, pnpm, bun and Cyborg-managed copies with the npm registry (or the pinned version), a native Claude with Anthropic’s own release channel (autoUpdatesChannel from its managed or own settings, latest by default), and a Homebrew copy with brew info. When that source can’t be read, the newer version is unknown and nothing is offered. While provider:sign-in waits, the link and code go to stderr in every output mode, so --json keeps stdout to the one result; --no-wait --json returns them (with the operation id) on stdout instead.
provider:usage lists, for each provider account on the computers you own or have full access to, its plan, whether it is the active one, the 5-hour and weekly usage, when they reset, this month’s spend, where the reading came from and how fresh it is. A computer that is off prints Offline · data from <time>. --refresh needs --daemon <machine-id> or --all: it asks each online computer to read its usage files again and prints one line per computer as it answers (updated, updated (cooldown), no_answer, offline), then the table. --org adds the whole-organization rows, for workspace owners and admins. provider:usage-hook turns terminal readings on or off for one computer (it needs full access to it). provider:org-key connects or removes the optional organization admin key for Anthropic or OpenAI: the key is read from stdin only (never from an argument), checked with the provider before it is stored, and never shown again; it needs a workspace owner or admin. Inside an agent these three are refused.
provider:account-auto-switch turns automatic switching on or off for the Claude accounts saved on one computer; it needs the computer’s owner or an admin on it. While it is on, the computer moves to the saved account with the most left once the active one reaches 90% used (the computer sets that threshold), and running turns finish first. It prints the new state, and provider:accounts shows it in its AUTO SWITCH column with the last automatic switch, if any (off from a computer whose daemon does not support it yet). Inside an agent it is refused.
provider:acp-catalog lists the ACP agents this CLI knows (Grok Build, Cursor, Goose, …) with each one’s catalog version, the binary that must be on the machine’s PATH (or “fetched on first run” for an npx/uvx entry) and where to install it; it reads the CLI’s own copy of the catalog and sends nothing. provider:add-acp turns an entry on for one machine with the same request as Settings → Providers → Add: only the catalog id is sent, and the machine runs the command from its own copy of the catalog, so an id that machine does not know is refused (INVALID_REQUEST). The agent then shows up in provider:list. When it is not ready there yet (available: false: its binary is missing, or it is not signed in), the result says so with a hint, and provider:list shows the reason. Grok Build signs in on first use with a Grok account (or XAI_API_KEY on a machine without a browser).
Schedules
cyborg schedule:list <workspace-id> [--cybo <agent-id>]
cyborg schedule:runs <workspace-id> <schedule-id> [--limit 20]
cyborg schedule:create <workspace-id> <agent> --cron "0 9 * * 1-5" --prompt "Summarize yesterday" [--destination dm|channel] [--channel <id>] [--tz America/La_Paz] [--continue-session <session-id>]
cyborg schedule:update <workspace-id> <schedule-id> --cron "0 8 * * *" [--destination dm|channel] [--channel <id>|none] [--continue-session <session-id|none>]
cyborg schedule:pause <workspace-id> <schedule-id> # schedule:resume to undo
cyborg schedule:run <workspace-id> <schedule-id> --execute # once, now
cyborg schedule:delete <workspace-id> <schedule-id> --yes
A schedule the machine refuses (a bad cron, one you cannot see) exits 1 with SCHEDULE_REFUSED. schedule:run shows its plan first (--execute runs it from a script). A schedule runs now at most once a minute, whether you or its agent asks; a second run inside that minute is refused. Inside an agent schedule:run runs only the agent’s own schedules (see Schedules and skill writes inside an agent).
A --channel the agent is not in gets the agent added, if you may add agents to that channel (the same rule as adding it in the app); otherwise the create is refused and nothing is scheduled.
A machine that takes a request and does not answer fails with an error naming the machine and the request, never a hang.
Persistent agents
Persistent agents are reusable templates: identity, personality and provider defaults.
cyborg cybo:create <workspace-id> reviewer "Code Reviewer"
cyborg cybo:list <workspace-id>
cyborg cybo:spawn <workspace-id> reviewer --channel <channel-id> --cwd ~/repo
cyborg cybo:spawn <workspace-id> reviewer --daemon <machine-id>
cyborg cybo:update <workspace-id> reviewer --soul-file soul.md --model default
cyborg cybo:update <workspace-id> reviewer --autonomy L4
cyborg cybo:delete <workspace-id> reviewer --yes
cybo:create and cybo:update take --tool-grants <json|@file> for Composio tool grants.
cybo:update --autonomy <L0|L1|L3|L4|L5> sets the agent’s autonomy level, the same setting as its profile. Any other value is refused before anything is sent. L4 and L5 are full autonomy and need a workspace owner or admin; the relay’s refusal is printed and the command exits non-zero. It is refused inside an agent.
cybo:spawn --daemon <machine-id> runs the agent on that machine or refuses: an agent with a home machine runs only there, so naming another machine is refused with the home’s name and id. It never changes the agent’s home. Without --daemon the agent starts on its home machine (an agent without one adopts its creator’s machine).
Chain of command
An agent another agent created reports to that agent (its manager), and it can never do more than its manager chain allows. cybo:access shows its owner, manager, chain and team, its access after the cap, and what the chain holds back. An agent’s create is a proposal the person it asked must approve: cybo:create --from-proposal <id> creates it exactly as proposed, and cybo:decline-proposal answers Not now (only the person it was sent to, once).
cyborg cybo:access <workspace-id> scout
cyborg cybo:create <workspace-id> --from-proposal <proposal-id>
cyborg cybo:decline-proposal <workspace-id> <proposal-id>
Inside an agent these are refused: the access view and the answer to a proposal are a person’s.
Give an agent to someone
Only an agent’s owner can give it away; an admin or someone with access to its machine cannot, and the workspace’s default agent cannot be given. The person you name must be an active member who may own agents and has a computer of their own in the workspace. Nothing changes until they accept, and the request expires after 7 days.
cyborg cybo:transfer <workspace-id> sprite --to toborochi@example.com # or --to <user-id>
cyborg cybo:transfers <workspace-id> # requests you sent or were sent
cyborg cybo:transfer-accept <workspace-id> <request-id> [--daemon <machine-id>]
cyborg cybo:transfer-decline <workspace-id> <request-id>
cyborg cybo:transfer-cancel <workspace-id> <request-id>
The recipient needs a computer in the workspace they can run agents on: one they own, or one whose owner gave them spawn (or admin) access. A member with no computer of their own receives an agent this way too; otherwise the send is refused with recipient_has_no_machine. Only the recipient can accept: there is no owner or admin shortcut, so the recipient runs cybo:transfers to find the request id and then cybo:transfer-accept (or uses Accept on the request in Activity). On accept the agent becomes theirs and runs on --daemon if given, else stays on its current home when they can run it there (nothing moves), else goes to one of their computers that is online. Its soul, permissions, skills and schedules go with it; when it moves, its open chats on the old machine close (history is kept), and memory it already uploaded comes along. Memory the old machine never uploaded comes along once that machine is back online. A refused request exits non-zero with the relay’s code (not_owner, recipient_has_no_machine, transfer_pending, request_expired, machine_not_yours, …). Inside an agent these commands are refused: who owns an agent is a decision a person makes.
Inside an agent: create and delete agents
An agent can create or delete an agent when a person asks it to. Inside the agent, cybo:create and cybo:delete run the agent’s own tools (cyborg7_create_agent, cyborg7_delete_agent), never your login:
cyborg cybo:create <workspace-id> notes "Release Notes" --soul-file soul.md --role "Release Notes"
cyborg cybo:create <workspace-id> notes "Release Notes" --soul "…" --daemon <machine-id> # home machine
cyborg cybo:delete <workspace-id> notes --yes
It works only when all of these hold:
- The agent holds the Spawn other agents permission (
spawn_agents). An agent a person creates has it by default; an agent another agent creates does not. - A person asked on this turn: a DM they typed, a mention, or a thread reply. A schedule, a task, a watcher or another agent’s message cannot ask.
- That person may create agents in the workspace (for a delete: may delete that agent themselves), and may run agents on the agent’s machine.
cybo:creategets--soulor--soul-file; inside an agent there is no default personality.- The command runs in a shell that proves the turn (Claude in bypass-permissions mode, or Pi). On Codex, OpenCode, ACP and other Claude modes the command is refused and names
cyborg7_create_agent/cyborg7_delete_agent: the agent calls that tool directly, with the same rules.
The new agent belongs to the person who asked and opens its first conversation with them. It never gets more than the agent that created it: only permissions that agent holds (default: the standard set), the same autonomy level as the agent that created it (lowered only to what you may set yourself: full autonomy needs an owner or admin), no bypass, MCP servers or tool grants. --bypass-permissions and --tool-grants are refused. --daemon sets the home machine (default: the agent’s own). The new agent’s name and instructions may use the words you typed to the agent in that DM; anything private it read elsewhere (other people’s messages, a relayed message, notes) and any credential are refused (privacy_held). An agent cannot delete itself. cybo:update and cybo:spawn follow the same rule (see Agent management for the person asking).
In your own plain session
A plain session (a Claude, Codex or other session you started yourself, not a named agent) has no agent of its own, so it acts for you. When you type in your own session, in the app, and ask it for an agent, it creates that agent at once under your account, with no card to tap. cybo:create there runs cyborg7_create_agent the same way:
- Only on a turn you typed live in your own session. A schedule, a task, a watcher, a CLI send, a Slack message, another agent or a teammate’s words merged into the turn cannot ask, and neither can a session an agent started.
- Only on a machine you own (your laptop, or a Workspace machine you own). On a machine someone else owns, create the agent in the app instead.
- You must be allowed to create agents in the workspace and to run agents on the new agent’s machine (default: the session’s own machine).
- Not when the turn read someone else’s words or outside content; create it in the app then.
- It gets the standard new-agent permissions, your default autonomy and nothing you could not set yourself. A routine is set up afterwards, by asking the new agent. A plain session deletes no agents.
Tasks
The same task board the app shows, scriptable:
cyborg task:create <workspace-id> "Fix login redirect" \
--description "302 loops on expired session" \
--assignee <user-or-agent-id> --priority high --label bug
cyborg task:list <workspace-id>
cyborg task:update <workspace-id> <task-id> --state <state-id>
cyborg task:archive <workspace-id> <task-id> # --unarchive to restore
cyborg task:bulk-update <workspace-id> <id1> <id2> --priority low
cyborg task:bulk-update <workspace-id> <id1> <id2> --archived --execute # archiving shows its plan first
cyborg task:comment <task-id> "shipped in #2573" # lands in the task's Activity feed
cyborg task:delete <workspace-id> <task-id> --yes
cyborg task:get <workspace-id> <task-id>
cyborg task:search <workspace-id> "login redirect" [--limit 20] # title, description or project key (e.g. CYBORG-202)
cyborg task:activity <task-id> # changes and comments
cyborg task:links <task-id>
cyborg task:attachments <task-id>
cyborg task:states <project-id> # workflow states, the ids for --state
cyborg project:list <workspace-id>
cyborg project:create <workspace-id> "Mobile app" [--color "#a78bfa"]
cyborg project:update <workspace-id> <project-id> [--name <name>] [--color <hex>]
Saved views: task:views <project-id> lists them, task:view-create <project-id> <name> saves one, task:view-update <view-id> changes one and task:view-delete <view-id> --yes removes it. The view commands take --layout (list, board, calendar, spreadsheet, gantt), --group-by, --sub-group-by, --order-by, --order-dir, --filters <json> and --display <json>.
task:create also supports --due <iso>, --start <iso>, --parent <task-id> (subtasks), --channel, --project, --cycle, and repeatable --label / --module.
Cycles and modules
A project’s cycles (time boxes) and modules (feature groupings), the ones the Tasks sidebar lists:
cyborg cycle:list <project-id> [--archived]
cyborg cycle:create <project-id> "Cycle 44" --start 2026-10-27 --end 2026-11-09 [--description <text>]
cyborg cycle:update <cycle-id> [--name <n>] [--start <day|none>] [--end <day|none>] [--archive | --unarchive]
cyborg cycle:transfer <project-id> <from-cycle-id> <to-cycle-id> # moves the unfinished work items
cyborg module:list <project-id> [--archived]
cyborg module:create <project-id> "Desktop updater" [--status in_progress] [--lead <member-id>] [--start <day>] [--target <day>]
cyborg module:update <module-id> [--name <n>] [--status <s>] [--lead <id|none>] [--start <day|none>] [--target <day|none>]
cyborg module:archive <module-id> [--undo]
A day is YYYY-MM-DD (that calendar day everywhere) or an ISO time; none clears it. Module statuses are planned, in_progress, paused, completed and cancelled. cycle:transfer leaves completed and cancelled items in the cycle they were done in; if some moves fail it says which items stayed and exits 1. A cycle or module name can’t be blank, and a module lead must be a member or an agent of the workspace; the relay refuses anything else. cycle:update --archive/--unarchive and module:archive check the row they get back and exit 4 (NOT_SUPPORTED) when the server didn’t apply the change, as a local daemon doesn’t. Inside an agent these commands are refused: an agent puts work items into a cycle or module with cyborg7_update_task.
Pages
Pages are the project docs you see in the app. A project is identified by its id (from project:list).
cyborg page:list <project-id> # alias: pages; shown as a tree
cyborg page:get <page-id> [--raw] # body as markdown (--raw: as stored)
cyborg page:create <project-id> "Runbook" --file runbook.md [--parent <page-id>] [--visibility private|public] [--icon 📘]
cyborg page:update <page-id> [--title <t>] [--file <path>] [--visibility private|public] [--icon <emoji|none>]
cyborg page:move <page-id> --parent <page-id|root> [--sort-order <n>]
cyborg page:delete <page-id> --yes
cyborg page:search <workspace-id> "runbook" [--limit 20] # page titles across a workspace
cyborg page:access <page-id> # who can read a private page, and who asked to
--file - reads the body from stdin. New pages are private unless you pass --visibility public.
Inside an agent, --visibility (and the tools’ visibility) works only for an agent of the page’s owner: their agents, their own sessions and the tokens they minted, applied at once; any other agent is refused. On a turn someone other than the page’s owner asked (a mention or a channel ask), even the owner’s agent is refused; a scheduled or background run with no other asker applies it. A write naming a turn the relay cannot confirm (lost in a relay restart, expired, or another machine’s) is refused like another person’s ask; a scheduled or task run of the owner’s own schedule or task is re-checked against it and still applies. Known limit: a detached process the agent starts at someone’s ask (a background shell job that outlives the turn) carries no turn, so it publishes as the owner. Private material of other people that the agent read still waits for the Allow of the person it belongs to. A page an agent creates, through the CLI, the MCP tools or an agent token, belongs to the person the agent acts for. When an agent’s page body @mentions someone who can read the page, that person is notified, with the agent named as the author; the person the agent acts for is not notified.
cyborg page:versions <page-id> [--before <version>] [--limit <n>] lists a page’s saved versions, newest first, at most 50 at a time; --before pages back. A version is written on every save that changes the title or the body; one person’s saves within 2 minutes count as one version. A page keeps its first version and its latest 499, and its versions go when the page is deleted. Only someone who may read the page sees its versions; to anyone else the page is not found.
Skills
Skills contain SKILL.md instructions and optional scripts or resources. <slug> accepts a slug or id. Owners and admins may write; an agent reads only its assigned skills in projects it may see.
cyborg skill:list <workspace-id> [--project <project-id>] [--label <label>] # alias: skills
cyborg skill:get <workspace-id> <slug> # prints SKILL.md
cyborg skill:create <workspace-id> <slug> --dir ./my-skill --label docs --label ops
cyborg skill:create <workspace-id> <slug> --file SKILL.md [--name <n>] [--description <d>]
cyborg skill:update <workspace-id> <slug> --dir ./my-skill [--label <label> ...]
cyborg skill:update <workspace-id> <slug> [--file SKILL.md] [--name <n>] [--description <d>] [--clear-labels]
cyborg skill:files:list <workspace-id> <slug> # paths, sizes, modes, SHA256
cyborg skill:files:put <workspace-id> <slug> scripts/run.sh ./run.sh # --file ./run.sh also works
cyborg skill:files:rm <workspace-id> <slug> scripts/obsolete.sh --execute # plan first without --execute
cyborg skill:sync <workspace-id> ./skills [--dry-run] [--label <label> ... | --clear-labels]
cyborg skill:import <workspace-id> --url <url> # --dry-run previews
cyborg skill:import <workspace-id> --github owner/repo --ref main --path skills/my-skill
cyborg skill:assign <workspace-id> <slug> <agent>
cyborg skill:unassign <workspace-id> <slug> <agent>
cyborg skill:delete <workspace-id> <slug> --yes
cyborg skill:search <workspace-id> "code review"
Create, update and sync also accept --scope workspace|project and --project <project-id>; import accepts the same scope options. --file and --dir are mutually exclusive. A directory contains SKILL.md at its root. Binary resources retain their bytes; any local executable bit becomes mode 0755, otherwise 0644. Browser uploads use 0644 because the browser does not supply executable bits.
skill:update --dir patches the files present in the directory and keeps other stored files. skill:files:put replaces just the named file and retains its local executable bit; skill:files:rm removes just that path. Neither operation rewrites labels or sibling files. The instructions remain separate: change SKILL.md with skill:update.
skill:sync accepts either one skill folder or a parent of skill folders. It compares metadata, instructions, decoded file SHA256 hashes and modes, and labels when supplied. A file-only change is update; identical bytes and mode are unchanged. A sync supplies the complete local file set, so remote-only files are removed, including all files when the local folder has none. --dry-run shows the plan without writes. The CLI chunks writes into batches of at most 200 skills and 1.5 MiB of encoded request data; a single oversized bundle is refused before sending.
Repeated --label replaces the label set on create/update/sync. Omission preserves existing labels; --clear-labels explicitly clears them and cannot be combined with --label. Labels are trimmed, lowercased, deduplicated and sorted: at most 20, each 1–40 characters, without commas or control characters. skill:list --label matches an exact normalized label; an empty filter means all visible skills, and an unknown label returns none. The Skills pane offers the same labels, chips and filter.
The relay owns the limits in skill-files.ts; UI rules have parity tests.
| Limit | Value |
|---|---|
| Bundled files per skill | 64 |
| One decoded file | 512 KiB |
| Total decoded bundled bytes per skill | 1 MiB |
| File path | 255 characters; at most 8 segments |
SKILL.md content | 200,000 characters |
| Skills per workspace | 500 |
| Bundled bytes per workspace | 64 MiB |
| Upserts / imports / sync batches per user | 120 / 10 / 10 per minute; separate buckets |
Folder upload/import skips hidden segments and __MACOSX; the import preview reports the skipped count. Direct writes refuse them. CLI/UI uploads refuse ZIP files: extract the archive first. Paths must be relative POSIX paths without traversal, backslashes, NUL, duplicate names, file/directory collisions or a bundled SKILL.md. Local symlinks are refused. Credential filenames (*.pem, *.p12, id_rsa*, credentials*) and high-confidence secret shapes are refused on writes, including UTF-16 content and complete private keys split across bundled files or SKILL.md. A refusal names the offending path and reason, never the matched secret. Documentation containing only a private-key header is allowed.
Quota failures use skill_quota; throttling uses rate_limited. Both leave refused writes uncommitted. An already oversized workspace may edit or shrink if neither its skill count nor its bundled-byte total grows. A sync batch consumes one batch allowance, rather than one upsert allowance per item.
GitHub imports pin their sourceUrl to the resolved commit before reading bytes. Raw/blob URLs with qualified refs/heads/ or refs/tags/ support slash-containing names; an unresolved boundary is refused. Reusing the pinned URL reads the same source; the marketplace re-import preview compares instructions, paths, hashes and modes when that preview feature is installed.
Inside an agent, the CLI uses cyborg7_manage_skill for writes under the attended-person/admin checks. MCP create accepts files; update accepts filesPatch: { put: [...], remove: [...] }; sync accepts complete files sets and compares hashes/modes. Each file uses { path, content, encoding: "utf8" | "base64", mode: "0644" | "0755" }. Omitted MCP labels preserve them; labels: [] clears them. cyborg7_list_my_skills({ label }) filters assigned skills; cyborg7_read_skill({ slug, filesOnly: true }) lists metadata without fetching or writing file bytes. A whole read fetches from the relay; for skills with bundled files, it materializes those files and reports their directory. Scripts run only when the agent invokes them. The daemon expires these directories on every boot, so deleted or unassigned copies do not survive a restart. Without a relay, skills are unavailable; Pi sessions missing MCP support are refused with the reason.
More flags
Flags that are easy to miss, each with the command it belongs to.
| Flag | Command | What it does |
|---|---|---|
--attempt <id> | agent:receipt | Prompt attempt id (promptAttemptId). |
--avatar <emoji-or-url> | cybo:create, cybo:update | Avatar emoji or URL. |
--max-runs <n> | schedule:create | Stop after this many runs (1 = one-shot). |
--catch-up | schedule:create | Run once for a window missed while the machine was off. |
--post-as <cybo> | webhook:create, webhook:update | Agent (id or slug) signed deliveries post as, instead of you (needs a signing secret). |
--no-post-as | webhook:update | Post deliveries as you again, not as an agent. |
--poll-ms <ms> | agent:external:test | How often to check (default 2000). |
--result <text> | task:update | Result text. |
--slug <slug> | skill:import | Save under this slug (default: from the skill’s name). |
--sort <sort> | skill:search | Order: relevance, new, installs (default: relevance). |
--with-prerequisites | provider:install | Also install what the provider needs first (e.g. Node). |
Anything else: cyborg rpc
rpc is an escape hatch that sends any request a signed-in client can send to the relay. Prefer the typed commands above; use rpc for what they do not cover yet.
cyborg rpc cyborg:list_channels '{"workspaceId":"<workspace-id>"}'
cyborg rpc <type> '<payload-json>' --dry-run # validate the payload locally, send nothing
cyborg rpc cyborg:update_channel --payload-stdin --yes < payload.json # payload from stdin, not argv
Every type rpc can send has an operation class, from the relay’s registry (packages/server/src/server/cyborg/rpc-op-class.ts; criteria under Operation classes below):
| Class | What it does | rpc |
|---|---|---|
read | Changes nothing | Sends it as it is |
configure | Writes configuration or data | Needs --yes |
execute | Runs or wakes something (an agent, a terminal, a schedule, a trigger, an install), or posts as you | Refused |
destroy | Deletes, purges or reverts what cannot be brought back | Refused |
credential | Sets, removes, mints or reveals a secret or a sign-in | Refused |
A type with no class yet is refused with RPC_TYPE_UNCLASSIFIED, so a newly added request is never sent before someone classifies it. A refused type answers RPC_TYPE_DENIED and names the typed command that does it with its own checks (for example cyborg rpc cyborg:delete_channel … says to use cyborg ch:delete), or says to use the app when there is no typed command yet. --yes and --dry-run do not change that.
--payload-stdin reads the JSON payload from stdin, so it never shows in ps, shell history or CI logs. --payload-stdin and --token-stdin both read stdin, so they cannot be used together: set CYBORG_TOKEN instead. rpc works through the relay only: it presents the token from --token-stdin (or CYBORG_TOKEN, or the deprecated --token) when you give one, otherwise your saved login (or --profile), and it refuses --email, which only logs in to a local development daemon.
Operation classes
Every relay request has one operation class, declared in one registry. cyborg rpc reads it (above), cyborg rpc … --dry-run prints a type’s class as opClass, and cyborg rpc cyborg:fetch_rpc_classes lists every type with its class from the relay you are signed in to. Nothing on the relay is gated by class yet.
| Class | What the request does |
|---|---|
read | Returns data and stores nothing. Opening or closing your own connection’s subscriptions (a terminal, an agent’s output, a browser view) is a read. |
configure | Stores a change that can be edited back: workspace, channel, agent, schedule, project and skill settings; access grants; your own preferences and markers (read markers, drafts, typing); what you write (tasks, pages, comments, an edit or a reaction); archiving. |
execute | Makes work happen now: starts, prompts, steers, approves, stops or replays an agent, a turn, a schedule or a delivery; drives a terminal, browser or process on a machine; installs or updates software on a machine; spends money (a seat); or sends something outside the workspace (a message that can start an agent’s turn, an email, a task created in an integration). |
destroy | Deletes or reverts something you cannot restore from the app (files, an agent’s or a recipe’s records, a working tree), or takes away or narrows a person’s, agent’s or machine’s membership, role or access, or ownership. |
credential | Creates, reveals, stores, rotates, tests, switches on or off or removes a secret or token, or something that exists to hold one (API keys, sign-ins, MCP keys, an agent’s MCP server headers, webhook signing secrets, invite and machine-join links, push and device registrations), or takes one as input. |
A request that fits several classes takes the strictest: credential, then destroy, execute, configure, read. Three rulings:
- Mirroring your own edit or reaction to a channel’s linked integration (Slack, Teams) is part of making it: the edit stays
configure. A post that can start an agent’s turn isexecute. - Tokens removed only because their owner is deleted (a member, an account, a workspace, an agent) leave the call
destroy. - A lookup that only fetches public data (a company logo, a skill marketplace search) is a
read. An edit that replaces content in place (a page, a memory) isconfigure.
Platform administration (superadmins)
cyborg admin is for Cyborg superadmins only, signed in with cyborg login. Everyone else is refused, and so is any agent.
cyborg admin review-login create <email> [--expires 30d] [--workspace-name "Marketplace Review"]
cyborg admin review-login create <email> --repair # fix the workspace (setup done), keep the code
cyborg admin review-login refresh-guide <email> # rewrite only the "Reviewer guide — start here" page
cyborg admin review-login list
cyborg admin review-login revoke <email>
A review login gives a marketplace reviewer’s account a fixed sign-in code. create makes the account and a seeded workspace with external agents on, if they don’t exist yet, and prints the code once. Running it again rotates the code. list never shows codes. The relay accepts these codes only while CYBORG7_REVIEW_LOGINS is on.
Terminals
The cyborg terminal command group drives real terminals running on any daemon you have access to. You can open one, send keystrokes, and read its output from the CLI without a GUI. Input is gated by ownership: you can only write to terminals you own.
Commands that take a <terminal-id> accept a full ID, a unique ID prefix, or the terminal’s name. Add --host <host> to target a specific daemon.
List terminals
Lists terminals in the current workspace directory. Add --all to list across all workspaces and daemons, or --cwd <path> to scope to a directory.
cyborg terminal ls [--all] [--cwd <path>]
Create a terminal
Opens a new terminal. --cwd sets the working directory (defaults to the current one) and --name gives it a name you can reference later.
cyborg terminal create [--cwd <path>] [--name <name>]
Send keystrokes
Writes input into a terminal. Special tokens like Enter, Tab, Escape, and C-c are interpreted as the matching control sequences; pass --literal to send them verbatim instead.
cyborg terminal send-keys <terminal-id> "<keys>" [Enter] [--literal]
Capture output
Reads the terminal’s current screen. Add --scrollback to read from the beginning of history, --ansi to keep color/escape codes, or --json for machine-readable output.
cyborg terminal capture <terminal-id> [--scrollback] [--history] [--keep-volatile] [--ansi] [--json]
A full-screen program (Claude Code, vim, less, htop) draws on the terminal’s alternate screen, which has no scrollback: a capture shows its current screen and nothing it drew before. Add --history to get everything the daemon still holds as an in-order transcript instead. With --workspace, that is every screen in the daemon’s output ring (the last 256 KiB of the terminal’s output), each line once, so earlier screens of a full-screen program are included. Without --workspace the local daemon keeps no output ring, so --history reads its scrollback, the same as --scrollback.
Follow a terminal
Prints a terminal’s output as it arrives, until you press Ctrl-C, --duration runs out, or the terminal exits. It starts with the current screen, then prints each line the first time it appears, in order, like tail -f. Screens a full-screen program redraws in place are read one by one, so nothing it shows between two of your reads is lost.
cyborg terminal watch <terminal-id> [--history] [--output <file>] [--text | --raw] [--keep-volatile] [--duration <time>] [--json]
| Option | What it does |
|---|---|
--history | Start with everything the daemon still holds (see capture --history) instead of the current screen. |
--output <file> | Append to a file instead of printing. |
--text | Rendered lines, each printed once. This is the default. |
--raw | The terminal’s raw output, escape codes included, as it arrives (with --history, the saved output first). |
--keep-volatile | Also print lines that are only counters, and every tick of a status row (see below). |
--duration <time> | Stop after 30, 30s, 5m or 1h. |
To keep a log of a Claude Code session running in a terminal on another machine:
cyborg terminal watch <terminal-id> --workspace <ws-id> --daemon <machine-id> --history --output session.log
watch uses the same access as capture: only the terminal’s owner can follow it. If the connection drops, watch stops with an error; run it again with --history to catch up.
On a slow connection the relay can drop a piece of live output. watch notices the missing piece, stops printing, subscribes again, and rebuilds from the output the daemon still holds, so nothing is skipped or printed out of order. With --raw it lines up the daemon’s saved output with the bytes already written and writes only what follows them. If that is not possible (the saved output no longer reaches back that far, or the match is ambiguous), it writes a line --- gap: N output frame(s) may be missing --- where the gap is and carries on. The same line marks the gap in text output if the daemon does not answer within a few seconds.
The text output is meant to read like what the session said, so it leaves out what only moves:
- Output is printed once the terminal has been quiet for a moment (at most a second later), so a screen that is still being redrawn is never read half-painted.
- A status row whose only changes are a timer, a token count or a spinner (Claude Code’s
✻ Thinking… (12s · ↓ 1.2k tokens)) is printed once, not on every tick. - A line that is only numbers and units (
42m 3s,1.6k tokens) is skipped. - A long line (40 characters or more) is printed once, even if the program draws it again later, for example when it redraws a view you already scrolled past.
- Blank lines are skipped.
- With
--history, the daemon keeps only the end of the terminal’s output, so the oldest part starts in the middle of a screen. A line in that part is printed only once it has been drawn whole, which can be later than when it first appeared.
--keep-volatile turns these three filters off. A line whose text changes in other ways (a progress bar, a line being typed in) is still printed each time it changes.
Kill a terminal
Closes the terminal and frees its process.
cyborg terminal kill <terminal-id>
Workspace terminals (via the relay)
Pass --workspace <id> to route through the relay instead of the local socket. The command reaches whichever daemon hosts the terminal, from any machine you’re logged in on, with your saved login (no --token needed). A terminal created with --workspace is bound to that workspace and appears in the app’s sidebar for its members, so the CLI and the app share one source of truth. When several daemons are connected, pick one with --daemon <id>.
cyborg terminal create --workspace <ws-id> --name deploy --cwd /srv/app
cyborg terminal ls --workspace <ws-id>
cyborg terminal send-keys deploy --workspace <ws-id> "systemctl status app" Enter
cyborg terminal capture deploy --workspace <ws-id>
cyborg terminal watch deploy --workspace <ws-id> --duration 5m
End-to-end example
Open a terminal, run a command in it, and read the result:
# 1. Create a named terminal and note its id
cyborg terminal create --name demo
# 2. Type a command and press Enter
cyborg terminal send-keys demo "ls -la" Enter
# 3. Read what the terminal printed
cyborg terminal capture demo
# 4. Close it when you're done
cyborg terminal kill demo
Terminals are referenced by name or ID prefix, so the same flow works against a terminal on any daemon you have access to. Add --host (direct) or --workspace (via the relay).
Related pages
- Connecting Agents: connect agents to your workspace
- Work with agents: invoke and customize agents
- API Reference: drive Cyborg over the inbound MCP server
Authored rules start in observe mode; agent-created rules start paused. Only the owner can confirm active/unpaused operation with webhook:rule:state; confirmation applies to future signed deliveries. The agent tool’s rule_state action can pause/observe, never activate/unpause. webhook:rules --json also returns creator and consecutive-failure state. Actual execution requires the relay startup switch documented in knowledge/webhook-wake-execution.md; it defaults off. Liquid uses the event object. Stored-event Retry/Replay remain distinct Activity operations.
Timing your own work
cyborg time:start <piece> [--kind card|pr|thread|schedule|other]
cyborg time:stop <piece> [--rejected]
cyborg time:report [--month YYYY-MM]
For a validation of human time per piece of work: time:start and time:stop record your own minutes on a piece in a local file under the Cyborg home (nothing is sent), several spans per piece add up, and a stopped piece counts as accepted unless --rejected. time:report gives the month’s pieces, accepted pieces, minutes and minutes per accepted piece.