One window, one project, one key.

Cursor stores your BYOK API key once per profile, not per repo. cursor-keys gives every project its own isolated profile so each window uses the right key, even side by side.

runtime deps 0 node โ‰ฅ18 encrypted set-key any OpenAI-compatible gateway MIT
$ npm install -g cursor-keys

01Register once, open forever

Add a project, clone your main Cursor sign-in and settings, inject the project key once. After that, cursor-keys status is the source of truth.

zsh
$ cursor-keys add acme --path ~/Projects/acme
Profile ready: ~/.cursor-profiles/acme

$ cursor-keys clone acme
$ cursor-keys set-key acme
Key set for acme (encrypted, round-trip verified)

$ cursor-keys status

Project   Color    Windows Key Repo
โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
 acme      #4f8cff  1       yes ~/Projects/acme
 client-b  #845ef7  1       yes ~/Projects/client-b
 client-a  #51cf66  0       no  ~/Projects/client-a

$ cursor-keys doctor acme
  โœ“ OpenAI API key row present
  โœ“ Explore subagent overrides present
  โœ“ Base URL (gateway.example.com/v1) in profile state

02Or let Cursor's agent set it up

No terminal experience needed. Open your project in Cursor, paste this into the agent chat (Cmd+L), and it runs the whole setup. Your API key goes into a hidden terminal prompt, never into the chat.

Set up cursor-keys (github.com/L-ubu/cursor-keys) for this project, step by step:
1. Run `npm install -g cursor-keys`.
2. Run `cursor-keys config baseUrl <your-gateway-url>` (replace with my gateway URL, e.g. https://gateway.example.com/v1).
3. Register this workspace: `cursor-keys add <folder-name> --path <this workspace's path>`.
4. Run `cursor-keys clone <folder-name>` to inherit my Cursor sign-in and settings.
5. Run `cursor-keys set-key <folder-name>` and ask me to paste the project API key at the hidden terminal prompt. Never write the key into files, chat, or logs.
6. Run `cursor-keys doctor <folder-name>` and fix what it flags.
7. Run `cursor-keys aliases --install` and `cursor-keys wrap --install` for the shell extras.
8. Open the project in its profile with `cursor-keys open <folder-name>`, then explain how I can tell it worked.

03What you get

โ—† Isolated profiles

One --user-data-dir per project, the only way Cursor can hold two keys at once. Extensions and MCP config stay shared via symlinks.

โ—† Encrypted key injection

set-key uses Cursor's safeStorage (Chromium OSCrypt) and writes the profile secret store. Round-trip verified, never plaintext in logs.

โ—† Clone your setup

clone copies sign-in, theme, and model config from your main Cursor, scrubs donor secrets (API keys, MCP tokens) from the copy, and prunes the AI chat history tables. Clones stay megabytes, not gigabytes, and no conversation history crosses between projects. New profiles open ready instead of repeating onboarding.

โ—† See the active key

Title bar color per project, a status bar item in every window, and status in the terminal.

โ—† Wrong-window guard

The companion extension detects a repo open in the wrong profile and offers a one-click relaunch into the right one.

โ—† Zero dependencies

Plain Node โ‰ฅ18 and sqlite3, no install scripts, releases signed with npm provenance. Nothing to audit, nothing to break on npm supply-chain day.

04Commands

One binary, three names: cursor-keys, ckeys, and the ck alias from aliases --install.

Command What it does
add <name> Register project and create profile
clone <name> Inherit sign-in, settings, model config from main Cursor
prune [name] Delete AI chat history from profile DBs, reclaim disk space
set-key <name> Inject the project API key, encrypted and verified
color <name> [#hex] Show or set the project title bar color
open [name] Launch Cursor with the profile (auto-detect from cwd)
status / current List projects or show mapping for cwd
config get <key> Print one config value (baseUrl, profilesRoot) for scripts
config baseUrl <URL> Set your OpenAI-compatible gateway endpoint
doctor [name] Health checks: key row, base URL, subagent overrides
wrap --install Plain cursor <path> auto-picks the profile
aliases --install Per-project aliases, the ck shortcut, and zsh tab completion
install-extension Link the status bar indicator and wrong-window guard into Cursor

05Config

Optional. Lives at ~/.config/cursor-keys/config.json. Set baseUrl to your LiteLLM, Vercel AI Gateway, or other OpenAI-compatible endpoint. Writes are atomic and merge-on-save, so overlapping runs never clobber registrations.

{
  "profilesRoot": "~/.cursor-profiles",
  "baseUrl": "https://gateway.example.com/v1",
  "projects": {
    "acme": { "path": "~/Projects/acme", "color": "#4f8cff" }
  }
}

Script-friendly reads: cursor-keys config get baseUrl prints one scalar on stdout.

06Why

Keys are profile-global, work is per-project

No setting, env var, or extension API swaps Cursor's key per folder. Separate profiles are the correct mechanism; cursor-keys makes them automatic.

Billing the wrong client is a silent failure

Colors, a status bar item, and a wrong-window guard turn an invisible mistake into an obvious one before the invoice arrives.

Secrets belong in Cursor's store

Keys are written into Cursor's encrypted secret row, not dotfiles, READMEs, or shell history.