Metadata-Version: 2.4
Name: tokensaver-cli
Version: 0.2.0
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/)** (Python API client). The CLI configures your **local machine**; the pipeline runs on TokenSaver (SaaS or local self-host).

**Get started:** sign up at [platform.tokensaver.fr](https://platform.tokensaver.fr), create a **`ts_…`** API key, then:

```bash
pip install tokensaver-cli
export TOKENSAVER_API_KEY=ts_your_key
tokensaver route claude --launch
tokensaver doctor --claude
```

## Installation

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

Development inside the monorepo:

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

**Requirements:** Python ≥ 3.10, no extra runtime dependencies (stdlib only).

## Commands

| Command | Purpose |
|---------|---------|
| `tokensaver route claude` | Configure Claude Code (settings + `.mcp.json` + plugin) |
| `tokensaver route claude --launch` | Configure + start `claude` |
| `tokensaver route claude --scope project --profile cheap --with-fs` | Project scope, cheap model, FS via Trust Gateway |
| `tokensaver route cursor` | Write `.cursor/mcp.json` + print Override URL steps |
| `tokensaver route codex` | Print OpenAI-compat env vars for Codex |
| `tokensaver route proxy` | Show base URLs for LangChain / OpenAI SDK / your code |
| `tokensaver unroute <target>` | Restore backed-up config |
| `tokensaver doctor [--claude] [--local]` | Check endpoints (+ Claude end-to-end probes) |
| `tokensaver status [--line\|--hook]` | Route status + Flux IA console link |
| `tokensaver profiles` | List cheap / default / strong model profiles |

### Claude Code options

| Flag | Effect |
|------|--------|
| `--scope user\|project\|local` | Settings file: `~/.claude/settings.json`, `.claude/settings.json`, or `.claude/settings.local.json` |
| `--model PROVIDER/ID` | Catalogue model id (sets `ANTHROPIC_MODEL`) |
| `--profile cheap\|default\|strong` | Built-in (or custom) profile from `~/.config/tokensaver/route/profiles.json` |
| `--with-fs` | Stdio MCP: `tokensaver-mcp-gateway` + filesystem for cwd |
| `--no-plugin` | Skip installing `~/.claude/skills/tokensaver-router` |
| `--local` | Force local self-host URL defaults |

Slash commands after plugin install: `/tokensaver-router:setup`, `:status`, `:pipeline`, `:model`, `:unroute`.

## SaaS defaults

| Surface | URL |
|---------|-----|
| API | `https://api.tokensaver.fr` |
| OpenAI-compat | `https://api.tokensaver.fr/openai/v1` |
| Anthropic-compat | `https://api.tokensaver.fr/anthropic` |
| MCP tools | `https://mcp.tokensaver.fr/mcp` |
| MCP gateway | `https://gateway.tokensaver.fr/mcp` |
| Console / Flux IA | `https://platform.tokensaver.fr/dashboard?tab=flows` |

## Local self-host

```bash
tokensaver route claude --local --with-fs --launch
# or: TOKENSAVER_MODE=local tokensaver route claude --launch
tokensaver doctor --claude --local
```

Defaults: API `:8000`, MCP `:8787`, gateway `:8788`, console `:3000`, optional `HTTPS_PROXY` egress `:8888`.

## Environment

```bash
export TOKENSAVER_API_KEY=ts_…   # required
export TOKENSAVER_CONSOLE_URL=…  # optional
export X-Organisation-ID=…
export X-Workspace-ID=…
```

## Related packages

| PyPI package | Role |
|--------------|------|
| **`tokensaver-cli`** | This package — `tokensaver route` / `doctor` / `status` |
| **`tokensaver-sdk`** | Python API client — `TokenSaver(api_key=…).ask(…)` |

API reference (public): [tokensaver.fr/sdk-api](https://tokensaver.fr/sdk-api)

## Tests

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

## Publishing to PyPI

Maintainers: see **[`docs/PYPI-CLI-RELEASE.md`](../../docs/PYPI-CLI-RELEASE.md)**.

Tag format: **`cli-vX.Y.Z`** (version in `src/tokensaver_cli/__init__.py`).
