StarSpace CLI

A workspace is your virtual Unix environment in the cloud - files, a read-only/read-write shell, semantic search, all reachable from the CLI and from any MCP-aware agent.

starspace mcp run "rg -n 'fn main' | head -20" --readonly
starspace cat src/main.rs | bat -l rust
starspace mcp ask "where is auth enforced?"

Push your folder once. From then on you can grep, find, rg, ls, cat, tree, pipe between them - locally on the cloud workspace - through one command. Plug an agent in via MCP and it has the same shell.

• Website: starspace.run
• Docs hub: starspace.run/docs
• CLI reference: starspace.run/docs/cli-reference
• Workspace API: starspace.run/docs/workspace-api
• MCP server: starspace.run/docs/mcp-server

Install

Recommended (isolated env, starspace exposed globally, easy upgrades):

# If you use uv (https://docs.astral.sh/uv/)
uv tool install starspace-cli

# Or pipx
pipx install starspace-cli

Plain pip also works (project-scoped venv or --user):

pip install starspace-cli            # or: python3 -m pip install starspace-cli

After install, starspace --help lists every command. If pip isn't on your PATH (common on macOS), use python3 -m pip install starspace-cli.

Quick start

starspace init               # save workspace id and API key
starspace push               # upload the current folder
starspace connect claude     # print an MCP config snippet
starspace mcp summary        # verify the MCP workspace view

Create a workspace and API key in the dashboard at starspace.run, under Workspace > API Keys. Full walkthrough at starspace.run/docs.

Workspace types

StarSpace has two workspace types. The CLI works with both.

Type	MCP tools	Best for
Indexed (default)	search, ask, fetch, workspace_summary, run, run_readonly, write tools	Codebases where semantic search and Q&A matter.
Sandbox	fetch, workspace_summary, run, run_readonly, write tools	Agent scratchpads and shell-style workspaces that do not need embeddings.

Indexed workspaces can be converted to Sandbox:

starspace convert sandbox

Conversion keeps files, drops chunks and embeddings, and disables search and ask for that workspace. Promotion back to Indexed is not supported in v1. Create a new Indexed workspace if you need semantic search again.

Configuration

Credentials are resolved in this order:

1. Environment variables: STARSPACE_WORKSPACE_ID, STARSPACE_WORKSPACE_API_KEY, and optional STARSPACE_BASE_URL.
2. Project config: ./.starspace/config.json, created with starspace init --project.
3. Global config: ~/.config/starspace/config.json on Linux and macOS, or %APPDATA%\starspace\config.json on Windows.

STARSPACE_BASE_URL defaults to https://api.starspace.run.

Core commands

starspace init

Save credentials. The command validates the API key with /whoami before it writes a config file.

starspace init
starspace init --project
starspace init --workspace-id <id> --api-key <ak_...>

starspace doctor

Check local config, API key validity, API reachability, MCP config paths, and local sync state.

starspace doctor

starspace push

Zip and upload local files to the workspace. Common generated folders such as .git, node_modules, .venv, dist, and build are ignored. Files larger than 1 MB are skipped by default.

starspace push
starspace push --root .
starspace push --delete
starspace -v push

starspace pull, status, and sync

starspace status       # compare local files with remote state
starspace pull         # download remote changes
starspace pull --force # overwrite local changes
starspace sync         # pull, then push

starspace connect <client>

Print an MCP server config snippet for a client.

starspace connect claude
starspace connect cursor
starspace connect chatgpt

The command only prints config in v1. It does not edit client files.

Shell access over MCP

The starspace mcp group is the headline feature: it gives you a real shell against the workspace's virtual filesystem. The agents you connect over MCP get the same shell - so anything you can do in the CLI, your agent can do too.

What you can do

# Run any read-only Unix pipeline against your workspace
starspace mcp run "rg -n 'class \\w+' src | head" --readonly
starspace mcp run "find . -name '*.test.ts' | xargs wc -l" --readonly
starspace mcp run "git log --oneline -20" --readonly

# Natural-language Q&A backed by semantic search + ranked retrieval
starspace mcp ask "How is rate limiting enforced?"
starspace mcp search "auth middleware" --limit 5

# Read a specific range out of any file (line-precise grounding)
starspace mcp fetch file:src/app.ts --start-line 1 --end-line 80

# Workspace snapshot - file count, top dirs, what's indexed
starspace mcp summary

# Structured per-file table (path, size, type, content_hash). Add
# --extract for markdown titles + code symbols on the first 100 entries.
# Cheaper than rg-walking when you need to plan across many files.
starspace mcp manifest --limit 200
starspace mcp manifest -p src/ --extract

# Print a copy-paste system-prompt fragment teaching an MCP-connected
# agent how to use this workspace. --raw pipes cleanly into your agent.
starspace mcp instructions
starspace mcp instructions --raw

# Health check / connectivity probe
starspace mcp health

Truncation telemetry

When run or run_readonly output is capped, the response's structuredContent.truncation block tells agents exactly how to continue:

{
  "truncated": true,
  "total_lines": 500, "shown_lines": 200,
  "shown_range": { "start": 1, "end": 200 },
  "suggested_next_range": { "start": 201, "end": 400 }
}

The human-readable footer also names the next range, so the agent can just run cat path 201:400 to keep reading.

Write tools

When you call starspace mcp without --readonly, write tools are also available. Edit through structured patches, not blind overwrites:

