npm package: @sweet-cli/sweet
Description: Sweet CLI — AI software engineer in your terminal (agent-only).
Latest version: 0.2.6

# Sweet CLI

Sweet CLI is a fast, terminal-first AI coding assistant that runs a local Python agent and streams results back to your shell. It’s optimized for real-world software engineering tasks: search, edit, run, commit, and iterate quickly.

## Key features
- Starts a local Python agent in a per-user virtualenv and streams output live
- Caches the agent bundle under `~/.sweet/agent` and auto-updates from your billing host
- First-class project/session handling; resume where you left off
- Sensible defaults with safe production guardrails
- Supports multiple providers, including DeepSeek and OpenRouter

## Requirements
- Node.js >= 18
- Python 3.8+ available on PATH (the CLI will create a venv under `~/.sweet/agent/.sweetvenv`)

## Install
```bash
npm i -g @sweet-cli/sweet
```

Verify:
```bash
sweet --version
sweet --help
```

## Quick start
```bash
# Start the agent (DeepSeek by default)
sweet start "Analyze my repo and propose a refactor plan"
```

During the first run, Sweet will:
- Seed (or refresh) the agent cache in `~/.sweet/agent`
- Create a Python virtualenv and install requirements
- Launch the agent and stream results in your current directory

## Commands
### start
```bash
sweet start [message...] [options]
```
Options:
- `-p, --provider <provider>`: `deepseek` (default) | `openrouter` | `nebius`
- `-m, --model <model>`: override model name
- `--resume-last`: resume the most recent session
- `--session <id>`: resume a specific session by ID

### init
```bash
sweet init
```
Creates a minimal `SWEET.md` guidance file in the current directory.

### login
```bash
sweet login --api-base <url>
```
Signs in to your billing host and saves a token to `~/.sweet/config.json`.

### sessions
```bash
sweet sessions
```
Lists available sessions (and ensures the agent venv exists locally).

## Providers and models
### DeepSeek (default)
No extra setup needed when using the relay (billing host). If you want to use a direct provider API key locally (not recommended), set `SWEET_ALLOW_CLIENT_KEYS=true` and export the provider key (e.g., `DEEPSEEK_API_KEY`).

### OpenRouter (DeepSeek v3.1 via OpenRouter)
You can run the agent via OpenRouter using your own key. The agent uses the OpenAI SDK interface for OpenRouter, so prefer `OPENAI_API_KEY` for compatibility.

One‑shot example (inline env):
```bash
OPENAI_API_KEY=sk-or-v1-... SWEET_ALLOW_CLIENT_KEYS=true \
  sweet start -p openrouter -m deepseek/deepseek-chat-v3.1
```

Or export then run:
```bash
export OPENAI_API_KEY=sk-or-v1-...
export SWEET_ALLOW_CLIENT_KEYS=true
sweet start -p openrouter -m deepseek/deepseek-chat-v3.1
```

Notes:
- Free tier: use `-m deepseek/deepseek-chat-v3.1:free`
- The CLI only forwards provider keys to the agent if `SWEET_ALLOW_CLIENT_KEYS=true`. Without this flag, keys remain unset on the agent side.

## Environment variables
- `SWEET_BILLING_API`: Base URL of billing/relay server (e.g., `https://billing.sweetcli.com`)
- `SWEET_BILLING_TOKEN`: Saved after `sweet login`; used to authenticate with billing/relay
- `SWEET_RELAY_API`: Relay API base for model calls (usually derived from billing API)
- `SWEET_AGENT_BASE_URL`: Override where the agent bundle (`sweet-agent.tgz`) is fetched
- `SWEET_AGENT_CACHE_ROOT`: Override cache path (default `~/.sweet/agent`)
- `SWEET_MINIMAL_DEPS=1`: Install a slim Python requirements set to save disk
- `SWEET_ALLOW_CLIENT_KEYS=true`: Allow forwarding provider keys into the agent process
- Provider keys (only respected when `SWEET_ALLOW_CLIENT_KEYS=true`):
  - `OPENAI_API_KEY` (recommended for OpenRouter)
  - `DEEPSEEK_API_KEY` (direct DeepSeek usage)
  - `SERPER_API_KEY` (optional search provider)

## Agent bundle and cache
- The CLI installs or refreshes the agent in `~/.sweet/agent` and executes it from there.
- By default it downloads `sweet-agent.tgz` from the configured billing host with cache-busting.
- Override bundle source:
```bash
SWEET_AGENT_BASE_URL=https://your-host.example sweet start
```

### Local development source
You can force the CLI to use your local agent source (this repo) instead of downloading a bundle:
```bash
SWEET_AGENT_LOCAL_DIR=/absolute/path/to/sweagent sweet start
```
This will copy your local files into `~/.sweet/agent` on each run and execute from there.

## Sessions and project directory
- The agent runs in your current working directory by default; Sweet sets `SWEET_PROJECT_DIR` internally.
- Use `--resume-last` or `--session <id>` to continue prior work.

## Insufficient balance behavior
- On start: the CLI will prompt you to add credits and wait for Enter.
- Mid‑run: the agent auto‑pauses when balance is insufficient, shows the billing URL, and waits for you to press Enter after adding credits. Your context is preserved.

## Troubleshooting
- “request entity too large” when sending long payloads: reduce message size or let the agent condense automatically; ensure the billing host allows larger bodies if needed.
- Virtualenv problems on first run: re-run; or set `SWEET_MINIMAL_DEPS=1` for slim deps.
- Force-refresh agent cache:
```bash
rm -rf ~/.sweet/agent && sweet start
```
- Override bundle host for testing:
```bash
SWEET_AGENT_BASE_URL=https://<your-host> sweet start
```

## Uninstall
```bash
npm uninstall -g @sweet-cli/sweet
rm -rf ~/.sweet/agent ~/.sweet/config.json
```

## Security notes
- Provider keys are not forwarded to the agent unless you explicitly set `SWEET_ALLOW_CLIENT_KEYS=true`.
- Billing tokens are stored in `~/.sweet/config.json`.

---
For support or feature requests, open an issue or reach out via your billing portal.