kenari CLI

@kenarihq/cli is the official kenari wrapper for using native and kenari models in one Claude Code or Codex session. Plain claude and codex commands remain on their native provider. kenari routes apply only when the tool runs through the wrapper.

Setup overview

Follow these five steps in order.

1. Check prerequisites

node --version

The output must be v18.0.0 or newer (any newer LTS also passes). If Node is not installed, install it from nodejs.org or via your package manager (brew install node, nvm install --lts, and so on).

2. Install the CLI

npm install -g @kenarihq/cli

3. Sign in with kenari login

kenari login

This opens the kenari.id approval page in your browser. After you press Approve access, the CLI receives a new API key through a local callback on 127.0.0.1 and stores it in ~/.kenari/credentials.json (mode 0600 on macOS and Linux). The full key never appears in a browser URL and is never printed to the terminal.

The new key is labeled CLI <hostname> and appears on the dashboard API keys page. You can revoke it at any time like any other key. Requests made with it follow the same billing rules as your other keys.

Options for special situations:

kenari login --no-browser   # print the URL without opening a browser
kenari login --paste        # paste a one-time code, useful over SSH
printf '%s\n' 'kn-...' | kenari login --stdin   # store an existing key

In --paste mode, the approval page shows a one-time code that you paste into the terminal. The code expires in 5 minutes and is useless without the CLI session that requested it.

Verify the connection after login:

kenari status --check

The credential row reads set when ~/.kenari/credentials.json exists and is readable. The connectivity row reads ok when the CLI can call /v1/models with that key.

4. Configure routes with kenari configure

kenari configure

kenari configure asks which tool and roles should route through kenari. When Claude Code and Codex are both installed, the default choice is both. If only one is installed, kenari selects it automatically.

Every role can remain native or use a fixed model with a kenari/<model-id> value. Claude Code has main, opus, sonnet, haiku, fable, and subagents roles. Codex has main, review, and subagents roles. Codex main also supports picker, while review and subagents support inherit.

Non-interactive examples:

kenari configure claude \
  --main native \
  --opus native \
  --sonnet kenari/step-3-7-flash:free \
  --haiku native \
  --fable native \
  --subagents native \
  --yes

kenari configure codex \
  --main picker \
  --review inherit \
  --subagents kenari/step-3-7-flash:free \
  --yes

Unprefixed model IDs always route to the native provider. Values with the kenari/ prefix always route to kenari. The wrapper never falls back between providers.

Verify the configuration:

kenari status

The claude or codex section of the output shows the per-role route that is currently active.

5. Run the wrapper

kenari claude [args...]
kenari codex [args...]

Each launch starts a private router on a random 127.0.0.1 port, starts the original CLI with overrides scoped to that process, forwards terminal input and signals, then stops the router when the process exits. The wrapper does not write provider settings or credentials into Claude Code or Codex configuration.

Verify the connection from inside the wrapper: send the first message to kenari claude. If the CLI reports 401 invalid x-api-key, run kenari status --check to see whether credential is still set. If it reports model_not_found, the model id was typed wrong. Check ids in Models and pricing.

Other commands

kenari status               # show routing configuration offline
kenari status --check       # check routes and connectivity
kenari models               # list models with prices
kenari reset [claude|codex] # remove routes without removing the login
kenari logout               # remove the kenari credential from this machine

kenari reset does not change the tool’s native configuration. kenari logout removes only the kenari credential, so native roles keep working.

Troubleshooting

Symptom	Cause	Fix
command not found: kenari	CLI is not installed, or PATH does not include the npm global prefix	reinstall with npm install -g @kenarihq/cli. Run npm config get prefix and add <prefix>/bin to PATH
kenari status --check shows credential: missing	~/.kenari/credentials.json does not exist	run kenari login again
kenari status --check shows connectivity: failed with 401	key was revoked in the dashboard, or is partially stored	run kenari logout then kenari login
kenari status --check shows connectivity: failed with 402	configured model is paid and balance is Rp 0	switch the role to kenari/step-3-7-flash:free, or add balance
Wrapper hangs after startup	local router collided with another process	close any other running Claude Code or Codex process. The router picks a random port, so collisions only happen between parallel sessions