Open Source·AI Agent Infrastructure

Your LinkedIn Outbound, Controlled by Agents.

Campaigns. Inbox. Leads. Lists. Network. 47 commands. Every one doubles as an MCP tool.

HeyReach automates LinkedIn outreach — but there’s no official CLI.
So we built heyreach-cli — the missing CLI for agents on HeyReach.

Install from npmSign up for HeyReach
47
Commands
10
API Groups
CLI
+ MCP Native
OpenClaw
OpenClaw
CLI / MCP
HeyReach
HeyReach
campaigns · inbox · leads · lists · network

Why heyreach-cli Exists

Without heyreach-cli

  • No official CLI — HeyReach only offers a REST API and dashboard UI
  • Agents can’t manage LinkedIn campaigns or reply to inbox without custom wrappers
  • Manual API auth per request — no token resolution strategy
  • No MCP support — agents can’t call HeyReach as a native tool
  • Campaign analytics and lead data locked in the dashboard

With heyreach-cli

  • 47 commands covering the full HeyReach API surface
  • Single API key, 3-tier resolution: flag → env var → config file
  • Every command is also an MCP tool — plug into any AI agent
  • JSON-first output — pipe to jq, save to files, feed to agents
  • Unified inbox management — read, reply, and track across all LinkedIn accounts

When You Need This

🚀

Automated LinkedIn Outreach

Launch and manage multi-step LinkedIn campaigns — connection requests, messages, InMails, profile views — all from your agent.

📬

Unified Inbox Management

Read and reply to LinkedIn conversations across all connected accounts without switching between dashboards or browsers.

🏷️

Lead Enrichment & Tagging

Look up any lead by LinkedIn URL, tag them by status or segment, and track which campaigns and lists they belong to.

📊

Campaign Analytics on Demand

Pull connection acceptance rates, reply rates, and message stats for any time period — data your agent can act on.

⚡

Real-Time Webhook Automation

Set up webhooks for 12 LinkedIn event types — replies, connection accepts, campaign completions — and trigger downstream workflows.

👥

Multi-Account Sender Management

Rotate across multiple LinkedIn accounts within a single campaign. Check connection status and network intelligence before outreach.

Quick Start

1. Install

Terminal
npm install -g heyreach-cli

2. Get your API key

1. Log into your HeyReach workspace

2. Navigate to Settings → Integrations → Public API

3. Copy your API key

3. Authenticate

Terminal
# Option A: environment variable (recommended for agents)
export HEYREACH_API_KEY="your-api-key"

# Option B: login command (saves to ~/.heyreach/config.json)
heyreach login

# Option C: per-command flag
heyreach campaigns list --api-key "your-api-key"

4. Verify

Terminal
heyreach status
# Validates your API key

heyreach campaigns list --pretty
# Returns your campaigns as formatted JSON

heyreach accounts list --pretty
# Lists your connected LinkedIn accounts

What heyreach-cli Gives Your Agent

8 cmds

Campaigns

List, get, pause, resume campaigns. Add leads to active sequences, stop leads mid-campaign, and pull lead analytics with status breakdowns.

4 cmds

Unified Inbox

Browse conversations across all connected LinkedIn accounts. Read threads, send replies, mark as seen — one inbox for every sender.

14 cmds

Lists & Leads

Create lead and company lists, add/remove leads by URL or ID, search within lists, and manage the full lead lifecycle with tagging.

5 cmds

Webhooks & Events

Subscribe to 12 real-time LinkedIn event types — connection accepts, message replies, InMail replies, campaign completions, and more.

2 cmds

Network Intelligence

Query a sender’s LinkedIn network and check connection status with any lead. Know who’s connected before you reach out.

MCP Server

Every command is exposed as an MCP tool. Claude, Cursor, OpenClaw, and any MCP client can call all 47 commands natively.

Agent Workflows

Real prompts agents use to manage HeyReach LinkedIn outbound end-to-end.

Launch a LinkedIn Campaign with Leads

Agent Prompt

“Create a prospect list called "Q2 Enterprise", add these 3 LinkedIn profiles to it, then add them to campaign 12345 and resume it.”

