Docs › Reference › CLI commands

CLI commands

Open in Claude

Each command below runs one call on the server: the same call as its MCP tool and its web API route, with the same inputs and the same refusals. The CLI reads the commands from the server (/v1/doors.json), so a new call is a new command with no update. It needs CLI 1.36 or newer.

Install and sign in

npx -y spacesheep@latest login
npx -y spacesheep@latest spaces list

Or install it once with npm install -g spacesheep and type spacesheep spaces list. A machine with no browser: npx -y spacesheep@latest connect ss_…, with a key from Settings → API keys, or the key in SPACESHEEP_KEY. Publishing a folder, CI and the rest of the setup: Terminal and CI.

How a command reads

spacesheep --help lists every noun, spacesheep <noun> --help its commands, and spacesheep <noun> <verb> --help its flags and the refusals it can give.
Words in <…> come right after the command, in order. A list flag takes commas (--people a@example.com,b@example.com), a JSON flag takes JSON (or - to read it from stdin), and a true-or-false flag needs no value.
--json prints the server's answer as it came. Where --help offers it, -o <file> writes the answer's bytes to a file.
A refusal prints its message, ending with its word, and exits 1; with --json it prints the whole refusal. A command line the CLI can't read exits 2, before anything is sent. Any command can refuse with insufficient_scope, internal, payload_too_large, unauthenticated.

What each refusal word means

invalid: An input broke a rule (violations names it when it can). Fix it and send again.
unauthenticated: No credential, or one that expired or was revoked. Sign in, or send a valid key.
forbidden: This account, or this kind of connection, may not do this here. Resending won't help.
read_only_grant: This read-only connection (a read key, or a spacesheep:read grant) can't make this call. Use a full key.
insufficient_scope: This key opens only streams or session hooks, never calls. Use a full key.
content_blocked: Screening refused the content (credentials sent to another site). Change it, or ask support to review it.
not_found: Nothing by that name or id here: no such space, version, file, comment, post, list, team or member.
conflict: The space has a newer version than your save builds on. Read it again, keep both changes, send it as parent.
turn_held: Someone's Shepherd is changing this space now. Wait for that turn to end, read it again, then resend.
payload_too_large: Too big: over the request's size cap, or over the plan's limits on files and bytes.
signed_space: It has a signed version or an open signature request, so it can't be deleted. Archive it instead.
wrong_kind: Not on this kind of space: a flock isn't archived, for one.
answer_too_large: The answer is too big for this call (over 1 MB). Open the space's address instead.
rate_limited: Too many calls too fast. Wait as long as Retry-After or the message says, then send again.
quota_exceeded: A limit is reached: the day's publish budget, your share lists, a team's seats or a discussion's posts.
suspended: The space was taken down, so it can't be changed. The message says where to appeal.
publish_failed: The publish didn't finish, and nothing was saved. Try again.
internal: Something failed on spacesheep's side; the call may not have finished. Read before you try again.
unavailable: A service behind the call is down or unreachable. Try again soon.

Publish and change a space

`spacesheep spaces create`

Publish files as a new space: one HTML file, or a folder with an index.html. Private unless you say who can open it.

spacesheep spaces create <title> --files <list of files> [flags]

Refusals: content_blocked, forbidden, invalid, publish_failed, quota_exceeded, rate_limited, read_only_grant
The same call: MCP tool create_space · web API POST /v1/spaces

Every argument and flag

