install-cli

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:

1. 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).
2. 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.

1. Direct them to the Developer Hub.
2. Click New app (or select an existing app).
3. Under Authentication, copy the Access Token.
4. 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.

# zsh — append to ~/.zshrc
intercom completion zsh >> ~/.zshrc

# bash — append to ~/.bashrc
intercom completion bash >> ~/.bashrc

# fish
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:

# Auto NDJSON when piped
intercom articles list | jq '.title'

# Force JSON
intercom articles list --json

# Inline jq filter
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                  # show stored credentials
intercom auth switch <workspace>    # change default
intercom me --workspace <id>        # one-off override

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"      # EU
export INTERCOM_API_BASE_URL="https://api.au.intercom.io"      # Australia

Set this in the shell rc file alongside the token.