Spatio CLI

The Spatio CLI is a standalone command-line client for your workspace. It sits alongside SpatioMCP (for agents) and the SpatioAPI (for raw HTTP): same workspace, three doorways.

Reach for the CLI when you want to script Spatio from a shell, pipe artifacts in and out, or run one-off commands without writing HTTP by hand.

Install

npm install -g @spatio-labs/cli

Or with pnpm:

pnpm add -g @spatio-labs/cli

The local service that runs your sessions ships inside the package, so there is nothing else to install. Verify:

spatio --version

Authenticate

Sign in with a Personal Access Token (it starts with pat_):

spatio auth login --pat pat_01HZ...

Pin a workspace at the same time:

spatio auth login --pat pat_01HZ... --workspace ws_01HZ...

Your session is saved to ~/.spatio/session.json and shared with Spatio Desktop, so signing in once covers both. Inspect or clear it:

spatio auth status
spatio auth logout

For CI or scripts, put the token in the environment instead of logging in, and pair it with --direct (see Raw API access):

export SPATIO_PAT="pat_01HZ..."

Run an agent

Prompt an agent the same way you would in the desktop app — but from your shell. The turn runs on your machine via the local service, and the reply streams back to stdout.

# One-shot: prompt in, streamed reply out, exits when the turn ends.
spatio -p "summarize my inbox from the last 7 days"

# stdin works too, so it composes with anything.
git log --oneline -20 | spatio -p "draft release notes from these commits"

Pick a vendor with --vendor (defaults to claude-code). Whichever you pick must be installed locally:

spatio -p "review this migration" --vendor codex

For multi-step or long-running work, sessions are addressable objects you can pass between processes:

SID=$(spatio chat new)
spatio chat send "$SID" "review the migration in 0042_user_schema.sql"
spatio chat tail "$SID" --json | jq 'select(.type=="tool_use_start")'
spatio chat close "$SID"

Default output renders the reply as plain text on stdout (so it pipes into anything) and surfaces tool calls + errors on stderr. --json switches to newline-delimited events instead — one ServerMessage per line.

Run any action

Every Spatio platform declares its actions in one place. spatio do <action.id> dispatches against whatever's registered today — adding a new platform on the server makes its verbs available here automatically, no CLI release required.

spatio do tasks.complete --params '{"task_id":"tsk_01HZ..."}'
spatio do notes.create   --params '{"title":"Standup","content":"…"}'
spatio do mail.send      --params-file ./params.json

Discover what's available:

spatio actions list                      # every action, all platforms
spatio actions list --platform tasks     # one platform's actions
spatio actions describe tasks.complete   # full spec for one action

Common commands

Every Spatio platform is a namespace with the same five verbs: list, get, create, update, delete.

# Read
spatio notes list
spatio notes get note_01HZ...
spatio tasks list

# create and update take a JSON body
spatio tasks create --body '{"title":"Follow up","priority":"high"}'
spatio notes update note_01HZ... --body '{"title":"Renamed"}'
spatio tasks delete task_01HZ...

Available namespaces: notes, tasks, sheets, slides, files, contacts, routines, apps, agents, channels, dm, calendar, inbox, workspaces. They mirror the SpatioMCP tools, so an agent flow lifts into a shell script with no translation layer.

The background service

Spatio runs a small local service that powers your sessions. It starts automatically the first time you run any command, and it is shared with Spatio Desktop, so there is never a duplicate. You rarely manage it directly:

spatio status     # running? signed in? which workspace?
spatio start
spatio stop
spatio restart

Workspace selection

If your account belongs to more than one workspace, pin one at login or override per command:

spatio auth login --pat pat_01HZ... --workspace ws_01HZ...
spatio notes list --workspace ws_01HZ...
spatio workspaces list

Raw API access

Call any SpatioAPI route directly:

spatio api get /v1/notes
spatio api post /v1/tasks --body '{"title":"x"}'

By default requests route through the local service, which holds your auth. Add --direct to skip it and call api.spatio.app straight with your PAT. useful in CI where no service is running:

export SPATIO_PAT="pat_01HZ..."
spatio notes list --direct

Output

Output is JSON. Add --json to pretty-print it, then pipe into jq:

spatio notes list
spatio tasks list --json | jq

Live events

Stream your workspace's event feed as newline-delimited JSON:

spatio watch
spatio watch --workspace ws_01HZ...

See also

• SpatioMCP tools: the same primitives, exposed to agents.
• SpatioAPI (REST): the underlying HTTP surface.