Agent creates the list, imports leads by profile URL, adds them to the campaign, and kicks it live — full campaign launch in one autonomous flow.

1
heyreach lists create --name "Q2 Enterprise" --type USER_LIST

Create lead list

2
heyreach lists add-leads --list-id $LIST_ID --leads-json '[{"firstName":"Alex","lastName":"Chen","profileUrl":"https://linkedin.com/in/alexchen","companyName":"TechCo","position":"CTO"}]'

Import leads with profile data

3
heyreach campaigns add-leads --campaign-id 12345 --leads-json '[{"lead":{"profileUrl":"https://linkedin.com/in/alexchen"}}]'

Add leads to campaign

4
heyreach campaigns resume --campaign-id 12345

Start the campaign

Morning Inbox Review

Agent Prompt

“Check for any unseen LinkedIn replies across all my accounts. Show me the new conversations and mark them as seen after I review.”

Agent pulls unseen conversations, reads full threads, and marks them seen — morning inbox zero without opening the dashboard.

1
heyreach inbox list --seen false --pretty

Get all unseen conversations

2
heyreach inbox get --account-id $ACCT_ID --conversation-id $CONV_ID --pretty

Read full conversation thread

3
heyreach inbox set-seen --conversation-id $CONV_ID --account-id $ACCT_ID --seen true

Mark as seen

Reply to a Hot Lead

Agent Prompt

“A VP of Sales at Acme just replied to our connection request. Send them a follow-up message and tag them as "hot".”

Agent finds the conversation, sends a personalized reply, and tags the lead — follow-up plus CRM tagging in one shot.

1
heyreach inbox list --search "acme" --pretty

Find the conversation

2
heyreach inbox send --conversation-id $CONV_ID --account-id $ACCT_ID --message "Thanks for connecting! Would love to explore how we can help Acme scale outbound."

Send follow-up message

3
heyreach leads add-tags --profile-url "https://linkedin.com/in/vp-sales-acme" --tags "hot,enterprise" --create-if-missing

Tag lead as hot

Campaign Performance Review

Agent Prompt

“Pull analytics for all my active campaigns over the last 30 days. Show me connection acceptance rates and reply rates.”

Agent exports comprehensive stats with day-by-day breakdowns — profile views, messages sent, replies, acceptance rates — a full performance brief.

1
heyreach campaigns list --statuses IN_PROGRESS --pretty

List active campaigns

2
heyreach stats overview --start-date "2026-02-11T00:00:00Z" --end-date "2026-03-11T23:59:59Z" --pretty

Pull 30-day analytics

3
heyreach campaigns get-leads --campaign-id $CAMPAIGN_ID --pretty

Check lead status breakdowns

Set Up Webhook Notifications

Agent Prompt

“Create webhooks for connection accepts and message replies so our n8n workflow gets notified in real-time when prospects engage.”

Agent creates webhook endpoints for key LinkedIn events — real-time automation infrastructure deployed in seconds.

1
heyreach webhooks create --name "Connection Accepts" --url "https://n8n.company.com/webhook/heyreach" --event-type CONNECTION_REQUEST_ACCEPTED

Webhook for connection accepts

2
heyreach webhooks create --name "Reply Notifications" --url "https://n8n.company.com/webhook/heyreach" --event-type MESSAGE_REPLY_RECEIVED

Webhook for message replies

3
heyreach webhooks list --pretty

Verify webhooks are active

Check Connection Status Before Outreach

Agent Prompt

“Before I add these leads to a campaign, check which ones are already connected to our LinkedIn sender account.”

Agent checks network connection status for each lead — filtering out already-connected contacts before adding to an outreach sequence.

1
heyreach accounts list --pretty

List sender accounts

2
heyreach network check --sender-account-id $SENDER_ID --lead-profile-url "https://linkedin.com/in/prospect1"

Check connection status

3
heyreach network list --sender-id $SENDER_ID --pretty

Browse full sender network

Commands Reference

