Manage sessions from the CLI

The cyborg CLI reaches every session you can open in the app, on any machine in your workspaces: your laptop, a headless server, a teammate’s machine you have access to. It goes through the Cyborg relay, so the machine running the session does not need to be the one you type on.

1. Install the CLI

macOS and Windows: the desktop app ships the CLI. Open Settings → System, find Command-line tool, and use its button to install it. It adds ~/.local/bin/cyborg, which runs the app’s own CLI, so the CLI and the app’s machine are always the same version. If ~/.local/bin is not on your PATH, click Add to PATH.

Linux (headless): the installer bundles its own runtime:

curl -fsSL https://raw.githubusercontent.com/Cyborg7-com/cyborg7-releases/main/cyborg-cli/install.sh | sh

Check it:

cyborg --version

2. Log in once

cyborg login --email you@example.com
cyborg whoami

cyborg login asks for your email and password, so it only works for an account that has a password. An account that signs in with an email code, Google or GitHub has no password the CLI can use, and the desktop app does not hand its session to the CLI. After cyborg login, every workspace command talks to the relay with your saved login. You never pass --host or --token. The local machine is only involved for cyborg daemon … and for a terminal on this machine.

3. Find a session

cyborg session:list                      # your sessions, every workspace and machine
cyborg session:list --workspace <ws-id>  # one workspace
cyborg machine:list <ws-id>              # the machines: online, version, your access

Every command below names a session by its id or a unique prefix of it. The first 8 characters session:list shows are enough. Add --workspace <ws-id> to search one workspace only.

4. Read and follow it

cyborg agent:history f24998d0            # the newest page of the transcript
cyborg agent:history f24998d0 --before '<cursor>'   # older pages (the command prints the cursor)
cyborg agent:state f24998d0              # running or idle, model, mode, context use
cyborg agent:follow f24998d0             # stream the live turn; ends with it
cyborg agent:follow f24998d0 --forever   # keep following until Ctrl-C

5. Prompt it and get the answer

# Stream the reply as it is written:
cyborg agent:prompt <ws-id> f24998d0 "summarize what you changed"

# Print only the final reply, for scripts:
cyborg agent:prompt <ws-id> f24998d0 "list the failing tests" --wait --timeout 300

# The same, as JSON (reply, promptId, promptAttemptId):
cyborg agent:prompt <ws-id> f24998d0 "list the failing tests" --json

If the agent is in the middle of a turn, the CLI tells you so and offers two flags:

Flag	What happens
--steer	Your prompt joins the running turn without cancelling it.
--queue	The CLI waits for the running turn to end, then sends.

The two flags are mutually exclusive.

To hand work from one session to another in a script, wait for the first to finish:

cyborg agent:wait f24998d0 --until idle --timeout 900
cyborg agent:prompt <ws-id> 9b8c2e65 "the first session is done, review its diff" --wait

If you doubt a prompt landed, check it with the promptId that --json printed:

cyborg agent:receipt f24998d0 <prompt-id>

6. Start a session on another machine

cyborg machine:list <ws-id>                               # pick a machine id
cyborg provider:list <ws-id> --daemon <machine-id>        # what it can run, and whether each is ready
cyborg agent:create <ws-id> --daemon <machine-id> --provider claude --cwd ~/repo
cyborg cybo:spawn <ws-id> reviewer --daemon <machine-id>

Without --cwd, a session on another machine starts in that machine’s home directory. Whether you may start one there is decided by the machine’s access settings, exactly as in the app; a refusal comes back as an error, never a hang.

7. Tidy up

cyborg agent:archive f24998d0                       # archive (restorable)
cyborg session:list --archived --workspace <ws-id>  # archived sessions
cyborg agent:restore <ws-id> <session-id>           # resume one

Troubleshooting

Errors name the host that was tried, why it failed, and what to run next:

• “Cannot reach the Cyborg relay at …”: a network problem. cyborg status shows your saved login; cyborg login signs in again.
• “rejected the saved login”: your session expired and could not be refreshed. Run cyborg login.
• “The computer running this (srv_…) is not answering”: the machine that runs the session took the request but did not reply. Check it with cyborg machine:list <ws-id>, and run cyborg daemon doctor on that machine.
• “No credential for …”: you passed --host for a relay you are not logged in to. Your saved login is only ever sent to the relay you logged in to.

See the CLI reference for every command and flag.