Skip to main content
Install the CLI and run valar setup: it logs you in to get a coding key, applies your organization’s settings, and connects your tools. The sections below show how to run each step yourself. On macOS and Windows 11, Claude Code, Claude Desktop and Cursor can share the optional on-device proxy. On Linux, Claude Code and Cursor can share it.

Prerequisites

  • One of the supported harnesses installed locally: Claude Code, the Claude Desktop app, Cursor, Codex, Pi, Oh My Pi, or VS Code (via GitHub Copilot Chat).
  • An account on the Valar Dashboard, where your coding key is created.
  • macOS, Linux, or WSL for the CLI; on Windows 11, Claude Code, Claude Desktop, Cursor and Codex.

Install the CLI

Install the valar CLI, a single binary with no runtime dependencies:
On Windows, from PowerShell:
At a terminal, the installer then runs valar setup. Set VALAR_NO_SETUP=1 to install only. Confirm it is on your path:

Set up in one command

valar setup logs you in, sets up the on-device proxy and quota-first as your organization’s settings say, and turns on your tools: the ones you name with --tools, or the ones you check in the list it shows. It stops at the first step that fails and names it. Fix the cause and run valar setup again. With no terminal, name the tools with --tools, provide a coding key in VALAR_API_KEY, and add --force to let it restart open apps. To run it from MDM, see Roll out with MDM.

Log in

valar login opens the Valar Dashboard in your browser. Sign in if asked, then click Create key and connect. The dashboard creates a coding key for this computer and hands it to the CLI, which checks the key with Valar and stores it in ~/.valar/config.json. There is nothing to copy or paste. You can also skip straight to connecting a harness: any valar command that needs a key and has none, such as valar claude on, opens the same page. Coding keys are scoped to agentic harnesses like Claude Code, Cursor, Codex, and Pi, and they carry your routing split. They use the vlrcode_ prefix. A key created by valar login is named valar CLI on <hostname> and is listed under API Keys in the dashboard with the Coding type, where you can rename or revoke it. The login page lets you choose when the key expires (30 days, 90 days, 1 year, or never); when a stored key has expired, the next valar command says so and logs in again. Each login creates a new key. If a key is already stored, valar login asks before replacing it (--force replaces it without asking), then tells you where to revoke the old one, which keeps working until you do.
A new key works right away. Until you set a split, it routes on Auto — Valar picks the target model — so it is safe to connect before you have tuned anything. It starts on your organization’s default strategy, Balanced unless an admin picked another under Settings > ValarCode settings > Default routing for new keys. See Model routing.

Without a browser

Over SSH, on a machine with no browser, or if your role cannot create keys, get a coding key from the Valar Dashboard under API Keys — choose the Coding type when creating it — (or from an admin) and store it. The token is shown once, so copy it before you leave the page. An inference key does not work here: the CLI refuses it before writing anything.
The key is resolved from, in order: --api-key, then $VALAR_API_KEY, then ~/.valar/config.json, then browser login. Where no browser can open, the CLI asks you to paste a key instead.

Connect a harness

Connect each harness from your own user account. Choose its guide for setup and restart requirements:

Claude Code

valar claude on

Claude Desktop

valar claude-desktop on

Cursor

valar cursor on

Codex

valar codex on

opencode

valar opencode on

Pi

valar pi on

Oh My Pi

valar ohmypi on

VS Code

valar copilot on
Routing Cursor requires a paid Cursor plan (Pro, Business, or Enterprise) — valar cursor on fails on the free plan or when Cursor is not signed in. valar cursor routes the Cursor editor (the desktop app) on macOS, Windows and Linux. On macOS and Linux it uses the on-device proxy when one is set up with valar proxy enable (Cursor 3.21.16 or newer); without it, Cursor is connected directly. On Windows, Cursor always uses the proxy, so run valar proxy enable first. The Cursor CLI (cursor-agent) is not supported. VS Code routing goes through GitHub Copilot Chat’s custom-endpoint provider, so it needs a signed-in Copilot and a recent VS Code. valar vscode and valar copilot are the same command.

On-device proxy