starspace mcp call write_file --arg path=notes.txt --arg content='hello'
starspace mcp call edit_file --arg path=src/app.ts --arg-json '{
  "operations": [{"replace": "old", "with": "new"}]
}'
starspace mcp call apply_patch --arg patch='*** Update File: src/app.ts...'

Read-only vs. writable routes

• starspace mcp <cmd> - writable route, all tools, including run (RW) and write_file/edit_file/apply_patch.
• starspace mcp <cmd> --readonly - read-only route. run is gated to read-only commands; write tools are not advertised at all. Use this for agent runs you want to be safe by construction.

Tool index

Tool	What it does
run	Execute a Unix shell pipeline (rg, grep, find, cat, ls, head, awk, sed, ...)
run_readonly	Same as run, but rejects any command that could mutate the workspace
fetch	Read a file (or a line range of it) by id - the canonical reader
search	Hybrid retrieval - keyword + semantic + symbol over the indexed workspace
ask	Natural-language Q&A with cited line ranges
write_file	Create or overwrite a file
edit_file	Structured replace/insert/delete on an existing file
apply_patch	Surgical diff-style edits
workspace_summary	File count, top dirs, indexing status
manifest	Structured per-file table (path, size, type, hash). with_extracted=true adds markdown titles + code symbols on the first 100 rows. Paginated via limit / offset.
server_health	Liveness, version, tool manifest hash
list_workspaces	List workspaces the current token is authorized for

Discover the live tool list anytime:

starspace mcp tools             # writable route
starspace mcp tools --readonly  # read-only route (subset)

Raw JSON-RPC

When you need to call a tool by name without an alias:

starspace mcp call server_health
starspace mcp call run --arg command='tree -L 2'
starspace mcp call write_file --arg path=notes.txt --arg content='hello'

Read commands

starspace whoami
starspace usage
starspace summary
starspace ls [prefix]
starspace cat path/to/file

starspace summary, ls, and cat use the workspace management API. The starspace mcp summary, mcp search, and mcp fetch commands use the MCP server surface.

Workspace conversion and quotas

starspace convert sandbox
starspace convert sandbox -w <workspace-uuid>
starspace convert sandbox -y
starspace usage

Indexed file quotas:

Tier	Indexed files per workspace	Indexed files per account
Free	100	100
Hobby ($7/mo)	2,000	10,000
Pro ($19/mo)	20,000	100,000

If a push hits the indexed file cap, the CLI prints the upgrade URL and a copy-pastable starspace convert sandbox command.

Global flags

Flag	Effect
--json	Emit machine-readable JSON to stdout. Errors go to stderr as JSON.
-v, --verbose	Print diagnostic logs to stderr, including per-file skip reasons during push.

Examples:

starspace --json status
starspace --json push
starspace --json doctor
starspace -v push

Recipes - composing with Unix tools

Every command honors the global --json flag and emits structured output on stdout; errors go to stderr. starspace cat <path> (no --json) prints raw file content, so pipes into grep, less, bat, jq, or your editor cleanly.

List the 10 biggest files in the workspace

starspace --json ls --sort size --limit 10 \
  | jq -r '.items[] | "\(.size_bytes)\t\(.file_path)"' \
  | numfmt --to=iec --field=1

Find all Python files containing "TODO"

starspace --json ls \
  | jq -r '.items[].file_path | select(endswith(".py"))' \
  | while read -r f; do
      starspace cat "$f" 2>/dev/null | grep -Hn --label="$f" TODO
    done

Count files by extension

starspace --json ls \
  | jq -r '.items[].file_path | split(".") | last' \
  | sort | uniq -c | sort -rn

Diff a remote file against your local working copy

diff <(starspace cat src/app.py) src/app.py

Pipe a remote file into your favorite reader

starspace cat README.md | bat -l md       # or | less, | glow, | mdcat
starspace cat src/main.py | rg -n 'def\s+\w+\('

Chain mcp ask into cat to read the cited files

starspace --json mcp ask "where is the auth flow defined?" \
  | jq -r '.content[].text' \
  | grep -oE '[a-zA-Z0-9_/.-]+\.(py|ts|tsx)' \
  | sort -u | head -5 \
  | while read -r f; do
      echo "─── $f ───"; starspace cat "$f" 2>/dev/null
    done

One-liner status: how much of the indexing budget have I used?

starspace --json usage | jq '.indexed_tokens'

Mirror the workspace to a local dir, then run rg

starspace pull --root ./snapshot && rg -n 'TODO' ./snapshot

pull is one HTTP round-trip; subsequent rg/grep/fd runs are local speed, no per-grep API cost.

Errors and exit codes

Human-readable errors include a stable code, a message, and sometimes a hint:

error [unauthenticated]: Unauthorized
  hint: Pass a valid Authorization header, either a session JWT or an ak_... API key.

In --json mode the same error is printed as JSON on stderr:

{"error": {"code": "unauthenticated", "message": "Unauthorized", "hint": "...", "status": 401}}

Exit codes are stable:

Code	Meaning
0	Success
1	User error, such as a bad arg, missing config, missing file, or validation failure
2	Server error, such as a 5xx response
3	Auth error, such as 401 or 403
4	Quota or rate limit, such as 429 or an indexed file cap

More

• Full CLI reference, including the mcp subcommands and every flag: starspace.run/docs/cli-reference
• MCP server protocol + tool list: starspace.run/docs/mcp-server
• Workspace REST API (what the CLI calls under the hood): starspace.run/docs/workspace-api
• Source + issues: github.com/starspace-run/starspace-cli

License

MIT.