CLI Reference

Every starspace command, side-by-side with its REST API equivalent. The CLI is a thin wrapper, anything it can do, you can do directly with curl.

Install

pip install starspace-cli

Requires Python 3.8+. Source: github.com/starspace-run/starspace-cli.

Global flags

These work on every command:

Flag	Effect
--json	Emit machine-readable JSON to stdout. Errors go to stderr as JSON. Built for AI agents and scripting.
-v / --verbose	Verbose diagnostic logging to stderr.

Exit codes

Stable contract, use these to dispatch in scripts without parsing stdout.

Code	Meaning
0	success
1	user error (bad arg, missing config, validation_error, payload_too_large)
2	server error (5xx)
3	auth error (401, 403)
4	quota / rate limit (429: quota_exceeded, rate_limited)

starspace init

Set up CLI credentials. Validates the API key against /whoami before writing the config so you fail fast if anything's wrong.

init (CLI)bash

# Interactive (writes ~/.config/starspace/config.json)
starspace init

# Project-scoped (writes ./.starspace/config.json)
starspace init --project

# Non-interactive
starspace init \
  --workspace-id <uuid> \
  --api-key ak_xxx

starspace doctor

Diagnose why something isn't working, config, key validity, base-URL reachability, MCP-config-file writability, local sync state.

doctor (CLI)bash

starspace doctor              # human output
starspace --json doctor       # JSON output (for agents / CI)

starspace whoami

Print the identity behind the current API key, user, workspace, tier, key prefix.

whoami (CLI)bash

starspace whoami
starspace --json whoami       # {"user_id": "...", "workspace_id": "...", "tier": "pro", "key_prefix": "ak_xxx"}

starspace summary

One-screen summary of the workspace: file count, total size, top extensions, largest files, most-recent edits. Backed by an indexed RPC so it's one round-trip even on large workspaces.

summary (CLI)bash

starspace summary
starspace --json summary      # {file_count, total_size_bytes, dir_count, extensions, largest_files, recent_files, ...}

starspace ls

List files in the remote workspace. Optional path prefix, sortable by path / size / updated time.

ls (CLI)bash

starspace ls                              # list everything (default limit 1000)
starspace ls src/                         # filter by prefix
starspace ls src/ --sort size             # largest first
starspace ls src/ --sort updated          # most recent first
starspace ls --limit 50
starspace --json ls src/services/         # {"items": [...], "count": N}

starspace cat

Stream a single remote file to stdout. Pipe-friendly, combines well with less, grep, jq, etc.

cat (CLI)bash

starspace cat src/main.ts
starspace cat src/main.ts | grep TODO
starspace cat package.json | jq .dependencies
starspace --json cat src/main.ts          # {file_path, content, size_bytes, content_hash, updated_at}

starspace connect

Print an MCP server config snippet (with your workspace baked in) and the path to the file you should paste it into per OS.

connect (CLI)bash

starspace connect claude           # Claude Desktop snippet
starspace connect cursor           # Cursor snippet
starspace connect chatgpt          # ChatGPT connector instructions
starspace --json connect claude    # JSON: { client, config_file, server_url, snippet }

starspace status

Diff between local directory and remote workspace. Lists files to pull, files to push, and modified files.

status (CLI)bash

starspace status              # human diff
starspace --json status       # {"in_sync": false, "to_pull": [...], "modified": [...], "to_push": [...]}

starspace push

Compress local files into a ZIP and upload to the workspace. Smart ignore handles .git, node_modules, .venv, etc.

push (CLI)bash

starspace push                 # push from current directory
starspace push --delete        # also delete remote files missing locally
starspace --json push          # {"pushed": 14, "skipped": 0, "batches": 1, ...}

starspace pull

Pull remote files (e.g., generated by an AI agent) back to local. Refuses to overwrite uncommitted local changes unless you pass --force.

pull (CLI)bash

starspace pull                 # pull remote → local
starspace pull --force         # overwrite local changes
starspace --json pull          # {"pulled": 14, "files": [...]}

starspace sync

Pull remote changes then push local changes in one shot.

sync (CLI)bash

starspace sync                # pull then push
starspace sync --delete       # plus delete remote files missing locally

starspace usage

Credits, storage, workspace counts (split by flavor - Indexed vs Sandbox), and the per-tier indexing token budget.

usage (CLI)bash

starspace usage
starspace --json usage        # {tier, workspace_type, credits, storage, workspaces: {indexed_used, sandbox_used, ...}, indexed_tokens: {used, max_per_workspace, max_per_account}, requests}

starspace convert sandbox

Demote an Indexed workspace to Sandbox. Drops every chunk and embedding (so ask and search stop working), but keeps every file in the index. Use this when you hit the per-tier indexing token budget and want to keep the workspace as a persistent shell + filesystem. Promotion back to Indexed is not supported in v1.

convert-sandbox (CLI)bash

starspace convert sandbox                       # workspace from config
starspace convert sandbox -w <workspace-uuid>   # explicit target
starspace convert sandbox -y                    # skip confirmation prompt

Error format

Errors include a stable code, a message, and (where helpful) a hint:

# Plain output:
$ starspace status
error [unauthenticated]: Unauthorized
  hint: Pass a valid Authorization header, either a session JWT or an ak_… API key.

# JSON output (errors go to stderr):
$ starspace --json status
{"error": {"code": "unauthenticated", "message": "Unauthorized", "hint": "...", "status": 401}}

# Indexing budget reached (workspace tokens exceed the per-tier cap):
$ starspace push
error [indexed_token_limit]: This indexed workspace has used 510,000 of its 500,000 indexing-token budget.
  hint: Upgrade to Hobby ($7/mo, 5M tokens/workspace), or convert this workspace to Sandbox (keeps all files, drops semantic search).
  cap:  workspace 510000/500000 (tier: free)
  next steps:
    Upgrade:             https://starspace.run/pricing
    Convert to Sandbox:  starspace convert sandbox -w <workspace-uuid>

See the Workspace API reference for the full list of error codes.