Metadata-Version: 2.4
Name: starspace-cli
Version: 0.2.2
Summary: Push your repo to a StarSpace workspace and connect Claude, Cursor, or ChatGPT to it over MCP.
Project-URL: Homepage, https://starspace.run
Project-URL: Documentation, https://starspace.run/docs/cli-reference
Project-URL: Source, https://github.com/starspace-run/starspace-cli
Project-URL: Issues, https://github.com/starspace-run/starspace-cli/issues
Project-URL: Changelog, https://github.com/starspace-run/starspace-cli/releases
Author-email: StarSpace <ace@starspace.run>
Maintainer-email: StarSpace <ace@starspace.run>
License-Expression: MIT
License-File: LICENSE
Keywords: agent-workspace,ai-agent,chatgpt,claude,cursor,developer-tools,embedding,mcp,model-context-protocol,semantic-search
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://starspace.run)
- **Docs hub:** [starspace.run/docs](https://starspace.run/docs)
- **CLI reference:** [starspace.run/docs/cli-reference](https://starspace.run/docs/cli-reference)
- **Workspace API:** [starspace.run/docs/workspace-api](https://starspace.run/docs/workspace-api)
- **MCP server:** [starspace.run/docs/mcp-server](https://starspace.run/docs/mcp-server)

## Install

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

```bash
# 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`):

```bash
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

```bash
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](https://starspace.run), under **Workspace > API Keys**. Full
walkthrough at [starspace.run/docs](https://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:

```bash
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.

```bash
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.

```bash
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.

```bash
starspace push
starspace push --root .
starspace push --delete
starspace -v push
```

### `starspace pull`, `status`, and `sync`

```bash
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.

```bash
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:

```bash
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:

```bash
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

```bash
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

```bash
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:

```bash
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

```bash
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"

```bash
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

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

### Diff a remote file against your local working copy

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

### Pipe a remote file into your favorite reader

```bash
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

```bash
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?

```bash
starspace --json usage | jq '.indexed_tokens'
```

### Mirror the workspace to a local dir, then run `rg`

```bash
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:

```text
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:

```json
{"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](https://starspace.run/docs/cli-reference)
- MCP server protocol + tool list:
  [starspace.run/docs/mcp-server](https://starspace.run/docs/mcp-server)
- Workspace REST API (what the CLI calls under the hood):
  [starspace.run/docs/workspace-api](https://starspace.run/docs/workspace-api)
- Source + issues: [github.com/starspace-run/starspace-cli](https://github.com/starspace-run/starspace-cli)

## License

MIT.
