Skip to main content
If the CLI is not behaving, start here. Each section covers a common failure mode with the quickest known fix.

​
Login or device-code fails

The CLI prints a URL and code even if a browser does not launch automatically. Copy the URL manually, open it in any browser, paste the code.
Codes expire after a few minutes. Run rubix login again to get a fresh code.
Typically a local firewall blocking the token exchange callback. Check outbound HTTPS to api.rubixkube.ai:443. Corporate proxies can also rewrite the request; set HTTPS_PROXY if needed.
The token was invalidated (new workspace role, long inactivity). Force a clean re-login:
rubix logout
rubix login

​
Stale or conflicting auth

If the CLI reports a workspace or user that is no longer correct: 
rubix logout
rm -f ~/.rubix/auth.json
rubix login
This resets auth completely and walks through the device-code flow again.

​
Command not found

Your global npm bin is not on PATH. Find it:
npm bin -g
Add the printed directory to your shell profile (~/.zshrc, ~/.bashrc, or PowerShell profile) and reload.
Rubix installs into the currently active Node version. If you switch Node versions, you may need to reinstall. Alternatively, install globally under a version manager setup that persists across Node switches (e.g. via npm config set prefix).

​
Node.js version errors

The CLI requires Node.js 18 or later. Check: 
node --version
If you see 16 or earlier, upgrade: 
# macOS with Homebrew
brew install node@20

# With nvm
nvm install --lts
nvm use --lts
Then reinstall the CLI.

​
Proxy, VPN, or strict egress

The CLI needs outbound HTTPS to:
  • api.rubixkube.ai:443
  • nats.rubixkube.ai:443
Test from the shell: 
curl -I https://api.rubixkube.ai
curl -I https://nats.rubixkube.ai
If behind a proxy: 
export HTTPS_PROXY=http://proxy.example.internal:3128
export HTTP_PROXY=http://proxy.example.internal:3128
export NO_PROXY=localhost,127.0.0.1

​
Chat is slow or unresponsive

Usually network latency between your terminal and api.rubixkube.ai. Verify with a plain curl -I. If latency is fine but Chat feels slow, try /new to drop a long context, or /models to switch to a faster model.
NATS connection dropped. Rubix reconnects automatically, but you may need to resubmit the last prompt. If drops are frequent, check for aggressive VPN or firewall idle timeouts.
Rare. Run /status to confirm environment and agent are healthy. If they are, send /new to start a fresh session and retry.

​
Terminal display glitches

Some terminals need truecolor enabled. Check COLORTERM is set to truecolor or 24bit. Mainstream terminals (iTerm2, Alacritty, modern VS Code terminal, Windows Terminal) support it by default.
Use /paste inside chat. It bypasses the terminal’s paste buffer and uses the system clipboard directly.
Install a font with broad Unicode coverage, like JetBrains Mono, Fira Code, or any Nerd Font variant.

​
CI-specific issues

Set RUBIX_API_KEY in the environment. The CLI uses that token directly and skips the device-code prompt.
Set RUBIX_ENV_ID to pin the environment for the run.
For repeat runs, install globally or cache @rubixkube/rubix in the CI image. npx re-downloads on every run.

​
Still stuck?

Email support

Include the output of rubix --version, your Node version (node --version), a short description of what you were doing, and any error output. A human engineer will respond.

​
Where to go next

Configuration

Where things live and how trust is scoped.

FAQ

Quick answers to common questions.