Basics
spaces --version
Most commands act on the workspace containing the current directory when run inside one; pass --workspace to target another. Inside a Spaces terminal, commands that would otherwise need --workspace or --session read them from the terminal's environment variables instead. --device runs the command against a paired device instead of this machine. --json is available on agent list, agent status, agent spawn, and device pair (without --ssh or --link) for machine-readable output.
Projects
spaces project list [--device <name-or-id>]
spaces project create (--dir <path> | --git-url <url>) [--device <name-or-id>]
Lists or adds projects on this machine, or on a paired device with --device. Create takes exactly one source, imports any spaces.yaml it finds, and prints the new project with its default workspace, which is created but not started. See Adding a project.
| Flag | Description |
|---|
--dir <path> | A folder: a non-git folder or a Git repository's root. A relative path is resolved against the current directory; with --device, pass an absolute or ~ path. |
--git-url <url> | A Git repository to clone. Spaces clones it into its managed folder and checks out the default branch. |
--device <name-or-id> | Paired device selector. Defaults to this machine. |
Workspaces
spaces workspace list [--project <id>] [--device <name-or-id>]
spaces workspace create --project <id> --branch <branch> [--base-branch <branch>] [--existing-branch] [--device <name-or-id>]
spaces workspace start [--workspace <id>] [--device <name-or-id>]
spaces workspace stop [--workspace <id>] [--device <name-or-id>]
spaces workspace restart [--workspace <id>] [--device <name-or-id>]
Lists, creates, starts, stops, and restarts workspaces on this machine or a paired device. See Start, stop, and restart for what each action does.
| Flag | Description |
|---|
--project <id> | Project filter for list; project id for creation. |
--branch <branch> | Workspace branch for creation. |
--base-branch <branch> | Base branch. Defaults to the project's default branch, then main or master. |
--existing-branch | Uses an existing branch instead of creating one. |
--workspace <id> | Workspace id for start, stop, and restart. Defaults to the workspace containing the current directory; required with --device. |
--device <name-or-id> | Paired device selector. Defaults to this machine. |
Terminals
spaces terminal list [--device <name-or-id>]
spaces terminal create [--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>
A terminal session survives quitting Spaces, so a session started here stays discoverable with spaces terminal list. Tail reconstructs rendered terminal output.
| Flag | Description |
|---|
--device <name-or-id> | Paired device selector for list, send, and tail. Defaults to this machine's local sessions. |
--workspace <id> | Workspace id for terminal create; omit inside a workspace. |
--command <cmd> | Shell command. Defaults to a login shell. |
--title <title> | Session title. Defaults to shell-1, shell-2, and so on, the first not already in use. |
--submit | Sends the text as a paste followed by a separate Enter keystroke, so Claude Code, Codex, and opencode submit the line instead of leaving it unsubmitted. |
<byte> | Decimal byte value from 0 through 255. |
--lines <count> | Number of lines to print. Defaults to 20. |
show <session> | Opens a native Spaces window for the session on macOS. |
stop <session> | Ends the session on this machine the way stopping its runtime target in the app does: its row disappears and its pane closes. A session that has already ended is refused. |
Agents
spaces agent list [--workspace <id>] [--json] [--device <name-or-id>]
spaces agent status [--session <id>] [--json] [--device <name-or-id>]
spaces agent brief write "<markdown>" [--session <id>] [--device <name-or-id>]
spaces agent brief write < brief.md
spaces agent brief read [--session <id>] [--device <name-or-id>]
spaces agent brief clear [--session <id>] [--device <name-or-id>]
spaces agent spawn --command <cmd> [--workspace <id>] [--title <title>] [--timeout <seconds>] [--json] [--device <name-or-id>]
spaces agent kill <session> [--device <name-or-id>]
spaces agent subscribe <child-session> [--subscriber <id>] [--device <name>]
spaces agent unsubscribe <child-session> [--subscriber <id>] [--device <name>]
spaces agent signal <event> [--workspace <id>] [--session <id>] [--agent-session <id>]
spaces agent brief write reads the markdown from the argument or from standard input (put -- before markdown that starts with -); an empty document clears the brief. Every agent command except signal accepts --device to target a paired device. See Orchestrate agents for what each command does, and Briefs for the brief commands specifically.
| Flag | Description |
|---|
--command <cmd> | Command that launches a supported coding agent (claude, codex, opencode, copilot, pi, or amp). |
--workspace <id> | Workspace id for spawn. Defaults to the workspace containing the current directory; required with --device. |
--title <title> | Window or session title for spawn. Defaults to the agent's name. |
--timeout <seconds> | Seconds spawn waits for the agent to be ready for input. Defaults to 90. |
--session <id> | Spaces terminal session id for status, brief, and signal. Defaults to SPACES_TERMINAL_TRACKING_ID. |
--subscriber <id> | The watching terminal's session id, for subscribe and unsubscribe (the child being watched is the positional argument). Defaults to SPACES_TERMINAL_TRACKING_ID. |
--agent-session <id> | The agent's own conversation id, for signal, when its hooks pass one as an argument. Defaults to the id in the hook payload. |
--device <name-or-id> | Paired device selector. Defaults to this machine's local sessions. |
--json | Emits machine-readable output where offered. |
Devices
spaces device list
spaces device pair [--json]
spaces device pair --ssh user@host [--ssh-port <port>]
spaces device pair --link <spaces-pair-link>
spaces device remove <name-or-id>
Lists, pairs, and removes paired devices. See Pairing for how each form of spaces device pair works.
MCP
spaces mcp
Runs the Spaces MCP server over standard input and output, so an MCP client such as Claude Code, Codex, opencode, GitHub Copilot CLI, pi, or Amp can connect. See MCP tools for setup and the tool list.
Service updates
spaces daemon apply-update
Applies a downloaded update to the Spaces service on this machine in place, without ending its sessions. See Updates.
