Metadata-Version: 2.4
Name: tokensaver-cli
Version: 0.3.4
Summary: TokenSaver CLI — route AI agents (Claude Code, Cursor, Codex) through the control plane
Author: TokenSaver
License-Expression: MIT
Project-URL: Homepage, https://platform.tokensaver.fr
Project-URL: Documentation, https://tokensaver.fr/sdk-api
Project-URL: PyPI, https://pypi.org/project/tokensaver-cli/
Keywords: tokensaver,llm,cli,claude,cursor,mcp,agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# TokenSaver CLI (`tokensaver-cli`)

Console command **`tokensaver`** to route AI agents through the **TokenSaver control plane** — cache, compression, PII, MCP gateway, observability.

Companion package to **[`tokensaver-sdk`](https://pypi.org/project/tokensaver-sdk/)**.

## Quick start (no dashboard required)

```bash
pip install -U tokensaver-cli
tokensaver login                 # signup or sign-in → saves credentials + ts_… key
tokensaver route claude --launch
tokensaver doctor --claude
```

Credentials live in `~/.config/tokensaver/credentials.json` (mode `0600`).  
`TOKENSAVER_API_KEY` still overrides the file when set.

## Installation

```bash
pip install tokensaver-cli
```

Monorepo:

```bash
cd packages/cli
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
```

**Requirements:** Python ≥ 3.10, stdlib only.

## Auth & keys

| Command | Purpose |
|---------|---------|
| `tokensaver login` | Interactive signup/sign-in (Free plan + API key) |
| `tokensaver login --email you@acme.com --signup -y` | Non-interactive signup |
| `tokensaver login --key ts_…` | Import an existing key (no JWT) |
| `tokensaver logout` | Remove local credentials |
| `tokensaver whoami` | Email, plan, key prefix, Flux IA link |
| `tokensaver approve [model]` | Approve model in Agent Registry (zero-trust) |
| `tokensaver models` | List profiles + catalogue models |
| `tokensaver use <profile\|model>` | Set Claude model (sticky) + approve |
| `tokensaver flows [--open]` | Flux IA URL + recent runs |
| `tokensaver catalog …` | List / approve Agent Registry |
| `tokensaver keys list` | List API keys |
| `tokensaver keys create --name CLI --use` | Create key and set as default |
| `tokensaver keys revoke <id>` | Delete a key |

## Routing

| Command | Purpose |
|---------|---------|
| `tokensaver route claude [--launch]` | Configure Claude Code + plugin |
| `tokensaver route claude --scope project --profile cheap --with-fs` | Project scope, cheap model, FS gateway |
| `tokensaver route cursor` / `codex` / `proxy` / `mcp` | Other agents |
| `tokensaver unroute <target>` | Restore backups |
| `tokensaver doctor [--claude] [--local]` | Health checks |
| `tokensaver status [--line\|--hook]` | Route status + Flux IA |
| `tokensaver profiles` | cheap / default / strong (plan-aware) |
| Claude plugin slash | `/tokensaver-router:models\|use\|flows\|quota\|cache\|catalog\|…` |

### Claude Code options

| Flag | Effect |
|------|--------|
| `--scope user\|project\|local` | Settings file scope |
| `--model` / `--profile` | Catalogue model or profile |
| `--with-fs` | Trust Gateway + filesystem for cwd |
| `--no-plugin` | Skip `~/.claude/skills/tokensaver-router` |
| `--local` | Self-host URL defaults |

On **Free**, default profile uses `openrouter/z-ai/glm-4.7-flash` (allowlist). Paid keeps Sonnet/Opus. Plan is stored at login (`plan_slug`); refresh with `tokensaver whoami`.

## Environment

```bash
export TOKENSAVER_API_KEY=ts_…   # optional if logged in
export TOKENSAVER_MODE=local     # or --local
export TOKENSAVER_PLAN=free      # optional override for Free defaults
export TOKENSAVER_CONSOLE_URL=…
```

## Docs

- Integration: [`docs/INTEGRATION-ROUTE-CLI.md`](../../docs/INTEGRATION-ROUTE-CLI.md)
- API reference: [tokensaver.fr/sdk-api](https://tokensaver.fr/sdk-api)

## Tests

```bash
cd packages/cli && pip install -e ".[dev]" && pytest -q
```

## Publishing

See [`docs/PYPI-CLI-RELEASE.md`](../../docs/PYPI-CLI-RELEASE.md). Tag: **`cli-vX.Y.Z`**.