campaigns (8 commands)
heyreach campaigns list [--keyword <text>] [--statuses <list>]List campaigns with optional filters
heyreach campaigns get --campaign-id <id>Get a single campaign
heyreach campaigns resume --campaign-id <id>Resume a paused campaign
heyreach campaigns pause --campaign-id <id>Pause an active campaign
heyreach campaigns add-leads --campaign-id <id> --leads-json <json>Add leads to a campaign
heyreach campaigns stop-lead --campaign-id <id> [--lead-url <url>]Stop a lead mid-sequence
heyreach campaigns get-leads --campaign-id <id> [--time-from <iso>]Pull lead analytics with status breakdowns
heyreach campaigns get-for-lead [--profile-url <url>] [--email <e>]Find which campaigns a lead is in
inbox (4 commands)
heyreach inbox list [--account-ids <list>] [--search <text>] [--seen <bool>]Browse conversations with filters
heyreach inbox get --account-id <id> --conversation-id <id>Read full conversation thread
heyreach inbox send --conversation-id <id> --account-id <id> --message <text>Send a LinkedIn message
heyreach inbox set-seen --conversation-id <id> --account-id <id> --seen <bool>Mark conversation seen/unseen
accounts (2 commands)
heyreach accounts list [--keyword <text>]List connected LinkedIn accounts
heyreach accounts get --account-id <id>Get a single account
lists (9 commands)
heyreach lists list [--keyword <text>] [--list-type <type>]List lead and company lists
heyreach lists get --list-id <id>Get list details
heyreach lists create --name <name> [--type USER_LIST|COMPANY_LIST]Create a new list
heyreach lists get-leads --list-id <id> [--keyword <text>]Search leads within a list
heyreach lists add-leads --list-id <id> --leads-json <json>Add leads to a list
heyreach lists delete-leads --list-id <id> --member-ids <list>Remove leads by ID
heyreach lists delete-leads-by-url --list-id <id> --urls <list>Remove leads by LinkedIn URL
heyreach lists get-companies --list-id <id> [--keyword <text>]Query companies in a list
heyreach lists get-for-lead [--profile-url <url>] [--email <e>]Find which lists a lead belongs to
leads (4 commands)
heyreach leads get --profile-url <url>Look up a lead by LinkedIn URL
heyreach leads add-tags --tags <list> [--profile-url <url>]Add tags to a lead
heyreach leads get-tags --profile-url <url>Get all tags on a lead
heyreach leads replace-tags --tags <list> [--profile-url <url>]Replace all tags on a lead
lead-tags (1 command)
heyreach lead-tags create --tags-json <json>Create workspace-level tags with colors
stats (1 command)
heyreach stats overview --start-date <iso> --end-date <iso> [--campaign-ids <list>]Pull campaign analytics with day-by-day breakdowns
webhooks (5 commands)
heyreach webhooks listList all webhooks
heyreach webhooks get --webhook-id <id>Get a single webhook
heyreach webhooks create --name <name> --url <url> --event-type <type>Create webhook for LinkedIn events
heyreach webhooks update --webhook-id <id> [--url] [--event-type] [--active]Update webhook configuration
heyreach webhooks delete --webhook-id <id>Delete a webhook
network (2 commands)
heyreach network list --sender-id <id> [--page <n>]Browse a sender's LinkedIn network
heyreach network check --sender-account-id <id> [--lead-profile-url <url>]Check connection status with a lead
org (11 commands)
heyreach org workspaces [--offset <n>] [--limit <n>]List organization workspaces
heyreach org create-workspace --name <name> [--seats-limit <n>]Create a new workspace
heyreach org update-workspace --workspace-id <id> [--name] [--seats-limit]Update workspace settings
heyreach org api-keys --workspace-id <id>List API keys for a workspace
heyreach org create-api-key --workspace-id <id> --type <type>Generate new API key (PUBLIC, N8N, MCP, etc.)
heyreach org users [--role <role>]List organization users
heyreach org get-user --user-id <id>Get a single user
heyreach org workspace-users --workspace-id <id>List users in a workspace
heyreach org invite-admins --inviter-email <e> --emails <list>Invite admin users
heyreach org invite-members --inviter-email <e> --emails <list> --workspace-ids <list>Invite members with permissions
heyreach org invite-managers --inviter-email <e> --emails <list> --workspace-ids <list>Invite manager users

