tokensaver-cli 0.3.31

The control plane CLI for AI coding agents

Route Claude Code, Cursor, and Codex through TokenSaver — Zero Trust governance, MCP tools, and Flux IA observability on every run.

Free signup · 15 free models · 600+ model catalog (Pro) · stdlib-only · MCP + Trust Gateway · Python ≥ 3.10

Get started (60s) · Connect (CLI · API · MCP) · What you get · Agent graph · Control plane · Architecture · Agents · Docs · llms.txt

Most coding agents talk to LLM providers directly: no shared audit trail, no inline PII guard, no org-wide FinOps — and every teammate wires MCP by hand.

TokenSaver CLI is the open-source on-ramp to the TokenSaver control plane: one command routes your agent through governed pipelines (cache, compression, RAG, PII, quotas) with full observability in the console.

Platform governance, not a local-only proxy. Policies, RBAC, Agent Registry, and Flux IA live on platform.tokensaver.fr. The CLI configures your laptop; the platform enforces and traces every call.

The CLI is one way in. Same control plane via OpenAI/Anthropic-compatible APIs, Python SDK / REST, MCP tools, or Trust Gateway — see Connect to the control plane (mirrors console Docs → Build / Connect).

Who it's for:

• Developers shipping with Claude Code, Cursor, or Codex who want governance + observability without rewriting agent code
• Platform teams standardizing how agents connect to LLMs (OpenAI-compatible + Anthropic-compatible APIs, MCP tools, Trust Gateway)
• FinOps / security stakeholders who need PII filtering, quotas, and auditable runs — not just cheaper tokens
• Free-plan explorers — tokensaver login creates a workspace and API key in under a minute

Quick Start · Why TokenSaver · Command reference · Contributing

What you get

• 600+ models (Pro/BYOK) — full Agent Registry; Free plan includes 15 hosted models (GLM, DeepSeek, GPT-OSS, Llama, …) with no provider API key → models & Free plan
• tokensaver route claude --launch — Claude settings, MCP tools (mcp.tokensaver.fr), Trust Gateway (gateway.tokensaver.fr), and the tokensaver-router plugin in one shot
• Governed pipelines — cache, compression, PII, RAG, and quotas follow your API key policies (runtime governance, not hard-coded in the CLI)
• Flux IA — tokensaver flows lists recent runs; tokensaver flows --open jumps to the console dashboard
• Business loops (ACP-9) — tokensaver loop start|tick|end|status to govern vibe-coding sessions → vibe-coding-loops.md
• Agent Registry — tokensaver approve / tokensaver use for zero-trust model catalog (fixes 403 on quarantined models)
• MCP slash commands — /tokensaver-router:quota, :flows, :cache, :models, … inside Claude Code
• Clean undo — tokensaver unroute claude restores backed-up config files
• Zero runtime deps — stdlib only; pip install tokensaver-cli and go

Companion library: tokensaver-sdk for POST /pipelines/run, chat sessions, and programmatic API access.

Why TokenSaver

TokenSaver adds a hosted trust layer (governance, registry, observability) while keeping the OSS CLI free and MIT-licensed.

Connect to the control plane

This repository ships the CLI on-ramp. Every path below hits the same SaaS control plane (governance + Flux IA):

Deep dive (OSS): docs/connect-control-plane.md — matrix, recipes, “do not confuse egress vs MCP vs A2A”.
Product Docs: platform.tokensaver.fr → sidebar Docs → Build (choose a path) · Connect (n8n, LangChain, Cowork, …)

# Same control plane without routing an IDE — OpenAI-shaped client
export OPENAI_BASE_URL=https://api.tokensaver.fr/openai/v1
export OPENAI_API_KEY=ts_…
./examples/04-llm-egress.sh    # optional auth check + Flux IA reminder

Architecture

 Claude Code · Cursor · Codex · LangChain · n8n · MCP host · your app
        │           │              │             │
        │ CLI       │ LLM egress   │ SDK/REST    │ MCP A / Gateway
        └───────────┴──────────────┴─────────────┘
                              │
                              ▼
 ┌─────────────────────────────────────────────────────────┐
 │  TokenSaver control plane  (SaaS · EU-ready)            │
 │  Cache → RAG → Compression → PII → LLM → Audit          │
 │  Agent Registry · FinOps · Flux IA                      │
 └─────────────────────────────────────────────────────────┘
        │
        ▼
 LLM providers  (OpenRouter · Anthropic · OpenAI · Mistral · …)

 Optional local helper (this repo):
   tokensaver CLI  →  writes settings / MCP / env for Claude · Cursor · Codex

