| name | install-cli |
| license | MIT |
| description | Install and authenticate the Intercom CLI (`@intercom/cli`) — a command-line tool for managing Intercom workspaces, designed for both human operators and AI agents. Use when the user asks to "install the Intercom CLI", "set up the intercom command", "install @intercom/cli", or wants shell access to their Intercom workspace.
|
| disable-model-invocation | true |
Install Intercom CLI
Install the @intercom/cli package globally and authenticate it against the user's workspace. The CLI complements this plugin: the plugin is for in-conversation MCP usage, while the CLI is for shell access, scripting, and workspace provisioning.
Prerequisites
Before installing, verify the user has:
- Node.js >= 20.6.0 — Run
node --version to check. If missing or older, direct them to install via nodejs.org or their version manager (nvm, fnm, volta).
- npm — Comes bundled with Node.
If node --version returns < 20.6.0, stop and ask the user to upgrade before proceeding. The CLI will not run on older versions.
Step 1: Install Globally
npm install -g @intercom/cli
Verify the install:
intercom --version
If the user gets a permission error (EACCES) on macOS or Linux, they likely have a system Node install. Recommend either:
- Switching to a user-managed Node via nvm/fnm/volta (preferred), or
- Configuring an npm prefix under their home directory.
Do not suggest sudo npm install -g — installing global packages as root is a known footgun and will cause permissions issues on later updates.
Step 2: Authenticate
There are two paths. Ask the user which applies.
Path A: Existing Workspace (most common)
The user has an Intercom workspace and needs to connect the CLI to it.
- Direct them to the Developer Hub.
- Click New app (or select an existing app).
- Under Authentication, copy the Access Token.
- Authenticate one of two ways:
Option 1 — Persistent (recommended for interactive use):
intercom auth login --token "<paste-token-here>"
This stores the token in the OS keyring (Keychain on macOS, Secret Service on Linux, Credential Manager on Windows) so future commands don't need the env var.
Option 2 — Environment variable (recommended for CI / scripting):
export INTERCOM_TOKEN="<paste-token-here>"
Add this to ~/.zshrc, ~/.bashrc, or the equivalent so it persists across shells. For CI, set it as a secret in the pipeline config.
The env var takes precedence over the keyring-stored credential when both are present.
Path B: New Workspace (provisioning)
The user wants to create a brand-new Intercom workspace from scratch — no token needed.
intercom setup --company-name "Acme"
This command provisions a workspace, signs the user in, and stores the resulting credentials. The CLI will prompt for an email, password, and verification code during the flow.
If the user has additional setup needs (importing articles, enabling Fin, etc.), point them at:
intercom setup --help
Step 3: Verify
Run:
intercom me
Expected output: the admin's name, email, and the active workspace ID. If this fails:
| Error | Likely Cause | Fix |
|---|
Not authenticated | No token in keyring or env | Re-run Step 2 |
401 Unauthorized | Token revoked or wrong workspace | Generate a new token in the Developer Hub |
command not found: intercom | Global install path not on $PATH | Run npm config get prefix, ensure <prefix>/bin is on $PATH |
Step 4 (Optional): Shell Completions
Recommend this only if the user uses intercom interactively in their shell.
intercom completion zsh >> ~/.zshrc
intercom completion bash >> ~/.bashrc
intercom completion fish > ~/.config/fish/completions/intercom.fish
Restart the shell or source the rc file for completions to take effect.
Quick Reference
After install, the user can run any of these. Don't dump this whole list at them — surface relevant commands based on their goal.
| Command | Purpose |
|---|
intercom me | Show current admin + workspace |
intercom api <endpoint> | Raw API access (like gh api) |
intercom articles list|get|search | Help center articles |
intercom contacts list|get|search | Contacts |
intercom conversations list|get|search | Conversations |
intercom fin manifest|enable|download | Fin AI Agent |
intercom messenger get|update|snippet | Messenger config |
intercom config list | Show CLI config |
Full reference: @intercom/cli README.
Agent / Pipe Mode
The CLI auto-detects when stdout is piped and switches to compact NDJSON (one JSON object per line). This makes it ergonomic for scripts and AI agents:
intercom articles list | jq '.title'
intercom articles list --json
intercom articles list --jq '.data[].title'
If the user is using the CLI from a Claude Code agent or other automation, prefer --json or --jq over parsing human-formatted output.
Multi-Workspace
If the user manages multiple workspaces:
intercom auth list
intercom auth switch <workspace>
intercom me --workspace <id>
Each workspace's credential is stored separately in the keyring.
Troubleshooting
npm install -g Hangs or Fails on Corporate Network
The user's npm registry may be proxied. Check npm config get registry — if it points at an internal mirror, that mirror may not have @intercom/cli published. Set the registry explicitly for this install:
npm install -g @intercom/cli --registry=https://registry.npmjs.org
intercom Command Found But Crashes Immediately
Usually a Node version mismatch. Run node --version and confirm it's >= 20.6.0. If using nvm, ensure the active version (nvm current) is the one the global install used.
Token Stored But Commands Still Fail With 401
The INTERCOM_TOKEN env var overrides the keyring. Run unset INTERCOM_TOKEN and try again — a stale env var may be shadowing a fresh keyring credential.
Wrong Region (EU / Australia)
The CLI defaults to the US API. If the workspace is hosted in EU or Australia:
export INTERCOM_API_BASE_URL="https://api.eu.intercom.io"
export INTERCOM_API_BASE_URL="https://api.au.intercom.io"
Set this in the shell rc file alongside the token.
