CLI Troubleshooting

Installation Issues

cosmo: command not found

The CLI binary isn't on your PATH. This usually means the global npm bin directory isn't included.

Fix 1: Reinstall globally

npm install -g @cosmohq/cli

Fix 2: Check where npm installs global packages

npm config get prefix

The bin directory is at <prefix>/bin. Ensure that path is in your $PATH:

echo $PATH

If it's missing, add it to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export PATH="$(npm config get prefix)/bin:$PATH"

Then reload your shell: source ~/.zshrc

Fix 3: If using nvm

With nvm, the global prefix changes per Node.js version. Run cosmo with the same Node version used during installation, or reinstall after switching:

nvm use 20
npm install -g @cosmohq/cli

Installation fails with permission errors

On macOS/Linux:

Don't use sudo npm install -g. Instead, fix npm's global prefix to be user-owned:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g @cosmohq/cli

On Windows:

Run the terminal as Administrator if you see EPERM errors.

Installed a new version but old version still runs

Clear npm's cache and reinstall:

npm uninstall -g @cosmohq/cli
npm cache clean --force
npm install -g @cosmohq/cli
cosmo --version

Authentication Issues

Error: Not authenticated

You haven't logged in yet, or your session has expired.

cosmo auth login

This opens your browser to complete the OAuth flow. After authorizing, return to the terminal — the CLI detects the completed login automatically.

Auth login opens browser but CLI never confirms

The CLI listens on a local port for the OAuth callback. If your browser can't redirect back (e.g., browser is blocking the redirect, or a firewall blocks localhost), authentication hangs.

Fix:

1. Ensure your browser allows redirects to localhost / 127.0.0.1
2. Temporarily disable any VPN that might block loopback connections
3. If you're in a headless environment (e.g., SSH), use the --token flag with a pre-generated token instead:

cosmo auth login --api-key <your-api-key>

You can generate an API key via the server's API endpoints or have an admin provision one for you.

Error: Token expired or session keeps expiring

Cosmo auth tokens are short-lived. Re-authenticate:

cosmo auth logout
cosmo auth login

If this keeps happening, check that your system clock is accurate — JWT validation is time-sensitive.

Logged in but seeing "Organization not found"

You may be authenticated but not yet a member of any organization. Either:

• Accept an invitation email that was sent to you, or
• Create a new organization at cosmo.dev

Team Workspace Issues

Team sync fails

Check your auth status and try syncing again:

cosmo auth status
cosmo team sync

Use --pull or --push flags to limit the sync direction if needed:

cosmo team sync --pull

Chat & REPL Issues

REPL starts but responses are slow or hang

1. Check your internet connection — AI calls require connectivity to Cosmo's API and the LLM provider
2. Check Cosmo's status — visit status.getcosmo.app for any active incidents
3. Try a one-shot command instead to isolate the issue:

cosmo chat "Hello"

Tool calls fail with Integration not connected

The integration isn't set up in your organization. Connect it first:

cosmo mcp connect <server-type> --label <name>

Or navigate to Settings → Integrations in the desktop or web app.

Long responses get cut off

This is usually a context window issue. If the conversation is very long, the model may not have enough context for a complete response. Start a fresh session:

# In REPL, start a new session
/new

Or end the REPL and restart it.

Colors or formatting look wrong in terminal

The CLI uses ANSI color codes. If your terminal doesn't support them or they render as garbled characters:

NO_COLOR=1 cosmo

MCP Connector Issues

Error: Failed to connect to MCP server

This typically means the MCP server process couldn't start (for stdio transport) or the remote server is unreachable (for SSE/HTTP transport).

For local stdio servers:

1. Check the command path is correct
2. Verify the binary exists and is executable
3. Run the MCP server command manually to see the error output

For remote servers:

1. Check your internet connection
2. Verify the server URL is correct in the connector config
3. Check if the remote service has an active incident

MCP servers show as disconnected after system restart

Local stdio MCP connections need to be re-established on each CLI startup. This is by design — the CLI re-connects when needed. If a connector consistently fails to reconnect, check if the underlying service or binary is still available:

cosmo mcp list
cosmo mcp connect <server-type> --label <name>   # Re-connect if needed

Updates

cosmo update doesn't install the latest version

The CLI uses npm for updates. Run:

npm install -g @cosmohq/cli@latest
cosmo --version   # Confirm new version

Getting More Help

If your issue isn't covered here, run with verbose logging:

DEBUG=cosmo:* cosmo

Then share the output with support@getcosmo.app along with:

• Your OS and Node.js version (node --version)
• CLI version (cosmo --version)
• The exact error message
• Steps to reproduce