OurToken CLI

Install

The public package is named ourtoken and requires Node.js 20 or newer.

npx ourtoken --version
npx ourtoken login

login starts a device authorization instead of a localhost callback. It prints a short approval code, opens /cli/activate, and waits for your signed-in browser to approve or deny it. The terminal creates an ephemeral RSA key pair; the service stores only hashes plus a short-lived encrypted key payload, so the plaintext Installation Key is delivered only to that terminal.

The first successful login creates one dedicated, revocable Installation Key for that local installation. A later ourtoken login reuses the protected local key after checking it with the service. Use ourtoken login --force to rotate it; the old key is revoked only after the replacement has been installed successfully.

For staging or a self-hosted deployment, pass an explicit API origin:

ourtoken login --api-url https://api.staging.ourtoken.dev

Managed clients and models

During login, the CLI detects Codex and Claude Code, fetches server-recommended Client-Compatible Models, then asks which client/model pairs to activate. It creates the reserved ourtoken profile only for selections you confirm.

Current compatibility targets are Codex CLI 0.142.5 using the OpenAI Responses API and Claude Code 2.1.197 using the Anthropic Messages API. A client version is considered supported only after its exact staging trace passes. Codex's non-function hosted-tool descriptors are deliberately omitted; standard function tools and their result loops are preserved.

The CLI changes only these fields:

The CLI never reads or rewrites Codex's auth.json; its native OAuth/session records remain byte-for-byte intact. Its protected ~/.ourtoken/bin/codex-auth.mjs helper reads only the active profile's credential from protected local state and writes that credential only to Codex's child-process stdout. Hooks, MCP settings, unrelated environment variables, and other configuration remain intact. Switching to system-default removes only the OurToken-managed fields and restores what was present before the first switch.

Commands

ourtoken login [--force] [--api-url URL] [--no-browser]
ourtoken logout [--revoke]
ourtoken usage [--month YYYY-MM] [--json]

ourtoken codex|cx add|list|use|current|edit|remove|clone
ourtoken claude|cc add|list|use|current|edit|remove|clone

ourtoken usage returns only settlement totals for the calling Installation Key: UTC-month request count, input/cached/output tokens, customer spend, per-model breakdown, and customer-safe wallet availability. It never returns prompts, responses, provider routes, internal costs, or activity for other keys.

logout restores active ourtoken profiles to system-default and removes local login state. It leaves the server-side key active by default so an accidental local cleanup does not revoke a working installation. Use ourtoken logout --revoke when the device is retired or compromised.

Profiles

Each client has a read-only system-default profile plus named profiles you manage:

ourtoken codex list
ourtoken codex add work --provider relay --base-url https://relay.example/v1 --model openai/gpt-5 --credential-ref work-key
ourtoken codex use work
ourtoken codex current
ourtoken codex clone work review
ourtoken codex edit review --model openai/gpt-5-mini
ourtoken codex use system-default
ourtoken codex remove review

claude and cc accept the same subcommands. A profile records a provider name, base URL, optional model, and credential reference; the secret itself is held only in protected local state. To pipe a credential from a password manager, use:

security find-generic-password -w -s relay-key | ourtoken codex add work \
  --provider relay --base-url https://relay.example/v1 --credential-ref relay-key --credential-stdin

Do not put a credential after --credential-ref; command histories and process lists are not secret storage.

Local security and recovery

Protected state lives under ~/.ourtoken: directory mode 0700 and secret file mode 0600 on macOS/Linux, or a verified owner-only ACL on Windows. The CLI fails closed if it encounters an insecure state file or any symbolic-link target.

Every mutation first creates an exact protected transaction backup, acquires a per-tool lock, writes atomically, and rolls back the whole transaction after a partial failure. The latest ten successful transactions are retained under ~/.ourtoken/backups. If you need recovery, stop all OurToken CLI invocations, inspect the newest backup manifest, restore only the named client files, then run ourtoken codex current or ourtoken claude current to confirm the desired profile.

If the CLI reports managed-field drift, someone changed a field that OurToken owns outside the CLI. Review the current config and backup first; use --force only when you intentionally want the selected profile to replace that drift.