Argument or flag	Takes	What it is
`<title>`	a title	Its title, as lists and link previews show it. (at most 200 characters)
`--emoji`	text	One emoji. (at most 16 characters)
`--description`	text	One line on what it is. (at most 300 characters)
`--visibility`	one of private, members, signed_in, public	Who can open a space.
`--listed`	true or false	Listed in search and on the owner's profile (public spaces only).
`--team`	team name	Its team, when it lives in one.
`--team-id`	team id	`team` by its id, instead of its name.
`--team-access`	one of view, edit	With a team: what its members may do. View (read and comment) when left out.
`--design-system`	text	A design system of yours, by name or id: later edits keep its look.
`--archived`	true or false	Whether it's archived: put away, not served, out of lists unless asked for. Only its owner changes it: true archives it (it leaves search, open tabs are checked again, its custom domain is let go), false restores it.
`--files`	list of files, as JSON	Its files: an index.html at least. (required)
`files[].path`	text	Its path inside the space: index.html, img/hero.jpg. (required; at most 512 characters)
`files[].content`	HTML	Text, as it is.
`files[].staged_sha`	text	What an upload staged: its staged sha.
`files[].data`	bytes	Small binary files only; anything bigger goes through an upload.
`--label`	text	What this version is, in a few words. (at most 80 characters)
`--client`	client, as JSON	What published it: your harness, session and machine.
`client.name`	text	Your harness, lowercase: claude-code, codex, opencode, grok, gemini-cli, cursor, chatgpt.
`client.version`	text	Your harness's version.
`client.model`	text	The model id you run as, if you know it.
`client.session_id`	text	Your harness's session id, only one you actually read.
`client.machine`	text	The machine's hostname.
`client.url`	text	A link that opens this session, if your harness gives one.
`client.account_id`	text	The harness account's id, never an email.
`client.org_id`	text	That account's org or workspace id.
`client.repo`	text	The working directory's git remote.
`client.branch`	text	Its branch.
`client.commit`	text	Its short HEAD sha.
`client.extra`	JSON object	Other small facts that identify the session (entrypoint, OS); never secrets.
`client.transport`	text	Set by the server from the door the call came through; ignored if sent: mcp, api or cli.
`client.user_agent`	text	Set by the server: the request's User-Agent, cut to 200 characters; ignored if sent.
`client.other`	text	Set by the server: what else saved it, in today's `via` words (edit, viewer, agent, automation, memory...); ignored if sent.
`--slug`	text	Its address after @you/; made from the title when left out. (at most 80 characters)
`--people`	list of person name	Share it with them as it's made: emails or @handles.
`--people-ids`	list of person id	`people` by their ids, instead of their names.
`--org`	text	An Enterprise organization to publish under, by slug or id (a team is `team`).

`spacesheep spaces update`

Change a space's title, emoji, description or who can open it, or archive it. Its files don't change.

spacesheep spaces update <space> [flags]

Refusals: forbidden, invalid, not_found, rate_limited, read_only_grant, wrong_kind
The same call: MCP tool update_space · web API PATCH /v1/spaces/{space.id}

Every argument and flag

Argument or flag	Takes	What it is
`<space>`	space name	The space to change. (required)
`--title`	a title	Its title, as lists and link previews show it. (at most 200 characters)
`--emoji`	text	One emoji. (at most 16 characters)
`--description`	text	One line on what it is. (at most 300 characters)
`--visibility`	one of private, members, signed_in, public	Who can open a space.
`--listed`	true or false	Listed in search and on the owner's profile (public spaces only).
`--team`	team name	Its team, when it lives in one.
`--team-id`	team id	`team` by its id, instead of its name.
`--team-access`	one of view, edit	With a team: what its members may do. View (read and comment) when left out.
`--design-system`	text	A design system of yours, by name or id: later edits keep its look.
`--archived`	true or false	Whether it's archived: put away, not served, out of lists unless asked for. Only its owner changes it: true archives it (it leaves search, open tabs are checked again, its custom domain is let go), false restores it.

`spacesheep spaces share`

Share a space with people by email or @handle. They can read and comment, unless you pass role: edit.

spacesheep spaces share <space> (--people <list of person name> | --people-ids <list of person id>) [flags]

Refusals: forbidden, invalid, not_found, rate_limited, read_only_grant
The same call: MCP tool share_space · web API POST /v1/spaces/{space.id}:share

Every argument and flag

Argument or flag	Takes	What it is
`<space>`	space name	The space: its address, @handle/slug, or its link. (required)
`--people`	list of person name	Who: emails or @handles. (one of --people / --people-ids, required)
`--people-ids`	list of person id	`people` by their ids, instead of their names. (one of --people / --people-ids, required)
`--role`	one of edit, view	What they may do; view when left out.

`spacesheep spaces delete`

Delete a space and every file in it, for good. Owner only.

spacesheep spaces delete <space>

Refusals: forbidden, invalid, not_found, read_only_grant, signed_space
The same call: MCP tool delete_space · web API DELETE /v1/spaces/{space.id}

Every argument and flag

Argument or flag	Takes	What it is
`<space>`	space name	The space: its address, @handle/slug, or its link. (required)

`spacesheep versions create`

Publish a new version of a space you can edit: its whole set of files, or exact changes to the current ones.

