Intercom CLI

CLI tool for managing Intercom workspaces. Designed for both human operators and AI agents.

Install

npm install -g @intercom/cli

Authentication

Existing workspace

Get an API access token from the Developer Hub:

1. Go to the Developer Hub
2. Click New app (or select an existing app)
3. Under Authentication, copy the Access Token
4. Set it in your environment:

export INTERCOM_TOKEN="<your-token>"

Or authenticate via the CLI:

intercom auth login --token "<your-token>"

New workspace

Use the setup command to provision a new workspace — no token required:

intercom setup --company-name "Acme"

Quick Start

# Check your identity
intercom me

# List help center articles
intercom articles list

# Get a conversation
intercom conversations get <conversation-id>

# Set up a workspace with articles and Fin
intercom setup --company-name "Acme" --articles-from ./docs

Commands

| Command | Description | |---|---| | intercom api <endpoint> | Raw API access (like gh api) | | intercom auth login\|logout\|status\|list\|switch | Manage authentication | | intercom auth bootstrap\|signup\|verify-email | Workspace provisioning | | intercom me | Show current admin and workspace | | intercom articles list\|get\|search\|create\|update\|delete | Manage help center articles | | intercom contacts list\|get\|create\|update\|delete\|search | Manage contacts | | intercom conversations list\|get\|reply\|search | Manage conversations | | intercom help-center list\|get\|create | Manage help center collections | | intercom messenger get\|update\|snippet | Configure Messenger | | intercom fin manifest\|enable\|download | Fin AI Agent core | | intercom fin procedures list\|get\|validate\|test\|publish | Fin procedures | | intercom fin guidance\|attributes\|audiences\|workflows\|simulations | Fin SDK resources | | intercom fin data-connectors list\|get | Fin data connectors | | intercom setup | Orchestrate full workspace setup | | intercom config get\|set\|list | Manage CLI configuration | | intercom pricing | Show current Intercom pricing | | intercom changelog | Show the CLI's release notes / version history | | intercom completion bash\|zsh\|fish | Generate shell completions |

Global Flags

| Flag | Description | |---|---| | --json | Output as pretty-printed JSON | | --jq <expr> | Filter JSON output (subset of jq) | | --workspace <id> | Override default workspace | | --verbose | Show HTTP request/response details | | --no-retry | Disable automatic rate limit retry | | --timeout <seconds> | Request timeout in seconds | | --agent | Force machine-readable output (JSON/NDJSON) | | --human | Force human-readable output even when piped | | --wide | Show all columns with wider truncation | | --version | Print CLI version |

Agent / Pipe Mode

When stdout is not a TTY (piped to another program), the CLI automatically outputs compact NDJSON — one JSON object per line. No flag needed:

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

# Force JSON with flag
intercom articles list --json

# Filter inline
intercom articles list --jq '.data[].title'

Raw API Access

The intercom api command provides direct access to any Intercom API endpoint:

# GET request (default)
intercom api /me

# POST with fields
intercom api /articles -f title="Hello" -f author_id=123

# Typed fields (booleans, numbers, file reads)
intercom api /articles -F draft:=true -F [email protected]

# Auto-paginate
intercom api /articles --paginate

# Use jq to filter
intercom api /contacts --jq '.data[].email'

Environment Variables

| Variable | Description | |---|---| | INTERCOM_TOKEN | API token (bypasses credential store) | | INTERCOM_API_BASE_URL | Override API base URL | | INTERCOM_APP_BASE_URL | Override app base URL | | INTERCOM_CONFIG_DIR | Override config directory | | INTERCOM_PASSWORD | Password for signup/bootstrap |

Development

git clone [email protected]:intercom/cli.git
cd cli
pnpm install
pnpm build      # Build to dist/
pnpm test       # Run tests (~5s)
pnpm lint       # TypeScript typecheck
pnpm dev        # Watch mode

# Try it locally
export INTERCOM_TOKEN="<your-token>"
node dist/index.js me

See SETUP.md for full developer setup guide.

Releasing

Publishing @intercom/cli to npm runs through .github/workflows/publish.yml, which fires when a GitHub Release is published. It uses OIDC trusted publishing (GitHub Actions mints a short-lived token per run, so there is no long-lived NPM_TOKEN) and npm staged publishing, which holds every version behind a human 2FA approval before it becomes installable. The org-wide reference is the Engineering Wiki: Release new npm package versions.

Prerequisites (one-time)

• GitHub: write access to this repo, to bump the version and create Releases.
• npm: to approve a staged release, log in to npmjs.com as intercom-npm-publisher (the package owner). Credentials are in the 1Password Engineering Vault.

Cut a stable release

1. Bump the version. In a PR, set the new version in package.json and move the unreleased entries in CHANGELOG.md under a new ## [X.Y.Z] - YYYY-MM-DD heading. Merge it to main — the workflow refuses any release that is not reachable from the default branch.
2. Create a GitHub Release. From the Releases page, add a tag vX.Y.Z that matches package.json exactly (the v prefix is required; the workflow asserts tag == version). Leave the release label as None. Publishing the Release creates the tag and triggers publish.yml.
3. Wait for the workflow. It runs the tag and branch guards, builds, then runs npm stage publish over OIDC. When the Actions run is green, the version sits in npm's staged queue — uploaded but not yet installable.
4. Approve in npm. Logged in as intercom-npm-publisher, open Staged Packages, review the version, and Approve with 2FA. A stable version publishes to the latest dist-tag and is then installable via npm install -g @intercom/cli.

Cut a prerelease

Same path and same approval gate; a prerelease lands on the next dist-tag instead of latest.

1. Bump package.json to a version with a - suffix (e.g. X.Y.Z-beta.1) and merge to main via PR. Prereleases come from the default branch too.
2. Create a GitHub Release tagged vX.Y.Z-beta.1 from that commit (the tag must match the version) and tick Set as a pre-release.
3. The workflow detects the - suffix and stages to the next tag, never latest.
4. Approve the staged version with 2FA as above. Consumers opt in explicitly with npm install -g @intercom/cli@next; a plain install still resolves to stable latest.

Reject a staged release

If a staged version should not ship, choose Reject in Staged Packages and it is removed without publishing. Rejecting leaves the git tag and GitHub Release behind, so also delete the Release and tag from the GitHub Releases UI. The version can then be re-staged — only published versions are immutable.

License

MIT