Tutorials

End-to-end walkthroughs. Each one is a complete, copy-pasteable recipe for a real workflow.

1. Sync your first workspace from the CLI

From zero to "your codebase is on Starspace" in under three minutes.

Step 1, Install the CLI

pip install starspace-cli

Step 2, Get a workspace + key

Sign in at app.starspace.run. Create a workspace if you don't have one, then go to Workspace Settings → API Keys → Create key. Copy the ak_… key (you'll only see it once).

Step 3, Initialize the CLI

From your project's root directory:

cd my-project/
starspace init --project        # writes ./.starspace/config.json

Answer the three prompts (workspace ID, API key, base URL, press Enter to accept the default https://api.starspace.run).

Step 4, Sanity-check

starspace doctor

You should see all checks passed for config, base URL, and API key.

Step 5, Push your codebase

starspace push

Smart ignore handles .git, node_modules, .venv, and other common noise. Files larger than 1 MB are skipped.

Step 6, Verify

starspace status

Should print Local and remote are in sync.

2. Pull a workspace into a fresh directory

For a teammate who needs to grab everything an AI agent has been editing.

mkdir my-project-copy && cd my-project-copy

# Set up credentials (interactive)
starspace init --project

# Pull all files
starspace pull --force          # --force because the dir is empty
ls -la                          # see your synced files

Pull is hash-based, repeated starspace pull calls only download files that actually changed. It's safe to run on a cron.

3. Connect your workspace to Claude Desktop

Once your code is synced, give Claude Desktop direct read/search access over MCP.

Step 1, Generate the snippet

starspace connect claude

The CLI prints a JSON block plus the path to your Claude Desktop config file (varies by OS).

Step 2, Edit the config

Open the path the CLI gave you. If mcpServers already exists, merge the starspace key in alongside any existing entries, don't replace the whole object.

{
  "mcpServers": {
    // ... your existing servers ...
    "starspace": {
      "url": "https://api.starspace.run/functions/v1/mcp-run-v1",
      "headers": { "Authorization": "Bearer ak_your_key_here" }
    }
  }
}

Step 3, Restart Claude Desktop

Quit and re-launch. Open a new chat and ask: "What MCP tools do you have access to?"

You should see search, fetch, workspace_summary,manifest, run_readonly, and friends, all scoped to your workspace.

4. Drive the CLI from an AI agent (using `--json`)

Every command supports --json for machine-readable output and uses stable exit codes. AI agents and CI pipelines can dispatch on them without parsing prose.

Bash example

# Push and capture the result. Bail with the same code on failure.
result=$(starspace --json push) || exit $?
pushed=$(echo "$result" | jq -r '.pushed')
echo "Pushed $pushed files"

# Branch on whether anything is out of sync.
if starspace --json status | jq -e '.in_sync == false' > /dev/null; then
    echo "Drift detected, running pull then push"
    starspace --json pull --force && starspace --json push
fi

Python example

import json, subprocess, sys

def cli(*args: str) -> dict:
    """Run a starspace command in --json mode and return the parsed payload."""
    proc = subprocess.run(
        ["starspace", "--json", *args],
        capture_output=True, text=True,
    )
    if proc.returncode != 0:
        # Errors go to stderr as JSON in --json mode.
        err = json.loads(proc.stderr)
        raise SystemExit(f"{args[0]} failed: {err['error']}")
    return json.loads(proc.stdout) if proc.stdout.strip() else {}

state = cli("status")
if not state["in_sync"]:
    cli("pull", "--force")
    cli("push")
print("Workspace is in sync.")

Exit-code dispatch

starspace --json status
case $? in
  0) echo "ok" ;;
  1) echo "user error, check args" ;;
  2) echo "server error, retry with backoff" ;;
  3) echo "auth error, refresh API key" ;;
  4) echo "rate limited, back off and retry" ;;
esac

5. Inspect a remote workspace from the CLI

Once your code is in Starspace you don't have to pull it back to look at it, the CLI has read commands that talk to the index directly.

Who am I?

starspace whoami
# user_id:      eb27f4ab-3465-...
# workspace_id: 92d087e3-75dd-...
# tier:         pro
# key_prefix:   ak_8fc60

What's in this workspace?

starspace summary
# files:        482
# size:         4.2 MB
# directories:  94
# last update:  2026-05-06T09:37:12...
#
# Top extensions:
#   177  .ts
#   173  .tsx
#    51  .sql
#
# Largest files:
#   409.4 KB  package-lock.json
#   205.5 KB  bun.lock
#   ...
#
# Recent edits:
#   2026-05-06T09:37:12  smoke.txt
#   ...

Drill in to a directory

# List the largest files under src/, capped at 20
starspace ls src/ --sort size --limit 20

# Most-recently-edited files (anywhere in the workspace)
starspace ls --sort updated --limit 10

# Read one file straight to stdout, pipes cleanly into less / grep / jq
starspace cat src/main.ts | less
starspace cat package.json | jq .dependencies
starspace cat src/services/agentService.ts | grep -n TODO

Pure-shell drift report

# How many files in the workspace are bigger than 100 KB?
starspace --json ls --limit 10000 \
  | jq '[.items[] | select(.size_bytes > 102400)] | length'

# What .py files have I changed in the last hour?
starspace --json ls --sort updated --limit 200 \
  | jq -r '.items[] | select(.file_path | endswith(".py"))
                    | "\(.updated_at)  \(.file_path)"' | head

6. Auto-sync on every git commit

Keep your Starspace workspace pinned to your latest committed state.

# In your repo:
cat > .git/hooks/post-commit << 'HOOK'
#!/bin/sh
starspace push 2>&1 | tail -1
HOOK
chmod +x .git/hooks/post-commit

Each commit triggers a push. Only the changed files are uploaded (hash-based delta), so this is cheap.