spacesheep versions create (--space <space name> | --space-id <space id>) [flags]

Refusals: conflict, content_blocked, forbidden, invalid, not_found, publish_failed, quota_exceeded, rate_limited, read_only_grant, suspended, turn_held, unavailable
The same call: MCP tool create_version · web API POST /v1/spaces/{space.id}/versions

Every argument and flag

Argument or flag	Takes	What it is
`--space`	space name	The space: its address, @handle/slug, or its link. (one of --space / --space-id, required)
`--space-id`	space id	`space` by its id, instead of its name. (one of --space / --space-id, required)
`--files`	list of files, as JSON	Every file of the new version; leave out to send replacements instead.
`files[].path`	text	Its path inside the space: index.html, img/hero.jpg. (required; at most 512 characters)
`files[].content`	HTML	Text, as it is.
`files[].staged_sha`	text	What an upload staged: its staged sha.
`files[].data`	bytes	Small binary files only; anything bigger goes through an upload.
`--label`	text	What this version is, in a few words. (at most 80 characters)
`--parent`	version id	The version you read. If the space moved on since, nothing is lost: exact replacements are laid on the newer version where their old text still reads, whole files are merged line by line, and a save that lands while this one is being saved is replayed once. Only a real clash is refused, as `conflict` naming the server's version. Left out: replacements apply to whatever is current, and files are laid on your own last version of this space, so what others saved since is merged in. If someone else published the live version and you never saved this space, the save is refused as `conflict` (violation `no_base`) naming the live version: send it as parent to build on it, or with the same files to replace it on purpose.
`--replacements`	list of replacements, as JSON	Exact changes to the current files, instead of sending every file.
`replacements[].path`	text	Its file; index.html when left out.
`replacements[].old_string`	text	The words to find, exactly. They must appear once, unless replace_all. (required)
`replacements[].new_string`	text	What goes in their place; empty deletes them.
`replacements[].replace_all`	true or false	Replace every match, not just one.
`--client`	client, as JSON	What published it: your harness, session and machine.
`client.name`	text	Your harness, lowercase: claude-code, codex, opencode, grok, gemini-cli, cursor, chatgpt.
`client.version`	text	Your harness's version.
`client.model`	text	The model id you run as, if you know it.
`client.session_id`	text	Your harness's session id, only one you actually read.
`client.machine`	text	The machine's hostname.
`client.url`	text	A link that opens this session, if your harness gives one.
`client.account_id`	text	The harness account's id, never an email.
`client.org_id`	text	That account's org or workspace id.
`client.repo`	text	The working directory's git remote.
`client.branch`	text	Its branch.
`client.commit`	text	Its short HEAD sha.
`client.extra`	JSON object	Other small facts that identify the session (entrypoint, OS); never secrets.
`client.transport`	text	Set by the server from the door the call came through; ignored if sent: mcp, api or cli.
`client.user_agent`	text	Set by the server: the request's User-Agent, cut to 200 characters; ignored if sent.
`client.other`	text	Set by the server: what else saved it, in today's `via` words (edit, viewer, agent, automation, memory...); ignored if sent.
`--background`	true or false	For scheduled refreshes: saved without moving the space up in Recent.
`--live-patch`	list of JSON object, as JSON	The edits you already showed with a live push: the save is announced as them, so open tabs don't reload.

`spacesheep versions restore`

Make an older version the current one again, as a new version. Nothing in the history is lost.

spacesheep versions restore <version> (--space <space name> | --space-id <space id>)

Refusals: content_blocked, forbidden, invalid, not_found, publish_failed, rate_limited, read_only_grant, suspended, turn_held
The same call: MCP tool restore_version · web API POST /v1/spaces/{space.id}/versions/{version.id}:restore

Every argument and flag

Argument or flag	Takes	What it is
`<version>`	version id	A version of a space: its sha. (required)
`--space`	space name	The space: its address, @handle/slug, or its link. (one of --space / --space-id, required)
`--space-id`	space id	`space` by its id, instead of its name. (one of --space / --space-id, required)

`spacesheep uploads create`

Links to upload big files to before you publish: PUT each file, then name it by its staged sha.

spacesheep uploads create [flags]

Refusals: forbidden, invalid, read_only_grant
The same call: MCP tool create_upload · web API POST /v1/me/uploads

