starspace-cli 0.2.2

Push your repo to a StarSpace workspace and connect Claude, Cursor, or ChatGPT to it over MCP.

StarSpace CLI

Command line tools for StarSpace workspaces. Use it to push a local folder to StarSpace, inspect the remote workspace, and call the same mcp-run-v1 MCP server used by Claude, ChatGPT, Cursor, and other MCP clients.

• 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.

MCP commands

The starspace mcp group calls mcp-run-v1 directly over JSON-RPC. It uses the same workspace API key as the rest of the CLI, sends the current MCP protocol header, and accepts both JSON and event-stream responses.

Useful shortcuts:

starspace mcp tools --readonly
starspace mcp health
starspace mcp summary
starspace mcp search "auth middleware" --limit 5
starspace mcp fetch file:src/app.ts --start-line 1 --end-line 80
starspace mcp ask "How is billing enforced?"
starspace mcp run "rg -n billing src" --readonly

Raw calls are also available:

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'

--readonly routes through /functions/v1/mcp-run-v1/readonly, where write tools are not exposed. On that route, run is read-only. On the writable route, run_readonly is also available for read-only shell commands.

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.