MCP Server Setup

Every command is available as an MCP tool. Configure once and your agent has full HeyReach LinkedIn access.

Claude Desktop / Cursor (~/.cursor/mcp.json or claude_desktop_config.json)
{
  "mcpServers": {
    "heyreach": {
      "command": "npx",
      "args": ["heyreach-cli", "mcp"],
      "env": {
        "HEYREACH_API_KEY": "your-api-key"
      }
    }
  }
}

MCP tools registered (47 total):

campaigns_listcampaigns_getcampaigns_resumecampaigns_pausecampaigns_add_leadscampaigns_stop_leadcampaigns_get_leadscampaigns_get_for_leadinbox_listinbox_getinbox_sendinbox_set_seenaccounts_listaccounts_getlists_listlists_getlists_createlists_get_leadslists_add_leadslists_delete_leadslists_delete_leads_by_urllists_get_companieslists_get_for_leadleads_getleads_add_tagsleads_get_tagsleads_replace_tagslead_tags_createstats_overviewwebhooks_listwebhooks_getwebhooks_createwebhooks_updatewebhooks_deletenetwork_listnetwork_checkorg_workspacesorg_create_workspaceorg_update_workspaceorg_api_keysorg_create_api_keyorg_usersorg_get_userorg_workspace_usersorg_invite_adminsorg_invite_membersorg_invite_managers

OpenClaw Agent Setup

Give any OpenClaw agent full HeyReach LinkedIn access. Install once, set the API key, and the agent manages your outbound autonomously.

1
Install on the agent's server
npm install -g heyreach-cli
2
Set API key in agent environment
export HEYREACH_API_KEY=your-key — or use heyreach login to save to config
3
Start MCP server
heyreach mcp — runs on stdio transport, compatible with any MCP client
4
Add LinkedIn outbound instructions to SOUL.md
Tell the agent how to manage campaigns, reply to conversations, and tag leads through your outbound workflow
5
Test from Slack
"Check for new LinkedIn replies today" — agent calls heyreach inbox via MCP, returns unseen conversations as structured JSON

Architecture

Every API endpoint is a CommandDefinition — one source of truth powering both the CLI subcommand and the MCP tool.

src/
├── core/
│   ├── types.ts      # CommandDefinition, HeyReachClient interfaces
│   ├── client.ts     # HTTP client (X-API-KEY, retry, rate limit)
│   ├── auth.ts       # 3-tier API key resolution
│   ├── config.ts     # ~/.heyreach/config.json
│   ├── errors.ts     # Typed error classes
│   ├── output.ts     # JSON output + --fields filtering
│   └── handler.ts    # Request builder from CommandDefinition
├── commands/
│   ├── campaigns/    # 8 commands
│   ├── inbox/        # 4 commands
│   ├── accounts/     # 2 commands
│   ├── lists/        # 9 commands
│   ├── stats/        # 1 command
│   ├── leads/        # 4 commands
│   ├── lead-tags/    # 1 command
│   ├── webhooks/     # 5 commands
│   ├── network/      # 2 commands
│   └── org/          # 11 commands
├── mcp-entry.ts      # MCP server (auto-registers all commands)
└── index.ts          # CLI entry point

Same pattern as all TOFU CLIs

The CommandDefinition architecture is shared across instantly-cli, clay-gtm-cli, hubspot-cli, partnerstack-cli, and ms365-cli. One schema definition generates the Commander.js subcommand, the Zod schema, and the MCP tool — zero duplication.

HeyReach API Specifics

Uses X-API-KEY header auth (not Bearer). POST body pagination with offset/limit. 300 req/min rate limit with auto-retry. Separate Organization API for admin operations.

Ready to automate your LinkedIn outbound?

Install heyreach-cli, set your API key in 60 seconds, and your agent can manage campaigns, reply to conversations, and track leads across your entire LinkedIn operation.

Sign up for HeyReach

Need agents running your LinkedIn outbound? We deploy and manage the full setup.