Skip to main content

​
Install OrbCode CLI

OrbCode CLI runs on any system with Node.js >= 20. Install it globally from npm, then sign in with your MatterAI account.

​
Prerequisites

Node.js >= 20 — check with node --version
A MatterAI account — sign up at app.matterai.so if you don’t have one

​
Install from npm

Verify the install:

​
Install from source (development)

npm link creates a symlink to the repo, so after pulling changes you only need to rebuild — no relink required:
Relink only when the package name or bin entry changes:
The version reported by orbcode --version is read from package.json at runtime. If --version shows an old version after pulling, rebuild with npm run build.

​
Authentication

Browser-based device flow with polling (no copy/paste needed).
1

Start the login flow

Run orbcode login (or /login inside the TUI). The CLI calls POST /orbcode/auth/start on the MatterAI backend, which issues a one-time device code (10-minute lifetime).
2

Authorize in the browser

The CLI opens https://app.matterai.so/orbital?loginType=orbcode&devicecode=<code> in your browser. If you’re already signed in, the Authorize OrbCode CLI dialog appears immediately; otherwise you’re redirected to sign in first.
3

Click Authorize

Clicking Authorize binds your session token to the device code. The CLI polls the backend every 3 seconds and picks up the token exactly once.
4

Start coding

The CLI verifies the token against the profile endpoint, saves it, and you’re ready to go. Sign out anytime with /logout.

​
Alternative authentication

You can skip the browser flow entirely:
  • API key in settings.json — set apiKey in ~/.orbcode/settings.json (or a project’s .orbcode/settings.json).
  • Env token — set MATTERAI_TOKEN to skip login entirely (takes precedence over everything).
Tokens are MatterAI JWTs. A token whose payload has env: "development" automatically routes API calls to http://localhost:3000, matching the extension’s behavior.

​
Troubleshooting