Connect CLI

tokenharbor is a tiny command-line tool that points the AI coding agents you already use at the Token Harbor gateway — one key, every model.

What it does depends on the agent, and the table below says which is which:

• Auto — it edits that agent's own config file, after copying the file aside. disconnect puts those values back.
• Env — it sets the shared OPENAI_* / ANTHROPIC_* variables and writes no file. disconnect removes the variables.
• Guided — it prints the exact Base URL and key and you paste them into the app yourself. Nothing is written on your behalf, so nothing is undone on your behalf either: what you typed into a GUI or a YAML file is yours to remove.
• Unsupported — the client's current official interface does not expose a safe arbitrary OpenAI-compatible gateway. The CLI explains that limitation and does not ask you to paste a key into a field that is not supported.

So "undo" means undo what the CLI wrote — never a promise to reach into settings it never touched.

Install

One command. Nothing to install first — if your machine doesn't have Node.js, a private copy is provisioned automatically into ~/.tokenharbor (your system is never touched).

macOS / Linux

curl -fsSL https://tokenharbor.ai/connect.sh | sh

Windows (PowerShell)

irm https://tokenharbor.ai/connect.ps1 | iex

New to the terminal? On a Mac press <kbd>⌘ Space</kbd>, type "Terminal", hit Enter, then paste the command. On Windows, search "PowerShell".

After installing, the interactive menu opens automatically. Later, just run tokenharbor in any new terminal to get it back.

The menu

[1] Connect ALL detected agents
[2] Pick agents one by one
[3] Restore previous configs (undo everything, from backup)
[4] Status & diagnosis
[5] Change API key
[q] Quit

• [1] / [2] ask for your API key once (get one at /dashboard/api-keys — free account works), verify it, then configure the agents.
• [3] undoes what the CLI wrote: Auto agents' config values go back to what they held before, and the Env variables are removed. A setting you changed yourself after connecting is left alone and reported rather than reverted out from under you, and Guided apps are not touched at all — the CLI never wrote to them. Previous values are recorded at connect time and a one-time <file>.th-backup copy sits next to every file we do write.
• [5] swaps in a new key and re-applies it to everything already connected.

Supported agents

The automatic adapters for Codex, opencode, OpenClaw, Qwen Code, and pi are exercised by an installed-client compatibility job; pi is checked against both its legacy and current package lines, including Windows. Claude Code has also been request-tested locally, while CI checks its generated settings and installed binary version separately. Pull requests run the matrix and a schedule repeats it weekly against current releases. Guided entries are based on each client's linked official setup format and remain labeled Guided because their GUI or server installation cannot be rewritten and runtime-tested safely from this CLI.

Guided agents keep their API settings inside app-internal storage that no external tool can safely write — the CLI prints the exact two values to paste (including your actual key), which takes about 30 seconds.

Most other terminal tools work automatically through the universal environment (OPENAI_* / ANTHROPIC_* variables, loaded by new terminals).

Commands

Flags for scripting: --yes (non-interactive), --skip-verify (behind proxies), --no-env (agent configs only), --env-all (also override an existing OPENAI_API_KEY / ANTHROPIC_*).

Passing the key without leaking it

Give the key on stdin or the environment, never as a command-line argument. An argument is written to your shell history and is visible to any other process on the machine via ps:

# good — read from the environment
export TOKENHARBOR_API_KEY="$(cat ~/.th-key)"
tokenharbor connect --yes

# also good — interactive prompt, nothing is echoed or recorded
tokenharbor connect

Safety

• Reversible. disconnect (or menu [3]) restores the values that were there before — not just deletion. If you changed one of those settings yourself after connecting, that edit is left alone and reported, rather than being reverted out from under you.
• Non-destructive. A config file that fails to parse is never modified; every file we do touch gets a one-time .th-backup copy first. If that backup cannot be written, the change is abandoned rather than made unprotected.
• No hijacking. If you already export your own OPENAI_API_KEY, the CLI leaves that variable group untouched by default so your other scripts keep billing where they did.
• Where the key goes. ~/.tokenharbor/config.json (created mode 0600, written atomically), each configured agent's own config file, and — so agents that only read the environment can find it — OPENAI_API_KEY / ANTHROPIC_AUTH_TOKEN in your shell profile, or your Windows user environment. It is never sent anywhere except the Token Harbor gateway.
• Verified, not trusted. The installer pins a Node version and checks it against nodejs.org's published SHA-256; the CLI archive is checked against /cli/manifest.json before anything is extracted or run. Both are staged and swapped in, so a failed install leaves your existing one working.

Troubleshooting

• "Could not reach the gateway" but your network is fine — corporate/VPN proxies: Node's fetch ignores HTTP_PROXY, so verification can false-negative. Answer y to "Configure anyway", or use --skip-verify.
• "That doesn't look like a Token Harbor key" — keys start with thk_. An OpenAI sk-… key won't work here; create one at /dashboard/api-keys.
• Agent doesn't pick up the change — open a new terminal (the environment loads on shell start), or restart the editor for GUI agents.

Uninstall

One command does all of it — reverts every agent, removes the shell hook, takes ~/.tokenharbor/bin back off your PATH (in every shell profile it might have been added to, not just your current one), and deletes ~/.tokenharbor including the stored key:

tokenharbor uninstall

Open a new terminal afterwards for the PATH change to take effect.

disconnect is the smaller version: it reverts the agents but leaves the CLI installed.