โโโโโโโโโโ โโโโโโโโโโ โโโโโโโโ โโโโโโโ โโโโโโโ โโโ โโโโโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโ โโโ โโโ โโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโ โโโโโโ โโโโโโโ โโโโโโโโ โโโ โโโ โโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโ โโโโโโ โโโโโ โโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโ โโโ โโโ โโโโโโโโโโโ โโโ โโโโโโโโ โโโโโโโ โโโโโโโ โโโ โโโโโโโโโโโ โโโโโโโ โโโ โโโ โโโ โโโโโโโโโโโ โโโ โโโโโโโโ
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.
$ npm install -g cursor-keys
GitHubยท Quick startยท Agent setupยท Featuresยท Commandsยท Configยท All tools
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.
$ 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
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.
One --user-data-dir per project, the only way Cursor
can hold two keys at once. Extensions and MCP config stay shared
via symlinks.
set-key uses Cursor's safeStorage (Chromium OSCrypt)
and writes the profile secret store. Round-trip verified, never
plaintext in logs.
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.
Title bar color per project, a status bar item in every window,
and
status in the terminal.
The companion extension detects a repo open in the wrong profile and offers a one-click relaunch into the right one.
Plain Node โฅ18 and sqlite3, no install scripts, releases signed with npm provenance. Nothing to audit, nothing to break on npm supply-chain day.
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 |
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.
No setting, env var, or extension API swaps Cursor's key per folder. Separate profiles are the correct mechanism; cursor-keys makes them automatic.
Colors, a status bar item, and a wrong-window guard turn an invisible mistake into an obvious one before the invoice arrives.
Keys are written into Cursor's encrypted secret row, not dotfiles, READMEs, or shell history.