Metadata-Version: 2.4
Name: tokenroute
Version: 0.2.0
Summary: Agent-first CLI for tokenroute — OpenAI-compatible LLM gateway with smart routing and transparent billing
Project-URL: Homepage, https://tokenroute.io
Project-URL: Documentation, https://docs.tokenroute.io
Project-URL: Repository, https://github.com/jiangjin11/tokenroute
Author: Paradigx Pte Ltd
License: MIT
Keywords: agent,ai,anthropic,cli,gateway,llm,openai
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28
Requires-Dist: paradigx-cli-core<0.2,>=0.1
Requires-Dist: typer<1.0,>=0.15
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.14; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Description-Content-Type: text/markdown

# tokenroute (Python CLI)

Agent-first CLI for [tokenroute](https://tokenroute.io) — the OpenAI-compatible LLM API gateway with smart routing and transparent token billing.

## Install

```bash
pip install tokenroute
# or, run once without installing:
uvx tokenroute --help
pipx run tokenroute --help
```

## Quickstart

```bash
tokenroute login                                 # OAuth device-flow, opens browser
tokenroute whoami                                # current user + balance
tokenroute keys create --name my-app             # create new sk-tr-* key
tokenroute balance                               # current credit
```

All commands accept `--json` (or env `TOKENROUTE_JSON=1`) for machine-parseable output that's friendly to agents and CI.

## Agent / sub-agent usage (no interactive login)

For automation, skip `tokenroute login` and call the OpenAI-compatible API directly with a pre-issued key:

```bash
export TOKENROUTE_API_KEY=sk-tr-...
curl https://api.tokenroute.io/v1/chat/completions \
  -H "Authorization: Bearer $TOKENROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'
```

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `TOKENROUTE_API_URL` | `https://api.tokenroute.io` | Override gateway base URL |
| `TOKENROUTE_API_KEY` | _(unset)_ | sk-tr-* key for LLM calls — skips `login` |
| `TOKENROUTE_JSON` | _(unset)_ | Set to `1` to force JSON output globally |

Credentials from `tokenroute login` are stored at `~/.paradigx/auth.json`
(owner-readable only on POSIX) — **shared** with other Paradigx CLIs (e.g.
`botu`) and **auto-refreshed**, so `login` is a one-time step per machine.
Upgrading from 0.1.x migrates the old `~/.tokenroute/credentials.json`
automatically on first run.

## License

MIT
