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 canonical 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. The legacy routes with no canonical successor, such as sequence images, AI variables or thread opens, have no command: reach them with kenso api <METHOD> <path>.
Install
On macOS or Linux, with or without Node, run the install script: fetch it with curl -fsSL and pipe it to sh. It installs a standalone build that brings its own Node.js, checks the download against the release's SHA256SUMS, puts the CLI in ~/.local/share/kenso and links ~/.local/bin/kenso. Run it again to update.
With Homebrew, on macOS or Linux, the same standalone build:
brew install ken-technology/tap/kensobrew upgrade kenso updates it.
With Node 22 or newer, on any system, Windows included:
npm i -g kenso
kenso --versionTo run it once without installing, use npx kenso --version. On an older Node, kenso stops with one line that says so.
Every way to install:
| Way | Systems | Needs |
|---|---|---|
| Install script, above | macOS, Linux (glibc) | Nothing |
| Homebrew, above | macOS, Linux | Homebrew |
| npm, above | Any | Node 22 or newer |
Standalone build: unpack it and put its bin folder on your PATH | macOS, Linux, Windows | Nothing |
The standalone builds are at https://downloads.ken.so/desktop/cli/<version>/, one per system: kenso-<version>-darwin-arm64.tar.gz, darwin-x64, linux-arm64, linux-x64 and kenso-<version>-windows-x64.zip, with their SHA256SUMS. https://downloads.ken.so/desktop/cli/latest.yml names the newest version. The builds come out nightly and Homebrew follows them, so a command added that day reaches npm first.
Tab completion
Tab completes resources, actions and flags once you install the script for your shell. The script asks kenso for the candidates on each Tab, so it stays right as the CLI updates: install it once.
# zsh: add this line to ~/.zshrc
source <(kenso completion zsh)
# bash: add this line to ~/.bashrc (on bash 3.2, the macOS default, use: eval "$(kenso completion bash)")
source <(kenso completion bash)
# fish: save the script once
kenso completion fish > ~/.config/fish/completions/kenso.fishUpdate notice
When a newer version is out, kenso says so on stderr after the command's own output, at most once a week: kenso 0.1.40 is out (you have 0.1.35): npm i -g kenso@latest. It checks registry.npmjs.org at most once every 7 days and never delays a command by more than about a second. A standalone build checks latest.yml on downloads.ken.so instead and names its own update: the install script, or brew upgrade kenso when Homebrew installed it. It stays quiet when stderr is not a terminal, in CI (CI set) and under a coding agent. Set KENSO_NO_UPDATE_NOTIFIER=1 to turn it off.
60-second quickstart
- Create an API key in app.ken.so at Settings > Integrations > API keys.
- Save the key, pick a workspace, then plan and apply a CSV import:
echo $KEY | kenso auth login --with-key
kenso workspace list --search 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 --yesworkspace 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 callreaches MCP-only tools, such as skills, from the shell.
Docs
Every page is in the package and prints offline with kenso docs <topic>.
| Page | Topic | What it covers |
|---|---|---|
| Authentication | auth | API keys, browser login, profiles, workspaces, doctor |
| Leads | leads | Import, update, remove, pause, tag and export leads, with recipes |
| Batch runs | batch | Dry run and apply, run folders, results files, resume, rate limits, --each |
| Output and errors | output-and-errors | The output contract, error JSON, error codes, exit codes, live streams |
| CRM (beta) | crm | Accounts, people, opportunities and CRM sync |
| Studio (beta) | studio | Pull, push, validate, preview and fill templates |
| Agent work (beta) | work | My agent: your own coding agent writes Kenso's AI work with kenso work run, or pull and submit |
| Webhooks | webhooks | Build a webhook handler locally: kenso webhooks listen --forward-to, trigger, the signature |
| Developer sandbox | sandbox | kenso sandbox: a workspace of your own where sends are simulated, its test key, the reserved test leads |
| Connect accounts | connect | kenso connect: an inbox, calendar, CRM, GitHub or other OAuth account, signed in by the person in a browser |
| Coding agents | agents | Claude Code, Codex, Cursor, the Agent Skill, environment variables, sandboxes |
| Command reference | reference | Every command with its flags, generated from the CLI at build time: kenso docs reference, or docs/reference.md in the installed package |
kenso docs
kenso docs leadsFor 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.