SaaS endpoints (default after tokensaver login):

Typical pipeline savings on the platform: ~45% fewer tokens (cache + compression + routing) — see tokensaver.fr.

Control plane & live observability

The CLI routes traffic; the TokenSaver control plane shows every governed run in real time.

tokensaver login              # saves ts_… key + workspace_id locally
tokensaver route claude --launch
# send a message in Claude Code, then:
tokensaver flows --open       # Flux IA in the browser (real-time)
tokensaver whoami             # email, plan, workspace id

Use the same email in the browser as tokensaver whoami. In the console sidebar: Flux IA for step-by-step runs, Agentic graph for the multi-agent canvas (as in the demo above).

Docs: Observability (this repo) · Product overview · Console

Get started (60 seconds)

# 1 — Install (stdlib only)
pip install -U tokensaver-cli

# 2 — Free signup or sign-in → ts_… key saved locally
tokensaver login

# 3 — Route Claude Code and launch
tokensaver route claude --launch

# 4 — Verify + open Flux IA
tokensaver doctor --claude
tokensaver flows --open

Credentials: ~/.config/tokensaver/credentials.json (0600).
TOKENSAVER_API_KEY overrides the file when set.

Self-host: append --local on commands (API :8000, MCP :8787/mcp, gateway :8788/mcp).

Agent compatibility

Claude Code flags: --scope user|project|local · --profile cheap|default|strong · --model provider/model · --with-fs · --no-plugin · --local

Undo: tokensaver unroute <claude|cursor|codex|proxy|mcp>

When to use · When to skip

Great fit if you…

• run Claude Code / Cursor daily and want one command to wire MCP + governance
• need Flux IA traces (tool calls, cache, PII steps) without building observability yourself
• want Free-tier exploration with a real control plane, not just a API key passthrough

Skip if you…

• need 100% offline / air-gapped with no SaaS (use --local self-host)
• only want local token compression with no platform
• cannot send prompts through a governed API (strict data residency without self-host)

Command map

Auth           login · logout · whoami · keys list|create|revoke
Models         models · use · profiles · approve · catalog
Observability  flows · loop · status
Route          route <claude|cursor|codex|proxy|mcp> · unroute …
Health         doctor [--claude] [--local]

export TOKENSAVER_API_KEY=ts_…
export TOKENSAVER_MODE=local          # or --local on commands
export TOKENSAVER_API_URL=http://localhost:8000
export TOKENSAVER_MCP_URL=http://localhost:8787/mcp
export TOKENSAVER_GATEWAY_URL=http://localhost:8788/mcp
# Optional override — otherwise local mode reads CONSOLE_BASE_URL or apps/console/.env.local PORT
export TOKENSAVER_CONSOLE_URL=http://localhost:7337
export TOKENSAVER_NO_BANNER=1         # hide ASCII banner on CLI start

Documentation

Examples (shell):

./examples/01-login-and-route.sh      # SaaS login + route
./examples/02-local-selfhost.sh       # localhost stack
./examples/03-glm-open-model.sh       # Free plan + GLM 4.7 Flash
./examples/04-llm-egress.sh           # OpenAI-compatible egress (no IDE route)
LAUNCH_CLAUDE=1 ./examples/03-glm-open-model.sh   # also launch claude

AI agents / LLMs: read llms.txt in this repo for a compact index.

TokenSaver for teams

The OSS CLI is built for individual developers: install, login, route your agent in minutes — free and MIT-licensed.

Running org-wide governance, SSO, centralized policies, and fleet FinOps across every team is what platform.tokensaver.fr and tokensaver.fr enterprise plans are for.

→ Request a demo · Early Adopter program

Contributing

Issues and stars welcome on this repo. Source of truth for releases is the private monorepo; this repository is a public mirror synced via scripts/sync-oss-cli.sh.

Releases: push packages/cli to main → CI auto-bumps patch (if needed), syncs the mirror, creates GitHub Release + PyPI. No manual version step.

See CONTRIBUTING.md · SECURITY.md · CHANGELOG.md

git clone https://github.com/tokensaver-ai/tokensaver-cli.git
cd tokensaver-cli
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]" && pytest -q

License

MIT — see LICENSE.