Provision the shared proxy once on macOS, Windows 11 or Linux, then enable each supported harness. Claude Code and Desktop retain their native login and can use subscription-first routing:
Enable only the apps you use. On macOS, proxy setup requests administrator access. On Windows it needs none; Windows asks you to confirm the local certificate instead. On Linux, proxy setup asks for administrator access once, to trust its certificate. Claude Desktop is not supported on Linux yet, so there you enable Claude Code and Cursor. Setup does not turn either app on by itself. Each app has its own ON/OFF control. Without a usable proxy, Claude Code uses direct routing; Desktop uses a direct provider profile when no proxy is provisioned. You can also select direct routing with --direct. See On-device proxy for setup, quota-first, and corporate networks. To deploy with MDM, see Roll out with MDM. The proxy runs on macOS, Windows 11 and Linux. On Linux, see On Linux for what it needs.

Per-engineer attribution

To attribute usage to each engineer, the CLI attaches a client id to every request. Most harnesses (Claude Code, Claude Desktop, Codex, Pi, Oh My Pi, and VS Code/Copilot) send it as an X-Valar-Client-Id header; Cursor, which cannot set custom headers, rides it as a token suffix (<coding-key>~<client-id>). By default the client id is your OS username (normalized to lowercase a-z 0-9 . _ - @ +, capped at 64 characters), so the analytics leaderboard shows real engineers rather than opaque strings. Change how it is derived with --user-id: The chosen id is recorded on on, so you can print it any time:
A plain key with no client id still works, but those requests are not attributed to an engineer. The client id is supplied by the client and is used only for attribution and routing. It is not a security boundary; access is gated on the coding key itself.

CLI reference

The CLI follows a harness-first grammar. A bare harness command normally means on, so valar claude is the same as valar claude on. Claude Desktop is the exception: valar claude-desktop prints help; include on, off, or status.
Harness names are claude, claude-desktop, cursor, codex, pi, ohmypi, opencode, and copilot. vscode is an alias for copilot. valar setup sets up the whole machine (see Set up in one command). valar on lists the tools on this computer that valar <tool> on can turn on, where you check the ones to turn on and uncheck the ones to turn off; a tool installed but never opened is named under the list until you open it once. With --tools it turns the named ones on without asking. valar status summarizes them; valar off attempts to turn off all configured harnesses; valar off --proxy also removes the on-device proxy and fails while anything still routes to Valar. valar update is an alias for valar upgrade. Per-harness commands Flags

Keeping the CLI current

--check reports available updates without installing them or migrating configuration. upgrade verifies the download’s SHA256, replaces the CLI, and completes required configuration and service updates. Run it from your own terminal session, without adding sudo. If migration must refresh running Claude Code sessions, the upgrade asks before interrupting them. Use valar upgrade --force only when that interruption is acceptable. Saved conversations remain available; interrupted requests and tools are not replayed automatically. Follow any instructions to reopen claude agents or resume an interactive conversation. An older Claude setup moves to the proxy lane when the machine can support it, otherwise to direct routing. A saved quota-first preference remains saved, but direct requests use Valar without the Claude subscription. Installing the proxy is a separate step that may require administrator access on macOS.

If an upgrade does not complete

Read the full error to see whether installation failed or the new CLI could not finish updating configuration or services. Keep the recovery records and address the reported cause before retrying. valar upgrade checks for a newer repair first; repeating the same error without a fix will not help. Do not install an older CLI over partially migrated configuration. If you need to stop routing, use the harness’s off command when the CLI says that recovery path is available, and restart affected sessions as instructed. Unknown or unreadable configurations can require repair before OFF is safe.

Automatic update notices

Interactive commands can offer an upgrade before continuing; non-interactive commands print a notice. The check is cached for up to a day. Set VALAR_NO_UPDATE_CHECK=1 to disable these notices.

Deprecated options

proxy enable --force, --no-restart, and --off are deprecated no-ops with warnings. Use harness commands to change routing and approve session restarts.

Managing keys

  • Revoke a coding key from the dashboard at any time. Requests using it stop resolving.
  • Issue a separate key per team or experiment to run different splits side by side. Each key can have its own routing policy.

Next steps

Model routing

Set the split and choose target models.

Analytics & savings

Watch usage and savings come in per engineer.