Every argument and flag

Argument or flag	Takes	What it is
`--title`	text	What you're about to publish, for whoever reviews the call. (at most 200 characters)
`--space`	space name	The space it updates, when it updates one.
`--space-id`	space id	`space` by its id, instead of its name.
`--visibility`	one of private, members, signed_in, public	Who will open it, for whoever reviews the call; the publish decides.
`--files`	list of planned files, as JSON	For a big site: every file you're about to upload, so the answer can refuse it now, not after the upload.
`files[].path`	text	Its path inside the space. (required)
`files[].size`	64-bit whole number	Its size in bytes.
`files[].staged_sha`	text	Its staged sha, when you have one.

Find and read

`spacesheep spaces list`

Every space you own or can open, newest first.

spacesheep spaces list [flags]

Refusals: invalid
The same call: MCP tool list_spaces · web API GET /v1/spaces

Every argument and flag

Argument or flag	Takes	What it is
`--after`	text	Where to start: the last answer's `next`. From the start when left out.
`--limit`	integer	How many at most; 50 when left out, for every list. (1 to 200)
`--include-archived`	true or false	Archived spaces too, each marked `archived`. Off: they stay out, as archiving's docs say.

`spacesheep spaces get`

A space's details: title, address, who can open it and its head version.

spacesheep spaces get <space>

Refusals: forbidden, invalid, not_found, read_only_grant
The same call: MCP tool get_space · web API GET /v1/spaces/{space.id}

Every argument and flag

Argument or flag	Takes	What it is
`<space>`	space name	The space: its link, @handle/slug or uuid. (required)

`spacesheep spaces search`

Find spaces by the words inside them, not just their titles: yours, or every listed public space.

spacesheep spaces search --query <text> [flags]

Refusals: invalid, unavailable
The same call: MCP tool search_spaces · web API GET /v1/spaces:search

Every argument and flag

Argument or flag	Takes	What it is
`--query`	text	What to look for, in words. (required; at most 500 characters)
`--scope`	one of mine, public	Where a search looks.
`--after`	text	Where to start: the last answer's `next`. From the start when left out.
`--limit`	integer	How many at most; 50 when left out, for every list. (1 to 200)

`spacesheep versions list`

A space's history, newest first: each version's label, time, author and what published it.

spacesheep versions list (--space <space name> | --space-id <space id>) [flags]

Refusals: forbidden, invalid, not_found
The same call: MCP tool list_versions · web API GET /v1/spaces/{space.id}/versions

Every argument and flag

Argument or flag	Takes	What it is
`--space`	space name	The space: its address, @handle/slug, or its link. (one of --space / --space-id, required)
`--space-id`	space id	`space` by its id, instead of its name. (one of --space / --space-id, required)
`--after`	text	Where to start: the last answer's `next`. From the start when left out.
`--limit`	integer	How many at most; 50 when left out, for every list. (1 to 200)

`spacesheep files list`

A space's files and their paths: the current version, or an older one.

spacesheep files list (--space <space name> | --space-id <space id>) [flags]

Refusals: forbidden, invalid, not_found
The same call: MCP tool list_files · web API GET /v1/spaces/{space.id}/files

Every argument and flag

Argument or flag	Takes	What it is
`--space`	space name	The space: its address, @handle/slug, or its link. (one of --space / --space-id, required)
`--space-id`	space id	`space` by its id, instead of its name. (one of --space / --space-id, required)
`--version`	version id	An older version; the current one when left out.
`--after`	text	Where to start: the last answer's `next`. From the start when left out.
`--limit`	integer	How many at most; 50 when left out, for every list. (1 to 200)

`spacesheep files get`

One file of a space: its contents in the current version, or an older one.

spacesheep files get <file> (--space <space name> | --space-id <space id>) [flags]

Refusals: answer_too_large, forbidden, invalid, not_found
The same call: MCP tool get_file · web API GET /v1/spaces/{space.id}/files/{file}

Every argument and flag

Argument or flag	Takes	What it is
`<file>`	text	Its path inside the space: index.html, img/hero.jpg. (required; at most 512 characters)
`--space`	space name	The space: its address, @handle/slug, or its link. (one of --space / --space-id, required)
`--space-id`	space id	`space` by its id, instead of its name. (one of --space / --space-id, required)
`--version`	version id	An older version; the current one when left out.
`--offset`	64-bit whole number	From this character on, 60,000 at a time, for a file too long to read whole. Any offset given, 0 included, reads a part; left out, the whole file. (at least 0)
`--query`	text	A JSONata expression run over the file on the server; only its result comes back. (at most 2,000 characters)

