Kenso CLI

The Kenso CLI (kenso) is the command line for Kenso. It does bulk work in your Kenso workspace from files: add thousands of leads to a campaign, update or clean them up, import accounts and people, and build Studio templates. It is made for coding agents (Claude Code, Codex, Cursor) and the people who drive them: JSON on stdout, fixed exit codes, a dry run before every bulk write, and runs you can resume.

Every API operation a workspace member can call is also a command, such as kenso campaigns list or kenso tags create. So the CLI reaches what the Kenso MCP reaches, straight against https://api.ken.so.

Install

You need Node 22 or newer.

npm i -g kenso
kenso --version

To run it once without installing, use npx kenso --version.

60-second quickstart

1. Create an API key in app.ken.so at Settings > Integrations > API keys.
2. Save the key, pick a workspace, then plan and apply a CSV import:

echo $KEY | kenso auth login --with-key
kenso workspace list --q acme
kenso workspace use 1234
kenso campaigns list --limit 5
kenso contacts import --campaign 812 --file leads.csv --dry-run
kenso contacts import --campaign 812 --file leads.csv --yes

workspace list and workspace use are only needed when your key reaches more than one workspace.

The dry run reads the file, maps the columns, checks every row, asks Kenso for a credit estimate, and writes nothing. It prints the plan, with the exact apply command in next:

{"run":"r_tdi5cdnx","dryRun":true,"command":"contacts import","rows":4,"valid":2,"invalid":2,"chunks":1,"chunkSize":1000,"campaignId":812,"mapping":{"Email":"email","First Name":"firstName","Last Name":"lastName","Company":"companyName","Pain Point":"customVariables.pain_point"},"customVariableKeys":["pain_point"],"estimate":{"kind":"leads","totalMillicredits":2000,"availableMillicredits":500000,"sufficient":true},"credits":{"needed":2,"available":500,"sufficient":true},"next":"kenso contacts import --campaign 812 --file leads.csv --yes","plan":"/home/you/.kenso/runs/r_tdi5cdnx/plan.json","invalidRows":"/home/you/.kenso/runs/r_tdi5cdnx/invalid.csv"}

The apply sends the rows and prints one summary. Every input row has one line in results.csv:

{"run":"r_tdi5cdnx","rows":4,"ok":0,"created":1,"updated":0,"skipped":{"duplicate":1},"failed":0,"notFound":0,"invalid":2,"changed":1,"results":"/home/you/.kenso/runs/r_tdi5cdnx/results.csv","resultsNdjson":"/home/you/.kenso/runs/r_tdi5cdnx/results.ndjson","invalidRows":"/home/you/.kenso/runs/r_tdi5cdnx/invalid.csv","resumed":false,"durationMs":1840,"campaignId":812,"notSendable":0}

This run exits 5 because two rows were invalid: open invalid.csv to see why, fix those rows, and import them again. Running the same command again is safe: an email that is already in the campaign comes back updated or skipped, never as a second lead.

CLI or MCP

• Use the CLI for volume: anything that starts from a file, anything over about 50 records, anything you may need to rerun or resume. Records never pass through the model's context: the agent passes a file path and reads a short summary.
• Use the MCP for conversation and single records: look up a campaign, draft a reply, read a report. The MCP is at https://mcp.ken.so/mcp, signs in with OAuth and needs no install (connection guide).
• Both use the same API and the same permissions. kenso mcp call reaches MCP-only tools, such as skills, from the shell.

Docs

Every page is in the package and prints offline with kenso docs <topic>.

kenso docs
kenso docs leads

For machine-readable help, run kenso describe: it prints every command, its flags and its body schema as JSON.

Every command and flag: run kenso describe <resource> <action> or kenso docs reference.