Setup and troubleshooting

Most installations need npx orbitmap init only once. These are the cases worth remembering.

"command not found: npx"

Your computer doesn't have Node.js yet; setup needs version 18 or newer.

Download the LTS installer from nodejs.org/en/download and run it.
Close the terminal and open a new one; the old window doesn't see Node yet.
Type node -v: you should see v18 or higher. Then run npx orbitmap init again.

Find your API key

The key belongs to your agent. In the app: Settings → Agents & API keys → your agent → Manage API Key → Reveal Key. The same key works for the CLI and the Agent API. A legacy key cannot be revealed, only regenerated; rerun init with the new key.

Run `init` again

Rerun npx orbitmap init to map a skipped folder or refresh setup after a CLI upgrade. It merges the local connection, updates the Orbitmap instructions in place and keeps workspace data on the server. It writes connection metadata under .orbitmap/, stores the key outside the repository and may update agent configuration and .gitignore. It never uploads source code; review its list of changes before confirming.

With another account's key, the folder is reconnected to that key's workspace and its areas are rebuilt for it. A run that ends without an area says why, starting No area was created for <folder>.

Connect another project

Run npx orbitmap init in the other repository or folder and choose the workspace. A key saved on this computer is offered first (see Getting started); pass --key to use a different one. For several repositories, run it in each or in their common parent (see How work is organized).

New workspace from the terminal

When the key's agent may create workspaces, the workspace question offers Create a new workspace, the default when the folder is outside every connected workspace. You type its name; nothing is created until you confirm. In a script: npx orbitmap init --key <key> --new-workspace <name>.

This needs an agent set to all workspaces, as the onboarding agent already is. For another agent, open Settings → Agents & API keys, edit it and choose All workspaces, including new ones (available when its owner is an administrator).

Switch Orbitmap off for one folder

npx orbitmap off keeps Orbitmap installed but switches it off in this folder, such as a scratch or client repository. It adds a short note to the folder's CLAUDE.md and AGENTS.md and marks the folder, so orbitmap commands in it and its subfolders stop and point to orbitmap on. npx orbitmap on removes both. Running init in a switched-off folder first asks whether to turn it back on.

Check the connection

When the app says the machine is connected but the agent cannot find the workspace or area, run npx orbitmap context from the connected folder. It prints the agent, workspace and area the session sees. If it cannot resolve them, check that .orbitmap/config.json exists where init ran, then rerun init.

Refresh the agent instructions

init installs the Orbitmap skills for Claude Code and Codex, globally or in this project. npx orbitmap setup-agent reinstalls them, for example after installing Codex, keeping the connection and key. Codex skills go to $CODEX_HOME when set, otherwise ~/.codex. Codex only runs hooks you have trusted: open /hooks in Codex and trust orbitmap emit-instructions.

Cursor reads these skills locally. For Cursor Cloud Agents, run npx orbitmap setup-agent --agent cursor and turn on Cursor's Sync Skills, or add --scope project and commit .cursor/.

"Codex not found"

Setup prints Codex not found when this computer has Claude Code but no Codex. The Codex skills are installed anyway; if you use Codex, trust the hook as above.

Update the CLI

npx orbitmap@latest init

Plain npx orbitmap can reuse an old copy from the npx cache, most often with npm 7 and 8 (check npm -v); @latest always fetches the newest release. For a global install (check with npm ls -g orbitmap), run npm i -g orbitmap@latest. The agent skills update themselves the next time your agent starts a session.

"A newer CLI is available"

Once a day the CLI may print one line:

[orbitmap] A newer CLI is available: <latest> (you run <current>). Update: <command>

Your agent usually passes it on; run the command it shows. Set ORBITMAP_NO_UPDATE_NOTIFIER=1 to turn it off. It is already silent in CI and when you are offline.

On an outdated CLI, init and setup-agent show the update command and ask Continue with <old> anyway? [y/N]. Answer N and update, or add --skip-update-check to go on anyway. If a command fails with CLI_UPGRADE_REQUIRED (HTTP 426), the server needs a newer CLI: run the update command in the error.

Your agent's language

Claude Code answers in the language set by the "language" key in ~/.claude/settings.json, for example "language": "german". Codex has no such setting; it follows the language you write in.

Off or uninstall

npx orbitmap off pauses Orbitmap in one folder. npx orbitmap uninstall removes only local files: the connection, the installed agent instructions and, unless you keep the machine-wide installation, the saved key. It previews the removal first. Your account, workspaces and their missions, intents, tasks and documents stay on the server, and the key stays valid: reveal it again and run npx orbitmap init to reconnect.

Advanced: local mode

Local mode keeps Orbitmap data in a local workspace directory instead of the hosted one, with a smaller feature set and without cloud-only features or the app connection. Use it only when you deliberately need an offline workspace, follow the CLI's local-mode guidance and don't mix its files with a cloud connection.