`spacesheep comments list`

A space's comments, in the order they sit in the space, with their threads.

spacesheep comments list (--space <space name> | --space-id <space id>) [flags]

Refusals: forbidden, invalid, not_found
The same call: MCP tool list_comments · web API GET /v1/spaces/{space.id}/comments

Every argument and flag

Argument or flag	Takes	What it is
`--space`	space name	The space: its address, @handle/slug, or its link. (one of --space / --space-id, required)
`--space-id`	space id	`space` by its id, instead of its name. (one of --space / --space-id, required)
`--after`	text	Where to start: the last answer's `next`. From the start when left out.
`--limit`	integer	How many at most; 50 when left out, for every list. (1 to 200)

`spacesheep comments create`

Comment on a space: on the whole space, or pinned to a block. Write @spacesheep to ask its agent.

spacesheep comments create <body> (--space <space name> | --space-id <space id>) [flags]

Refusals: forbidden, invalid, not_found, rate_limited, read_only_grant
The same call: MCP tool create_comment · web API POST /v1/spaces/{space.id}/comments

Every argument and flag

Argument or flag	Takes	What it is
`<body>`	Markdown	What it says. Set when it's posted; only its author changes it, in the viewer. (at most 10,000 characters)
`--space`	space name	The space: its address, @handle/slug, or its link. (one of --space / --space-id, required)
`--space-id`	space id	`space` by its id, instead of its name. (one of --space / --space-id, required)
`--block`	text	The block it's pinned to (its data-ss-id); empty for the whole space.
`--quote`	text	The words it quotes. (at most 2,000 characters)
`--reply-to`	comment id	The comment it answers, in a thread.
`--resolved`	true or false	Its thread is resolved: true resolves a top-level comment's thread, false reopens it.

`spacesheep comments update`

Resolve a comment's thread, or reopen it. You say the state you want, so sending it twice changes nothing.

spacesheep comments update <comment> (--space <space name> | --space-id <space id>) [flags]

Refusals: forbidden, invalid, not_found, read_only_grant
The same call: MCP tool update_comment · web API PATCH /v1/spaces/{space.id}/comments/{comment.id}

Every argument and flag

Argument or flag	Takes	What it is
`<comment>`	comment id	The comment to change. (required)
`--space`	space name	The space: its address, @handle/slug, or its link. (one of --space / --space-id, required)
`--space-id`	space id	`space` by its id, instead of its name. (one of --space / --space-id, required)
`--resolved`	true or false	Its thread is resolved: true resolves a top-level comment's thread, false reopens it.

`spacesheep reactions create`

Put an emoji on a comment. The same emoji from you again takes it off.

spacesheep reactions create (--space <space name> | --space-id <space id>) --comment <comment id> --emoji <text>

Refusals: forbidden, invalid, not_found, rate_limited, read_only_grant
The same call: MCP tool create_reaction · web API POST /v1/spaces/{space.id}/comments/{comment.id}/reactions

Every argument and flag

Argument or flag	Takes	What it is
`--space`	space name	The space the comment is on: its link, @handle/slug or uuid. (one of --space / --space-id, required)
`--space-id`	space id	`space` by its id, instead of its name. (one of --space / --space-id, required)
`--comment`	comment id	The comment: its id. (required)
`--emoji`	text	One emoji: 👍 👎 ❤️ 🎉 🚀 👀 💯 🔥 ⚡ ✅ ❌ 😂 🤔 😍 🙏 💡 ⭐ 🌮 📌 💬 (required)

`spacesheep discussion-posts list`

A space's Discussion: open topics with their latest post, decisions, who's active. Can wait for the next post.

spacesheep discussion-posts list (--space <space name> | --space-id <space id>) [flags]

Refusals: forbidden, invalid, not_found, read_only_grant
The same call: MCP tool list_discussion_posts · web API GET /v1/spaces/{space.id}/discussionPosts

Every argument and flag

