Skip to content
LUNAROUTEDocs

CLI

@lunaroute/cli configures the coding harness you already use to route through LunaRoute, and gives you the catalog, pricing, and usage from your terminal.

Install

Section titled “Install”
Terminal window
npm install -g @lunaroute/cli

Requires Node.js 20+.

Windows (PowerShell, 5.1-safe). No sudo is involved: global installs land in %APPDATA%\npm, which is user-writable. npx ships with npm, and two failures have specific causes:

Symptom Cause and fix
npx is not recognized Node is absent or off PATH. If Node is installed, open a new window first — PATH is read when a process starts.
npx.ps1 cannot be loaded because running scripts is disabled The default Restricted execution policy. Fix with Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser, or use npx.cmd for a one-off — the policy governs .ps1 script files, not .cmd batches. Where Group Policy overrides the user scope, use -Scope Process for that window only.

The same policy blocks the installed shim: after npm install -g @lunaroute/cli, lunaroute.ps1 fails the same way and lunaroute.cmd works.

WSL is a separate environment, not an alternative. Windows user variables do not cross into a distribution without WSLENV, and the npm/Node install is per side — install Node and the CLI inside the distribution for Linux-side work. Credentials are per side too: lunaroute login stores the key under ~/.config/lunaroute, so a login in PowerShell is invisible inside the distribution, and lunaroute run there fails with Not logged in until you log in again. A distro without Node can also resolve the Windows npx through interop PATH, which is confusing to debug.

Setup

Section titled “Setup”
Terminal window
lunaroute setup pi        # or: claude-code | claude-desktop | codex | opencode | openclaw | hermes | copilot-cli | dsh | zed | agy | generic

setup asks before writing. Where an extension exists (pi, opencode) it offers to install it — models then sync automatically and you sign in inside the harness. Otherwise it offers to run lunaroute login (opens your browser) before writing a config.

Already have a key?

Terminal window
lunaroute setup pi --key lr_… --yes

Flags: --extension / --models pick a flow, --yes accepts all prompts, --print previews without writing.

DeepSeek Harness (dsh) merges an llm-pi-ai provider into ~/.dsh/profiles/web/cordis.patch.yml (or $DSH_HOME), carrying model metadata from /v1/models. The patch hot-reloads, so a running dsh web picks up lunaroute/* models without a restart.

Run a session

Section titled “Run a session”
Terminal window
lunaroute run claude-code   # or: codex | zed | agy (`claude` is an alias for `claude-code`)

Starts the harness wired to LunaRoute for that session only. It sets the environment for the child process — and, for Codex, passes the provider as -c command-line overrides — so it writes no configuration and leaves your ~/.claude/, ~/.claude.json and ~/.codex/ files alone. Quit, and your previous setup is what runs next time. That makes it the cheapest way to try LunaRoute before changing anything:

  • --model <id> picks a model from the catalog (default: the first chat model).
  • Everything after -- passes through to the harness: lunaroute run codex -- --resume.
  • It uses your stored login, so run lunaroute login first; a LUNAROUTE_API_KEY in the environment is not enough for run, which errors with Not logged in.
  • claude and claude-code are the same command (one adapter, no behavioural difference).
  • lunaroute run zed launches Zed with LUNAROUTE_API_KEY injected into its environment (it finds the Zed binary itself). The provider block still comes from lunaroute setup zed; quit a running Zed first, since an env var only reaches a new process. Zed picks its model in the agent panel, so --model is ignored.
  • lunaroute run agy launches Antigravity CLI (Gemini CLI’s successor) through its gateway environment variables — AGY_LLM_GATEWAY_URL and AGY_LLM_GATEWAY_API_KEY — and writes nothing to ~/.gemini/antigravity-cli. agy reads its model list from LunaRoute’s catalog, so any catalog model works with --model. lunaroute setup agy prints the same two exports for your shell profile if you would rather run a bare agy.

Per-harness walkthroughs: Claude Code and Codex.

Catalog, pricing, usage

Section titled “Catalog, pricing, usage”
Terminal window
lunaroute models
lunaroute pricing
lunaroute usage

Running a personal agent (OpenClaw, Hermes, NanoClaw)? See Personal assistants.

Accounts

Section titled “Accounts”
Terminal window
lunaroute login     # authorize this device and store a key
lunaroute whoami    # signed-in user and organization
lunaroute key       # print stored key (for $() / export)
lunaroute api-key show              # same as "lunaroute key"
lunaroute api-key show --name my-key # prompt new key with name if revoked/missing
lunaroute logout    # remove stored credentials

lunaroute key and lunaroute api-key show print the same stored lr_… key — multiple show calls reuse it, they do not mint new keys. If run in a TTY and the stored key is revoked (401), api-key show prompts to generate a new one (--name sets the label, same as the dashboard’s key name, --yes accepts non-interactively). Non-TTY/piped usage prints the stored key without checking validity (fast, offline-safe; use api-key show --yes in CI to opt into the check).

All commands accept --profile <name> for multiple credential profiles; models, pricing, and usage accept --json.

LunaRoute documentation