Setup and troubleshooting
Most installations need only npx orbitmap init once. This page covers the cases worth remembering; it is not a transcript of every prompt.
Recover an API key
The key copied from the app's Connect step is shown once. If it is lost, regenerate the agent key in Settings and run init again. The CLI checks the new key before completing the connection.
Run init again
Rerunning is the normal way to connect another checkout, map a folder that was skipped, or refresh setup after a CLI upgrade:
npx orbitmap init
It merges the local connection, updates the OrbitMap instructions in place and keeps the workspace data on the server. Run it inside each repository when repositories are not siblings under one common parent. Run it in the common parent when you want one workspace root containing several areas.
init writes connection metadata under .orbitmap/, stores the API key outside the repository, and may update agent configuration and .gitignore. It does not upload source code, overwrite unrelated instructions, or delete your workspace data. Review its final file list before confirming.
Check the connection from the terminal
When the app says the machine is connected but the agent cannot find the workspace or area, run this from the connected folder:
npx orbitmap context
It prints the agent, workspace and area context available to the current session. If it cannot resolve them, check the directory and .orbitmap/config.json, then rerun init.
Refresh or add an agent
init installs instructions for Claude Code or Codex during the connection. Later, use:
orbitmap setup-agent
Use it after upgrading the CLI or when adding the other supported agent:
orbitmap setup-agent --agent codex
It refreshes the coding-agent instructions; it does not change the workspace connection or API key.
Remove the local setup
To undo files created by OrbitMap, including the local connection and installed agent instructions, run:
orbitmap uninstall
The command previews the removal and lets you cancel or keep the machine-wide installation. It does not delete workspace missions, intents, tasks or documents from OrbitMap. The key remains valid until you regenerate it.
Advanced: local mode
Local mode is for working without the hosted workspace and is not the normal onboarding path. It keeps OrbitMap data in a local workspace directory and has a smaller feature set; cloud-only features and the app connection do not apply. Use it only when you deliberately need an offline/local workspace and follow the CLI's local-mode guidance rather than mixing its files with a cloud connection.
If a command reports that it cannot resolve a workspace or area, first check that you are in the directory where init ran and that .orbitmap/config.json is present. For an area inside a multi-repository folder, run the command from that repository or provide the area context supported by your CLI version.
For how repository folders become areas, see How work is organized. For the normal first connection, return to Getting started.