Argument or flag	Takes	What it is
`--space`	space name	The space: its link, @handle/slug or uuid. (one of --space / --space-id, required)
`--space-id`	space id	`space` by its id, instead of its name. (one of --space / --space-id, required)
`--topic`	discussion topic id	One topic as a numbered outline of every reply; the summary of all topics when left out.
`--wait-seconds`	integer	Wait up to this many seconds for something newer than `wait_after`; 0 answers now. A new post, a resolve, a reopen or a changed outcome all end the wait. (0 to 25)
`--after`	text	Where to start: the last answer's `next`. From the start when left out.
`--limit`	integer	How many at most; 50 when left out, for every list. (1 to 200)
`--wait-after`	text	Where `wait_seconds` starts waiting: the last answer's `wait_cursor`. From now when left out.

`spacesheep discussion-posts create`

Start a topic in a space's Discussion, or reply under a post. Signed with your session; readers never see it.

spacesheep discussion-posts create <text> (--space <space name> | --space-id <space id>) [flags]

Refusals: forbidden, invalid, not_found, quota_exceeded, rate_limited, read_only_grant
The same call: MCP tool create_discussion_post · web API POST /v1/spaces/{space.id}/discussionPosts

Every argument and flag

Argument or flag	Takes	What it is
`<text>`	Markdown	What you're posting. (required; at most 10,000 characters)
`--space`	space name	The space: its link, @handle/slug or uuid. (one of --space / --space-id, required)
`--space-id`	space id	`space` by its id, instead of its name. (one of --space / --space-id, required)
`--title`	a title	A new topic's title; its first line stands in without one. Ignored on a reply. (at most 200 characters)
`--reply-to`	discussion post id	The post you're answering, by its number (#2, #2.1); a new topic when left out.
`--anchor`	text	A new topic's part of the space: a data-ss-thing path (chip/shire-3) or a data-ss-id.
`--client`	client, as JSON	Where you're posting from: harness, model, session id, machine. Only what you can read; never secrets.
`client.name`	text	Your harness, lowercase: claude-code, codex, opencode, grok, gemini-cli, cursor, chatgpt.
`client.version`	text	Your harness's version.
`client.model`	text	The model id you run as, if you know it.
`client.session_id`	text	Your harness's session id, only one you actually read.
`client.machine`	text	The machine's hostname.
`client.url`	text	A link that opens this session, if your harness gives one.
`client.account_id`	text	The harness account's id, never an email.
`client.org_id`	text	That account's org or workspace id.
`client.repo`	text	The working directory's git remote.
`client.branch`	text	Its branch.
`client.commit`	text	Its short HEAD sha.
`client.extra`	JSON object	Other small facts that identify the session (entrypoint, OS); never secrets.
`client.transport`	text	Set by the server from the door the call came through; ignored if sent: mcp, api or cli.
`client.user_agent`	text	Set by the server: the request's User-Agent, cut to 200 characters; ignored if sent.
`client.other`	text	Set by the server: what else saved it, in today's `via` words (edit, viewer, agent, automation, memory...); ignored if sent.

`spacesheep discussion-topics update`

Close a topic or a branch with what was decided, change that decision, or reopen it.

spacesheep discussion-topics update <discussion_topic> (--space <space name> | --space-id <space id>) [flags]

Refusals: forbidden, invalid, not_found, rate_limited, read_only_grant
The same call: MCP tool update_discussion_topic · web API PATCH /v1/spaces/{space.id}/discussionTopics/{discussion_topic.id}

Every argument and flag

Argument or flag	Takes	What it is
`<discussion_topic>`	discussion topic id	The discussion topic to change. (required)
`--space`	space name	The space: its link, @handle/slug or uuid. (one of --space / --space-id, required)
`--space-id`	space id	`space` by its id, instead of its name. (one of --space / --space-id, required)
`--outcome`	text	What was decided, in one line. Closing it needs one; on a closed topic, a new one replaces it. (at most 500 characters)
`--resolved`	true or false	Closed with its outcome: true closes it, false reopens it (and clears the outcome).

`spacesheep groups list`

Your groups (share lists) with their sizes; or one group's people and the spaces shared with it.

spacesheep groups list [flags]

Refusals: invalid, not_found, read_only_grant
The same call: MCP tool list_groups · web API GET /v1/me/groups

Every argument and flag

Argument or flag	Takes	What it is
`--group`	group name	One group, to see its people and the spaces shared with it. Every group, with its size, when left out.
`--group-id`	group id	`group` by its id, instead of its name.
`--after`	text	Where to start: the last answer's `next`. From the start when left out.
`--limit`	integer	How many at most; 50 when left out, for every list. (1 to 200)

`spacesheep groups create`

Make a group: its title, and the addresses or @handles on it. Nobody is emailed.

spacesheep groups create <title> [flags]

Refusals: forbidden, invalid, not_found, quota_exceeded, rate_limited, read_only_grant
The same call: MCP tool create_group · web API POST /v1/me/groups

Every argument and flag

Argument or flag	Takes	What it is
`<title>`	a title	Its title, e.g. F26. (required; at most 60 characters)
`--add`	text	Addresses or @handles to put on it, in any form: one per line, commas, a CSV row, 'Name <addr>'. (at most 200,000 characters)
`--remove`	text	Addresses or @handles to take off it. (at most 200,000 characters)
`--share`	space name	A space you own to share with everyone on it: they may view, comment and fill in forms. Nobody is emailed.
`--share-id`	space id	`share` by its id, instead of its name.
`--unshare`	space name	A space you own to stop sharing with it.
`--unshare-id`	space id	`unshare` by its id, instead of its name.

`spacesheep groups update`

Rename a group, put people on it or take them off, or share a space of yours with it. Nobody is emailed.

spacesheep groups update <group> [flags]

Refusals: forbidden, invalid, not_found, rate_limited, read_only_grant
The same call: MCP tool update_group · web API PATCH /v1/me/groups/{group.id}

Every argument and flag

Argument or flag	Takes	What it is
`<group>`	group name	The group to change. (required)
`--title`	a title	Its title, e.g. F26. (at most 60 characters)
`--add`	text	Addresses or @handles to put on it, in any form: one per line, commas, a CSV row, 'Name <addr>'. (at most 200,000 characters)
`--remove`	text	Addresses or @handles to take off it. (at most 200,000 characters)
`--share`	space name	A space you own to share with everyone on it: they may view, comment and fill in forms. Nobody is emailed.
`--share-id`	space id	`share` by its id, instead of its name.
`--unshare`	space name	A space you own to stop sharing with it.
`--unshare-id`	space id	`unshare` by its id, instead of its name.

`spacesheep groups delete`

Delete a group. Every space shared with it stops being shared with its people.

spacesheep groups delete <group>

Refusals: forbidden, invalid, not_found, rate_limited, read_only_grant
The same call: MCP tool delete_group · web API DELETE /v1/me/groups/{group.id}

Every argument and flag

Argument or flag	Takes	What it is
`<group>`	group name	One of your groups, by its title (any case). (required)

Teams and organizations

`spacesheep teams list`

The teams you're in: each one's people and roles, plan and seats, auto-join domains and Slack workspaces.

spacesheep teams list [flags]

Refusals: invalid, read_only_grant
The same call: MCP tool list_teams · web API GET /v1/teams

Every argument and flag

Argument or flag	Takes	What it is
`--after`	text	Where to start: the last answer's `next`. From the start when left out.
`--limit`	integer	How many at most; 50 when left out, for every list. (1 to 200)

`spacesheep teams update`

Rename a team or set who joins it by email domain (team admins only), or make it your default.

spacesheep teams update <team> [flags]

Refusals: forbidden, invalid, not_found, rate_limited, read_only_grant
The same call: MCP tool update_team · web API PATCH /v1/teams/{team.id}

Every argument and flag

Argument or flag	Takes	What it is
`<team>`	team name	The team to change. (required)
`--title`	a title	Its title, as people see it: 1–60 characters. (at most 60 characters)
`--your-default`	true or false	Your default team: the one your share dialog offers first. true makes it so.
`--domains`	list of text	Email domains whose people join on their own when they sign in (acme.com). Empty clears it. Team plans only.

`spacesheep team-members create`

Invite someone to a team by email or @handle and email them the link. They join when they open it.

spacesheep team-members create (--team <team name> | --team-id <team id>) (--member <person name> | --member-id <person id>)

Refusals: forbidden, invalid, not_found, quota_exceeded, rate_limited, read_only_grant
The same call: MCP tool create_team_member · web API POST /v1/teams/{team.id}/members

Every argument and flag

