@tokenite/cli

Agent-first CLI for Tokenite. A thin shell over @tokenite/sdk/admin plus a few composed debug primitives. Designed so an AI coding agent can drive a partner's integration end-to-end without reading their code.

Two consumers in one package:

• Binary: tk (alias tokenite). Distributed in bin/.
• Library: import { ... } from '@tokenite/cli' for embedding in scripts.

Install

pnpm add -g @tokenite/cli
# or per-project
pnpm add @tokenite/cli

Auth

tk auth login                                               # default: loopback OAuth (browser)
tk auth login --email [email protected] --password ...        # password flow (avoid in agent transcripts)
tk auth login --token <existing-pat>                        # use an existing PAT (best for CI)
tk auth status --json                                       # who am I, what's the active context
tk auth token                                               # print the active PAT to stdout (pipe-friendly)
tk auth logout                                              # forget stored credentials

The default tk auth login opens your browser to the dashboard's /cli-login page, captures the redirect on a loopback HTTP server, and stores the minted PAT — no password ever touches argv.

Credential precedence: TOKENITE_TOKEN env var > stored file (~/.tokenite/credentials.json). Override the host with TOKENITE_BASE_URL or --base-url.

Resource verbs

Every resource follows the same shape (ls / view / create / edit / rm where applicable), every command supports --json for machine-readable output, and every destructive verb requires --yes.

tk app ls --json
tk app create --name "My App" --callback-url https://my.app/cb --required-providers anthropic --json
tk app view <id-or-name> --json
tk app edit <id> --description 'updated'
tk app rotate-secret <id> --yes --json
tk app rm <id> --yes

tk key add anthropic --key-file ./anthropic.key
tk key ls --json
tk key rm <id> --yes

tk conn ls --json
tk conn suspend <id> --yes
tk conn resume <id>
tk conn revoke <id> --yes
tk conn set-budget <id> 50

tk spend ls --since 24h --json
tk spend ls --app <id> --from 2026-04-01T00:00:00Z

tk pat ls --json
tk pat create --name ci --password ...    # password required (server enforces fresh JWT)
tk pat rm <id> --yes

tk account ls --json
tk account create --name "Acme"
tk account edit <id> --pool-budget-limit 500 --pool-reset-period monthly

tk member ls --account <id>
tk member invite [email protected] --role member --account <id>
tk member update <userId> --cap 100 --account <id>
tk member rm <userId> --yes --account <id>

tk invite ls --account <id>
tk invite cancel <invitationId> --yes --account <id>
tk invite accept <claim-token>

tk context use <accountId>           # writes to ~/.tokenite/config.json
tk context current
tk context clear

Debug primitives

tk inspect <accessToken> --json                    # complete debug picture for one access token
tk call anthropic /v1/messages \
   --as <accessToken> \
   -d '{"model":"claude-haiku-4-5","max_tokens":50,"messages":[{"role":"user","content":"ping"}]}' \
   --json                                          # synthetic proxy probe
tk doctor --json                                   # reachability, auth, proxy, keys
tk events ls --since 1h --json                     # historical events
tk events ls --type proxy.error --json             # only errors
tk events view <eventId> --json                    # single event detail
tk events tail --app <id> --json                   # live SSE stream — pipe to jq
tk replay <eventId> --as <accessToken> -d '{...}'  # re-run a logged event with fresh body + token
tk api GET /api/apps --json                        # raw REST passthrough
tk schema --json                                   # full command tree (for agent self-briefing)

Library usage

import {
  createCliClient,
  inspectAccessToken,
  runDoctor,
  listEvents,
  tailEvents,
  loopbackLogin,
} from '@tokenite/cli';

const client = await createCliClient();
const apps = await client.admin.apps.list();
const dump = await inspectAccessToken(client, accessToken);
const health = await runDoctor(client);
const recent = await listEvents(client, { type: 'proxy.error' as const, limit: 50 });

await tailEvents(client, {
  appId: 'app-id',
  onEvent: (event) => console.log(event),
});

const credentials = await loopbackLogin({ baseUrl: 'https://api.tokenite.ai' });

Exit codes

| Code | Meaning | |---|---| | 0 | Success | | 2 | Usage error | | 41 | Auth required or expired | | 42 | No active account context | | 44 | Resource not found | | 45 | Conflict | | 50 | Network error | | 51 | Server error (5xx) | | 60 | Budget exceeded | | 61 | Provider error (upstream LLM) | | 70 | Unknown |

Distinct codes per failure class so agents can branch correctly without parsing stderr.

Output discipline

• Stdout is data only. JSON when --json, table otherwise.
• Stderr carries chatter (warnings, the human-readable error envelope).
• All destructive verbs require --yes. There are no interactive prompts.

Environment

| Var | Effect | |---|---| | TOKENITE_TOKEN | Use this PAT (highest precedence) | | TOKENITE_BASE_URL | Dashboard host override | | TOKENITE_ACCOUNT_ID | Active account scope | | TOKENITE_CONFIG_DIR | Override ~/.tokenite/ (used by tests) |