The spaces CLI is intentionally minimal. It exposes grouped project, workspace, agent, terminal, and MCP commands for automation and terminal workflows.
Use spaces when automation needs to inspect projects or workspaces, create host-scoped workspaces, launch workspace runtime, report coding-agent lifecycle state, or control Spaces terminal sessions. To expose these actions to an MCP client such as Claude Code, Codex, or opencode, see the Model Context Protocol reference.
spaces --version
spaces project list
spaces workspace list
spaces workspace start
spaces agent signal blockedspaces --versionPrints the installed Spaces CLI version.
spaces project list prints the projects in the active profile, or on a paired device with --device.
spaces project list [--device <name-or-id>]Workspace commands list, create, start, stop, and restart workspaces on the same-machine daemon, or on a paired device with --device so an orchestrator can discover and prepare work before spawning agents there. A remote listing reads the device overview. Stop matches the app's Stop: the workspace's processes and terminal sessions end, and a running Spaces app closes their panes and tracked browser tabs. Stopping with no app running leaves the tracked tabs open, since the app is what tracks them.
spaces workspace list [--project <project-id>] [--device <name-or-id>]
spaces workspace create --project <project-id> --branch <branch> [--base-branch <branch>] [--existing-branch] [--device <name-or-id>]
spaces workspace start [--workspace <workspace-id>]
spaces workspace stop [--workspace <workspace-id>]
spaces workspace restart [--workspace <workspace-id>]
spaces workspace start --device <name-or-id> --workspace <workspace-id>
spaces workspace stop --device <name-or-id> --workspace <workspace-id>
spaces workspace restart --device <name-or-id> --workspace <workspace-id>Terminal commands inspect and drive Spaces-owned terminal sessions on the same-machine daemon. Sessions survive app quit, so commands started here stay discoverable through spaces terminal list.
spaces terminal list [--device <name-or-id>]
spaces terminal create [--workspace <workspace-id>] [--command <cmd>] [--title <title>]
spaces terminal send text <session-id> <text> [--submit] [--device <name-or-id>]
spaces terminal send bytes <session-id> <byte> [<byte>...] [--device <name-or-id>]
spaces terminal tail <session-id> [--lines <count>] [--device <name-or-id>]
spaces terminal show <session-id>
spaces terminal stop <session-id>Tail reconstructs rendered terminal output. For identified coding-agent sessions, it omits an inline suggestion at the cursor while preserving status lines, dialogs, menus, and real input. Ordinary terminal sessions preserve faint text at the cursor.
Coding agents report their lifecycle explicitly for a workspace and terminal session. Inside a Spaces-managed terminal, the command reads the workspace and terminal-session IDs from environment. Spaces uses these events to surface blocked and done states in the app and Alerts. This command records state only; it does not launch or stop an agent.
spaces agent signal init
spaces agent signal working
spaces agent signal blocked
spaces agent signal done
spaces agent signal exitSpaces records agent lifecycle events only for Spaces-managed terminal sessions. Outside one, spaces agent signal exits successfully without reporting an event. Passing --workspace without --session, or the reverse, is an error rather than a silent no-op. Use init to establish the agent row; later events update that row, or establish one when the terminal runtime identifies the session as a coding agent.
Agent labels come from what the agent reports at init, or from the terminal runtime when it identifies known Codex, Claude Code, and opencode foreground commands.
Beyond reporting state, the CLI lets one terminal drive other coding agents. spaces agent list and spaces agent status show tracked agents (add --json for machine output); spaces agent annotate leaves a note. spaces agent spawn starts a supported agent (claude, codex, or opencode) in a new workspace terminal and blocks until Spaces detects it running — no hooks required. Spawn delivers no prompt: once it returns, send the first prompt with spaces terminal send. spaces agent subscribe watches a child and injects a clickable notice block into your terminal when it goes blocked, done, or exits. spaces agent kill ends a child and its terminal; it refuses a session that is not a coding agent. To steer a child, send it keystrokes with spaces terminal send — an agent's status still reflects only what the agent itself reports. Every command except signal accepts --device to target a paired device (remote spawn requires --workspace).
spaces agent list [--workspace <id>] [--json]
spaces agent status [--session <id>] [--json]
spaces agent annotate "waiting on review" [--session <id>]
spaces agent spawn --command claude [--workspace <id>] [--timeout <s>]
spaces agent subscribe <child-session> [--subscriber <id>] [--device <name>]
spaces agent unsubscribe <child-session> [--subscriber <id>] [--device <name>]
spaces agent kill <session>Subscriptions can watch a child on this device or, with --device, on a paired one. Notices are delivered only while the subscriber is idle, so one never lands mid-task, and a subscription that would form a watch cycle is rejected. The same actions are available to an MCP client, but spaces agent signal is deliberately never an MCP tool.
spaces device pair with no source opens a short-lived pairing window on the same-machine daemon and prints a spaces://pair link for connecting an iOS client from the terminal. Add --json for machine-readable output. Pass --link to redeem a link from another device, or --ssh user@host to pair with a remote daemon over SSH. Use --ssh-port for SSH ports other than 22.
On Ubuntu 24.04 devices, the Linux installer exposes the CLI at ~/.local/bin/spaces for terminal use and keeps the managed helper at ~/.spaces/bin/spaces.
spaces device pair [--json]
spaces device pair --ssh user@host [--ssh-port <port>]
spaces device pair --link <spaces-pair-link>
spaces device list
spaces device remove <name-or-id>spaces project list
spaces workspace create --project <project-id> --branch bugfix/login-timeout
cd <workspace-directory>
spaces workspace start
spaces agent signal init
spaces agent signal working
# ... later ...
spaces agent signal blockedThe GUI remains the primary place to configure templates and edit workspace details. The CLI stays focused on explicit profile, workspace, terminal, and agent automation.