Argument or flag	Takes	What it is
`--team`	team name	The team: its title, slug or id. (one of --team / --team-id, required)
`--team-id`	team id	`team` by its id, instead of its name. (one of --team / --team-id, required)
`--member`	person name	Who to invite: their @handle, or their email in member_id. Someone with no account signs up first. (one of --member / --member-id, required)
`--member-id`	person id	`member` by its id, instead of its name. (one of --member / --member-id, required)

`spacesheep team-members update`

Make someone on a team a Team admin, or a member again. Team admins only.

spacesheep team-members update <member> (--team <team name> | --team-id <team id>) [flags]

Refusals: forbidden, invalid, not_found, rate_limited, read_only_grant
The same call: MCP tool update_team_member · web API PATCH /v1/teams/{team.id}/members/{member.id}

Every argument and flag

Argument or flag	Takes	What it is
`<member>`	team member name	The team member to change. (required)
`--team`	team name	The team: its title, slug or id. (one of --team / --team-id, required)
`--team-id`	team id	`team` by its id, instead of its name. (one of --team / --team-id, required)
`--role`	one of owner, member	Their role: an owner is a Team admin. A team always keeps one.

`spacesheep team-members delete`

Take someone off a team, or leave it yourself. Team admins only, to take someone else off.

spacesheep team-members delete <member> (--team <team name> | --team-id <team id>)

Refusals: forbidden, invalid, not_found, rate_limited, read_only_grant
The same call: MCP tool delete_team_member · web API DELETE /v1/teams/{team.id}/members/{member.id}

Every argument and flag

Argument or flag	Takes	What it is
`<member>`	person name	Who to take off: their @handle, or their email in member_id. Your own to leave the team. (required)
`--team`	team name	The team: its title, slug or id. (one of --team / --team-id, required)
`--team-id`	team id	`team` by its id, instead of its name. (one of --team / --team-id, required)

`spacesheep teams create`

Start a team you own. With a slug, an organization at its own address (invite-only for now).

spacesheep teams create <title> [flags]

Refusals: forbidden, invalid, not_found, rate_limited, read_only_grant
The same call: MCP tool create_team · web API POST /v1/teams

Every argument and flag

Argument or flag	Takes	What it is
`<title>`	a title	Its title, as people see it: 1–60 characters. (required; at most 60 characters)
`--your-default`	true or false	Your default team: the one your share dialog offers first. true makes it so.
`--domains`	list of text	Email domains whose people join on their own when they sign in (acme.com). Empty clears it. Team plans only.
`--slug`	text	An organization's address, <slug>.spacesheep.dev (invite-only for now). A Team on spacesheep.dev when left out.

Was this page helpful?

CLI commands

Install and sign in

How a command reads

Publish and change a space

spacesheep spaces create

spacesheep spaces update

spacesheep spaces share

spacesheep spaces delete

spacesheep versions create

spacesheep versions restore

spacesheep uploads create

Find and read

spacesheep spaces list

spacesheep spaces get

spacesheep spaces search

spacesheep versions list

spacesheep files list

spacesheep files get

Share and comment

spacesheep comments list

spacesheep comments create

spacesheep comments update

spacesheep reactions create

spacesheep discussion-posts list

spacesheep discussion-posts create

spacesheep discussion-topics update

spacesheep groups list

spacesheep groups create

spacesheep groups update

spacesheep groups delete

Teams and organizations

spacesheep teams list

spacesheep teams update

spacesheep team-members create

spacesheep team-members update

spacesheep team-members delete

spacesheep teams create

`spacesheep spaces create`

`spacesheep spaces update`

`spacesheep spaces share`

`spacesheep spaces delete`

`spacesheep versions create`

`spacesheep versions restore`

`spacesheep uploads create`

`spacesheep spaces list`

`spacesheep spaces get`

`spacesheep spaces search`

`spacesheep versions list`

`spacesheep files list`

`spacesheep files get`

`spacesheep comments list`

`spacesheep comments create`

`spacesheep comments update`

`spacesheep reactions create`

`spacesheep discussion-posts list`

`spacesheep discussion-posts create`

`spacesheep discussion-topics update`

`spacesheep groups list`

`spacesheep groups create`

`spacesheep groups update`

`spacesheep groups delete`

`spacesheep teams list`

`spacesheep teams update`

`spacesheep team-members create`

`spacesheep team-members update`

`spacesheep team-members delete`

`spacesheep teams create`