Metadata-Version: 2.4
Name: starspace-cli
Version: 0.2.8
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

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.

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

## 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

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

```json
{
  "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:

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

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

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

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