The Fin CLI (@intercom/cli) is a command-line tool built for developers and AI coding agents, such as Claude Code, Cursor or Codex, to set up, configure and manage Intercom and Fin programmatically. You can point your coding agent at the CLI and ask it in plain language to set up Fin, import content, or change your Fin and Messenger configuration, without leaving your coding environment. Every command is designed to work without interactive prompts, with structured JSON output and clear error messages for use in automated workflows. Learn more at fin.ai/cli.
Requirements
Node.js 18 or higher (v20.6.0+ recommended)
An Intercom workspace in the US region (other regions are not currently supported)
Fin CLI or Fin Agent API MCP server? Use the Fin CLI when you want a coding agent to set up or change your workspace, such as configuring procedures, guidance, audiences, data connectors, workflows, the Messenger or articles. Use the Fin Agent API MCP server when you want an agent to use Fin, such as asking it questions or running procedures on behalf of a user.
Installation
Install the CLI globally via npm:
npm install -g @intercom/cli
Or run it directly without a global install:
npx @intercom/cli
Authentication
The CLI offers three authentication paths depending on your setup:
auth login — Enter an existing token directly.
auth bootstrap — Automatically create an app and retrieve a token using your email and password.
auth signup — Create a brand-new Intercom workspace from scratch.
Credentials are stored securely in your system keychain (macOS Keychain, Windows Credential Manager, or Linux libsecret), with an encrypted file fallback. Tokens expire after approximately 14 days. There is currently no automatic token refresh — you will need to re-authenticate when your token expires.
Key commands
One-command workspace setup
The intercom setup command automates workspace creation, Messenger installation, and help center population in a single step — no UI required.
intercom setup
Content ingestion from Markdown
Populate your help center by pointing the CLI at a local directory of Markdown files:
intercom setup --content-dir ./docs
Raw API access
The intercom api command provides direct access to any Intercom API endpoint, similar to how the GitHub CLI works with gh api:
intercom api
Fin configuration
Manage Fin procedures, guidance, audiences, data connectors, simulations, and workflows directly from the terminal — no need to visit the Intercom UI.
Use the CLI with Claude Code or another coding agent
Install and authenticate the CLI, then ask your coding agent what you want to do in plain language. For example, "Set up Fin on our site and import ./docs/help as articles", or "Only show the Messenger launcher to logged-in users". The agent runs the matching CLI commands for you. To review what it will change before anything is applied, ask it to use the --plan or --dry-run flags first.
Resource management
The CLI includes dedicated commands for managing common Intercom resources:
Command | Operations |
intercom articles | list, get, create, update, delete |
intercom contacts | list, get, create, update, delete |
intercom conversations | list, get, reply |
intercom help-center | list, get, create |
intercom messenger | get, update, snippet |
intercom fin | procedures, guidance, audiences, data connectors, simulations, workflows |
intercom me | show current workspace info |
Planning and dry-run modes
Two flags are available to validate commands before running them:
--plan: Lists the steps the CLI would take without executing them. Useful for AI agents reviewing a workflow before committing.
--dry-run: Validates the command and its inputs without making any changes.
Output modes
All commands support --json for structured output suitable for piping into other tools. You can also filter output inline using --jq — no system jq installation required.
Known limitations
US region only — other regions are not currently supported.
Tokens expire after approximately 14 days with no automatic refresh.
The auth signup and auth bootstrap commands use internal endpoints that may require Web Application Firewall (WAF) exceptions in some production environments.
Node.js 18 or higher is required. OAuth browser flow is not yet supported — token-based authentication (auth login --token) is the primary supported path.
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts