Documentation
Search LinkedIn, build lists, run campaigns and answer replies from a terminal, a script or a cron job. It is an MCP client, not a second API, so a command and an assistant make the same call.
npm i -g @kairon/cliNeeds Node 22.23.1 or newer. You can also run it once with npx and install nothing.
npm i -g @kairon/clinpx @kairon/cli whoamiOpens your browser and signs you in with your Kairon account. There is no API key. Credentials are stored in ~/.kairon/config.json at mode 0600, keyed by server, so a local login never disturbs the production one.
kairon loginkairon login --server http://localhost:3055Reports the account and the LinkedIn seat every command will run as. If this works, the rest will.
kairon whoamiEvery command prints JSON, so it pipes straight into jq. Ask for help on any group or command at any time.
kairon chat list --unreadkairon list --helpOne command per tool, and there is no list of them in the CLI itself. A tool name splits on its first underscore and the rest is kebab-cased, so the surface here is exactly the surface the server exposes.
This page is generated from the tool catalogue by the same functions that build kairon --help, on every release. The page and your terminal cannot disagree, because they are the same code.
Activate a campaign — starts sending to real people
Full descriptionTHIS STARTS SENDING MESSAGES TO REAL PEOPLE ON LINKEDIN, and a message already sent cannot be un-sent.
| Flag | Type | What it is for |
|---|---|---|
--startNow | boolean | |
--idrequired | string |
Create a draft campaign
Full descriptionCreate a draft campaign: a name, the sending seat (channelAccountId — a connected LinkedIn account in this org), and optionally the ICP to gate enrollment on (icpId; when omitted, the org's most-used ICP is auto-selected as the default gat…
| Flag | Type | What it is for |
|---|---|---|
--namerequired | string | |
--channelAccountIdrequired | string | |
--icpId | string |
Pause an active campaign
Full descriptionPause an active campaign — { id }.
| Flag | Type | What it is for |
|---|---|---|
--idrequired | string |
Validate and publish the campaign's draft graph
Full descriptionValidate and publish the campaign's current draft graph — { id, migrateInFlight? }.
| Flag | Type | What it is for |
|---|---|---|
--idrequired | string | |
--migrateInFlight | boolean |
One sequence run, step by step
Full descriptionRead ONE sequence run in full — { runId } (an id from campaign_runs).
| Flag | Type | What it is for |
|---|---|---|
--runIdrequired | string |
The campaign's sequence runs
Full descriptionRead the campaign's sequence runs — one per enrolled lead — keyset-paginated: { id, bucket?, cursor?, limit? }.
| Flag | Type | What it is for |
|---|---|---|
--bucket | waiting|didnt_accept|didnt_answer|replied|skipped|error|interested | |
--cursor | string | |
--limit | integer | |
--idrequired | string |
Replace the campaign's draft sequence graph
Full descriptionReplace the campaign's editable DRAFT sequence graph in full — { id, graph: { nodes, edges, startNodeKey } }.
| Flag | Type | What it is for |
|---|---|---|
--idrequired | string | |
--graph.nodesrequired | json arrayjson | |
--graph.edgesrequired | json arrayjson | |
--graph.startNodeKeyrequired | jsonjson |
How the campaign is doing
Full descriptionEverything about how a campaign is performing, in one read — { id, days? }.
| Flag | Type | What it is for |
|---|---|---|
--idrequired | string | |
--days | jsonjson |
Edit the campaign's configuration and audience
Full descriptionEdit a campaign's configuration — any subset of { id, name, sendWindow, autonomy, dailyEnrollmentLimit, enrollmentFilter, icpId, stopOnReply, leadListIds }.
| Flag | Type | What it is for |
|---|---|---|
--name | string | |
--sendWindow.days | json arrayjson | |
--sendWindow.startHour | integer | |
--sendWindow.endHour | integer | |
--sendWindow.timeZone | string | |
--autonomy | manual|autopilot | |
--dailyEnrollmentLimit | integer | |
--enrollmentFilter.buckets | json arrayjson | |
--enrollmentFilter.scope | seat|org | |
--icpId | jsonjson | |
--stopOnReply | boolean | |
--idrequired | string | |
--leadListIds | json arrayjson |
List LinkedIn conversations
Full descriptionList LinkedIn conversations, newest activity first.
| Flag | Type | What it is for |
|---|---|---|
--seatId | string | A teammate's seat id (from a chat's `channelAccountId`). Defaults to your own. |
--scope | mine|org | 'mine' (default) is your own seat; 'org' is every seat in the organization. |
--unread | boolean | |
--leadsOnly | boolean | Only chats already linked to a lead. |
--q | string | Case-insensitive match on the counterpart's NAME. |
--cursor | string | |
--limit | integer |
Read a conversation
Full descriptionRead one conversation's messages, newest first, by the chatId from chat_list.
| Flag | Type | What it is for |
|---|---|---|
--chatIdrequired | string | |
--cursor | string | |
--limit | integer |
Resolve a Sales Navigator filter
Full descriptionResolve a human-readable Sales Navigator filter value (location, industry, function) to a LinkedIn id, echoing the canonical label so a wrong match is visible.
| Flag | Type | What it is for |
|---|---|---|
--typerequired | location|industry|function|current_company|past_company|company_location|school|past_role|groups|persona|technologies|account_lists|lead_lists|postal_code | |
--queryrequired | string |
Get an ICP
Full descriptionRead one ICP and its latest (active) version by icpId.
| Flag | Type | What it is for |
|---|---|---|
--icpIdrequired | string |
List ICPs
Full descriptionList this org's ICPs, each with its latest (active) version's criteria and conditions.
Takes no flags.
List who you can act as
Full descriptionThe users you may act as, each with their organization and whether they have a LinkedIn account connected — you can only act as someone who does.
| Flag | Type | What it is for |
|---|---|---|
--search | string | Filter by name, email address or organization name. |
Act as another user
Full descriptionAct as another user from now on: every later call runs as them, on their LinkedIn seat and their organization.
| Flag | Type | What it is for |
|---|---|---|
--userrequired | string | The email address or user id to act as. |
Stop acting as another user
Full descriptionGo back to being yourself.
Takes no flags.
Send an InMail
Full descriptionSend an InMail (optional subject).
| Flag | Type | What it is for |
|---|---|---|
--targetrequired | jsonjson | |
--subject | string | |
--textrequired | string | |
--attachments | json arrayjson |
Send a connection invitation
Full descriptionSend a LinkedIn connection invitation (optional note) through the caller's account.
| Flag | Type | What it is for |
|---|---|---|
--targetrequired | jsonjson | |
--note | string |
Fetch a LinkedIn profile or company
Full descriptionFetch a LinkedIn person OR company through the caller's connected account — whichever the target addresses.
| Flag | Type | What it is for |
|---|---|---|
--targetrequired | jsonjson | |
--kind | profile|company | Override auto-detection. Required for a company addressed by universal name or numeric id. |
--refresh | boolean |
Add members to a list
Full descriptionAdd members to a list ({ asset, id, items }, ≤500 items).
| Flag | Type | What it is for |
|---|---|---|
--assetrequired | leads|companies | Which kind of list: 'leads' (people) or 'companies'. |
--idrequired | string | |
--itemsrequired | json arrayjson |
Create a list
Full descriptionCreate a named list — the campaign targeting unit.
| Flag | Type | What it is for |
|---|---|---|
--assetrequired | leads|companies | Which kind of list: 'leads' (people) or 'companies'. |
--namerequired | string |
Delete a list
Full descriptionSoft-delete a list by asset + id: it disappears from list_list with its memberships, the member leads/companies are untouched (they stay in the org pool, in their other lists, with their qualification state intact), and the name is immedia…
| Flag | Type | What it is for |
|---|---|---|
--assetrequired | leads|companies | Which kind of list: 'leads' (people) or 'companies'. |
--idrequired | string |
Get one list
Full descriptionOne list by asset + id: its name, live member count, and created date.
| Flag | Type | What it is for |
|---|---|---|
--assetrequired | leads|companies | Which kind of list: 'leads' (people) or 'companies'. |
--idrequired | string |
List lists
Full descriptionRead this org's lists of one asset, keyset-paginated, newest first, each with its live member count.
| Flag | Type | What it is for |
|---|---|---|
--assetrequired | leads|companies | Which kind of list: 'leads' (people) or 'companies'. |
--q | string | |
--cursor | string | |
--limit | integer |
Read a list's members
Full descriptionOne keyset page of a list's members ({ asset, id, q?, cursor?, limit? }), newest-added first.
| Flag | Type | What it is for |
|---|---|---|
--assetrequired | leads|companies | Which kind of list: 'leads' (people) or 'companies'. |
--idrequired | string | |
--q | string | |
--cursor | string | |
--limit | integer |
Remove members from a list
Full descriptionRemove members from a list ({ asset, id, memberIds }).
| Flag | Type | What it is for |
|---|---|---|
--assetrequired | leads|companies | Which kind of list: 'leads' (people) or 'companies'. |
--idrequired | string | |
--memberIdsrequired | json arrayjson |
Rename a list
Full descriptionRename a list ({ asset, id, name }).
| Flag | Type | What it is for |
|---|---|---|
--assetrequired | leads|companies | Which kind of list: 'leads' (people) or 'companies'. |
--idrequired | string | |
--namerequired | string |
Delete (retract) a sent message
Full descriptionRetract a message YOU sent, addressed by the chatId and message id that chat_messages returns.
| Flag | Type | What it is for |
|---|---|---|
--chatIdrequired | string | |
--messageIdrequired | string | The message's `id` from chat_messages. |
Edit a sent message
Full descriptionReplace the body of a message YOU sent, addressed by the chatId and message id that chat_messages returns.
| Flag | Type | What it is for |
|---|---|---|
--chatIdrequired | string | |
--messageIdrequired | string | The message's `id` from chat_messages. |
--textrequired | string |
Send a direct message
Full descriptionSend a LinkedIn direct message.
| Flag | Type | What it is for |
|---|---|---|
--chatId | string | Reply in this existing conversation (from chat_list). Use this, or `target`. |
--target | jsonjson | Open a NEW conversation with this person. Use this, or `chatId`. |
--textrequired | string | |
--attachments | json arrayjson | |
--clientToken | string |
A profile's recent posts
Full descriptionA page of a profile's recent posts (transient — not persisted).
| Flag | Type | What it is for |
|---|---|---|
--targetrequired | jsonjson | |
--cursor | string |
Search people (classic)
Full descriptionClassic LinkedIn people search — works WITHOUT a Sales Navigator seat.
| Flag | Type | What it is for |
|---|---|---|
--url | string | |
--keywords | string | |
--cursor | string | |
--limit | integer | Page size for paging (default 10). Classic search is clamped to 50 provider-side (Sales Nav allows 100). Set by "Load all", not by the agent. |
--filters | json arrayjson | |
--networkDistance | json arrayjson | Connection degree: 1 (1st), 2 (2nd), 3 (3rd+). LinkedIn native filter CONNECTIONS. |
--profileLanguage | json arrayjson | Profile languages as 2-letter ISO-639-1 codes (e.g. ["en","es"]). |
--openTo | json arrayjson | |
--connectionsOf | json arrayjson | Member ids whose connections to search within (from people.suggest). |
--followersOf | json arrayjson | Member ids whose followers to search within (from people.suggest). |
--advancedKeywords.firstName | string | |
--advancedKeywords.lastName | string | |
--advancedKeywords.title | string | |
--advancedKeywords.company | string | |
--advancedKeywords.school | string |
Search (Sales Navigator)
Full descriptionSearch LinkedIn Sales Navigator over people OR companies.
| Flag | Type | What it is for |
|---|---|---|
--category | people|companies | Search people (default) or companies. Some fields are valid for only one category. |
--keywords | string | LAST resort — matches noisily across all text. Prefer a structured filter for any title/industry/geography/size intent; use keywords only for a concept no filter captures. This is a BOOLEAN query, not a phrase: bare space-separated words are AND-ed (ALL must appear), so "fintech payments neobank" requires all three together and usually returns ZERO. For ALTERNATIVES, OR them, quote each, and ALWAYS wrap the OR group in parentheses: `("fintech" OR "payments" OR "neobank")`. The parentheses are MANDATORY — LinkedIn silently mis-parses an unparenthesized OR of 4+ terms and returns ~0. Quote multi-word phrases; combine groups with AND/NOT (e.g. `("fintech" OR "neobank") AND "payments"`). Operators must be UPPERCASE. |
--filters | json arrayjson | Id-resolved dimensions (location, industry, company, …). Same dimension repeated = OR; different dimensions = AND (each narrows the results). |
--cursor | string | Pass the cursor from a prior result to page. |
--limit | integer | Page size (max 100 for Sales Nav; default 10). Used when paging, not by the agent. |
--firstName | string | |
--lastName | string | |
--role.include | json arrayjson | |
--role.exclude | json arrayjson | |
--seniority.include | json arrayjson | |
--seniority.exclude | json arrayjson | |
--tenure | json arrayjson | Years at the current company in their current role, as {min,max} ranges. Years MUST be LinkedIn bucket breakpoints — valid min: 0, 1, 3, 6, 10; valid max: 1, 2, 5, 10 (buckets <1, 1-2, 3-5, 6-10, 10+). Any other value (e.g. min:5 or min:2) is rejected. So "5+ years" → {min:6}; "3+ years" → {min:3}; "3 to 5 years" → {min:3,max:5}. |
--tenureAtCompany | json arrayjson | Total years at the current company, as {min,max} ranges. Years MUST be LinkedIn bucket breakpoints — valid min: 0, 1, 3, 6, 10; valid max: 1, 2, 5, 10 (buckets <1, 1-2, 3-5, 6-10, 10+). Any other value (e.g. min:5 or min:2) is rejected. So "5+ years" → {min:6}; "3+ years" → {min:3}; "3 to 5 years" → {min:3,max:5}. |
--tenureAtRole | json arrayjson | Years in the current role, as {min,max} ranges. Years MUST be LinkedIn bucket breakpoints — valid min: 0, 1, 3, 6, 10; valid max: 1, 2, 5, 10 (buckets <1, 1-2, 3-5, 6-10, 10+). Any other value (e.g. min:5 or min:2) is rejected. So "5+ years" → {min:6}; "3+ years" → {min:3}; "3 to 5 years" → {min:3,max:5}. |
--companyHeadcount | json arrayjson | Size band of the person's current employer (people search). For a company's OWN size use `headcount`. Approximate "startup" with small buckets (["1-10","11-50","51-200"]). |
--companyType | json arrayjson | Ownership type of the person's current employer (people search; e.g. privately_held, public_company). A companies search has no company-type facet. |
--profileLanguage | json arrayjson | Profile languages as 2-letter ISO codes (e.g. ["en","es"]). |
--networkDistance | json arrayjson | Connection degree from the seat: 1 / 2 / 3 — valid for BOTH people and companies. The "GROUP" value (shared group) is PEOPLE only; do not use it on a companies search. |
--connectionsOf | json arrayjson | Member ids whose connections to search within. |
--changedJobs | boolean | Spotlight: only people who recently changed jobs. |
--postedOnLinkedin | boolean | |
--mentionedInNews | boolean | |
--followingYourCompany | boolean | |
--pastColleague | boolean | |
--sharedExperiences | boolean | |
--viewedYourProfileRecently | boolean | |
--viewedProfileRecently | boolean | |
--messagedRecently | boolean | |
--includeSavedLeads | boolean | |
--includeSavedAccounts | boolean | |
--hasJobOffers | boolean | Company search: only companies currently hiring. |
--headcount | json arrayjson | The company's OWN size band (companies search; the analog of people-search `companyHeadcount`). Approximate "startup" with small buckets (["1-10","11-50","51-200"]). |
--headcountGrowth.min | number | |
--headcountGrowth.max | number | |
--annualRevenue.currency | string | |
--annualRevenue.min | number | |
--annualRevenue.max | number | |
--followersCount | json arrayjson | Company follower count {min,max} ranges. Breakpoints — min: 1, 51, 101, 1001, 5001; max: 50, 100, 1000, 5000. |
--fortune | json arrayjson | Fortune ranking {min,max} ranges (e.g. Fortune 500). Breakpoints — min: 0, 51, 101, 251; max: 50, 100, 250, 500. |
--recentActivities | json arrayjson | Company signals: senior_leadership_changes and/or funding_events. |
--departmentHeadcount.department | json arrayjson | |
--departmentHeadcount.min | number | |
--departmentHeadcount.max | number | |
--departmentHeadcountGrowth.department | json arrayjson | |
--departmentHeadcountGrowth.min | number | |
--departmentHeadcountGrowth.max | number | |
--savedAccounts | json arrayjson | |
--savedSearchId | string | |
--recentSearchId | string | |
--lastViewedAt | number | |
--withinArea | number | |
--companyLists | json arrayjson | Scope a PEOPLE search to the companies in your own Kairon company lists (`list_list`, asset "companies"). The server expands each list to its companies' LinkedIn ids as a current_company filter — no per-company resolution, no 40-filter ceiling. NOT `account_lists`, which means Sales Navigator's own saved lists and will not match a Kairon list. People category only. |
Search by behavioural signal
Full descriptionFind people by what they DID, not by what their profile says — the behavioural counterpart to search_people / search_sales_navigator.
| Flag | Type | What it is for |
|---|---|---|
--signalrequired | posted_with_keyword|engaged_with_keyword|engaged_with_profile|recently_connected|viewed_my_profile | |
--config.keyword | string | |
--config.datePosted | past-24h|past-week|past-month | |
--config.firstDegreeOnly | boolean | |
--config.target.kind | person|company | |
--config.target.url | string | |
--cursor | string |
Flags are derived from each tool input schema, not written by hand, which is why they match the tool exactly. Three shapes get three treatments.
A string, number or boolean becomes --flag and takes its value literally. An enum shows its choices in the type column.
A tool input nests freely, so a nested field becomes --config.keyword rather than a flattened name that could collide with another tool field.
There is no honest flat spelling for "an array of either a member id or a URL", so those flags take JSON text. They are marked json in the table below.
Input is checked against the cached schema before any call, so a misspelled flag costs nothing and names itself: it tells you the option is unknown and suggests the one you meant.
--server <url>--json <json>--refresh-h, --help-v, --versionkairon list create --json '{"asset":"leads","name":"Q3"}'The result is JSON on stdout. Everything a human reads goes to stderr, so a pipe stays clean with no flags. A command that succeeds exits 0. A command that fails exits non-zero, writes nothing at all to stdout, and leads with a stable error code you can branch on rather than prose you would have to pattern-match.
kairon campaign stats --id camp_… | jq '.funnel'$ kairon list get --asset leads --id list_01… ; echo "exit=$?"
kairon list get failed: COMMON_NOT_FOUND
{
"code": "COMMON_NOT_FOUND",
"params": { "resource": "lead_list" }
}
exit=1For CI, a cron job or a container, there is no browser to open. Pass a token instead and the CLI needs no stored credentials at all.
KAIRON_TOKENKAIRON_API_URLKAIRON_CONFIG_DIRKAIRON_TOKEN=<access token> kairon whoamiKairon staff can act as any user; an owner or admin can act as a member of their own organization who does not outrank them. One command in, one command out, nothing to type in between.
kairon impersonate list --search acmekairon impersonate start --user [email protected]kairon chat listkairon impersonate stopSigning in registers a fresh client each time, so your terminal, your assistant and your cron each have their own. Acting as someone here does not redirect the 3am job.
Not 60 minutes after it started. Working never interrupts you; leaving for lunch ends it.
One line naming who you are acting as. stdout is untouched, so a pipe keeps working.
Acting as a seatless user would reach nothing, so impersonate list tags each candidate with whether they have one.
The account has no LinkedIn account connected, or the plan is not active. Connect one in Kairon and run kairon whoami again. Commands act as that seat, so nothing works without it.
Commands come from the server, cached per server URL under ~/.kairon/tools/, and the cache has no expiry because a tool set changes on deploy and not on a schedule. Run the command again with --refresh to re-fetch it.
Access tokens last 30 days and refresh silently. When the refresh token finally expires after 90 days you get one sentence and the command to run.
kairon logout deletes the local credentials. The server issues opaque tokens with no revocation endpoint, so the access token stays valid there until it expires. The command says so rather than implying a revocation that did not happen.