The Pro CLI
polytone — POLYTONEide's verified, token-saving generation loop in your terminal, your scripts, your CI. Part of the Pro subscription: the CLI verifies your Pro key offline and refuses without one. The free toolchain (ptc) stays complete and free — build, test, format and document without a key.
The verified loop, scriptable
polytone gen "<intent>" sends the compiled context slice (the same one ptc context emits) plus the frozen language card, receives a change-set, and verifies it in a scratch copy of your project: every changed module type-checked and its tests run, changed media documents rendered through their codecs. On failure the toolchain's teaching error goes back to the model — up to two repair rounds. Verified means applied; anything else means your files stay untouched and you see the last verdict.
polytone fix needs no intent at all: it runs your checks and tests, and the failing output IS the prompt. With a cheap_model configured, the cheap tier goes first and the strong model sees the task only when the cheap repairs fail — verification is local and free, so a failed cheap attempt costs cheap tokens, never strong ones. The token ledger prints provider-reported usage per run and per tier — and says so explicitly when a provider omitted usage and it had to estimate.
A transient provider failure never sinks a run: an HTTP 429 or 5xx backs off and retries — the IDE's exact policy (up to three attempts, 500 ms doubling to an 8-second ceiling) on both surfaces. A real refusal (a bad key, an unknown model) passes straight through, and the CLI says on stderr why it is waiting.
One subscription, two surfaces
The CLI and the IDE verify the same PTPRO.<payload>.<signature> keys against the same embedded public key — ECDSA P-256, checked offline on your machine. polytone license activate <key> installs it; polytone license exits 0 exactly when Pro is active, so scripts can probe it. No server is in the loop, and expiry (when a key carries one) is enforced only after the signature proves it authentic.
A first-party IDE backend
polytone agent speaks POLYTONEide's "Local agent (CLI)" protocol: the prompt arrives on stdin, the completion leaves on stdout, errors speak on stderr. Pick "Local agent (CLI)" in the IDE's provider settings (a desktop-app backend — a browser tab cannot spawn a process) and set the command to polytone agent — the IDE's loop then generates through the CLI's provider configuration. Perfect integration is a protocol, not a plugin.
BYO key, one card
Providers: Anthropic, OpenAI, and OpenAI-compatible local endpoints (Ollama, LM Studio). Your API key stays on your machine — POLYTONE never resells tokens; we sell the machinery that needs fewer of them. The CLI, the IDE and the public benchmark send ONE frozen language card, byte-identical across all three — the CLI resolves it from the IDE's source at build time, the benchmark harness at run time, and a cross-surface gate pins all of it — so the provider prompt cache is shared everywhere the card travels.
Command reference
| Command | What it does |
|---|---|
polytone gen "<intent>" [--target <file>] [--entry <file>] [--dir <path>] [--max-repairs <n>] | Generate a verified change — only a green change-set touches your files |
polytone fix [--entry <file>] [--dir <path>] [--max-repairs <n>] | Feed the failing check/test output to the model; apply the repaired, verified result |
polytone agent | Prompt on stdin, completion on stdout — the IDE's local-agent protocol |
polytone config [show | path] · set <key> <value> · unset <key> | provider (anthropic | openai | compatible | mock), model, cheap_model (tried first, escalates on failure — cheap tokens, never strong ones), base_url, api_key, max_tokens, mock_file, stream (default true — completions stream with a live progress counter; the code itself is never shown before it verifies) — POLYTONE_API_KEY (or the provider's own variable) overrides the file |
polytone session export [--out <file>] · replay <file> [--dir] [--entry] | Sessions are code: export the ledger as a polytone-session v1 file — the same document the IDE exports — and replay one anywhere: the verified change-sets re-apply and re-verify locally, no model call; only a green final state is written (the IDE hands the replayed set to you instead — the one documented divergence) |
polytone ledger | The local intent ledger: lifetime totals and the per-model split — every gen/fix run records itself at ~/.polytone/ledger.jsonl; local only, never telemetry |
polytone license [activate <key> | remove] | Verify and install a PTPRO key (offline); license alone shows the status, exit 0 = Pro |
polytone card | Print the embedded language card — the exact bytes the IDE and the benchmark harness send (the one-card claim, checkable from a terminal) |
polytone version · polytone help | Version (with the language-card version) and usage |
A first session
polytone license activate PTPRO.… # your Pro key, verified offline
polytone config set model claude-sonnet-5
export POLYTONE_API_KEY=sk-… # or: polytone config set api_key …
ptc new notes && cd notes && ptc test # the free toolchain scaffolds and judges
polytone gen "store notes as JSON and add a word-count command, with tests"
# round 1: asking the model … verified — applied: updated main.pt
# 4 test(s): 4 passed; 0 failed · tokens: 3812 in / 921 out over 1 round(s)Getting the binary
The download page carries polytone-cli-<platform> archives for macOS (Apple Silicon and Intel), Linux, and Windows, built by CI on real runners on every version tag — next to the free toolchain archives, behind the same gate, with checksums in the shared SHA256SUMS.txt. Drop the binary into the unpacked toolchain folder next to ptc — the stdlib/ beside it is found automatically (or set POLYTONE_STDLIB) — then activate your key. Without a valid PTPRO key every generating command (gen, fix, agent, session) refuses and teaches the activation path — license, config, ledger, version, and help stay usable.
Download — polytone-cli archives
Getting a key
The Pro CLI is included in POLYTONEide Pro (≈ 12 € / month, intended price — validated before launch). Until the hosted checkout launches, keys are issued manually. Plans and the measured token numbers live on the POLYTONEide page.