Skip to Content

Kenso CLI

View as Markdown

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/kenso

brew upgrade kenso updates it.

With Node 22 or newer, on any system, Windows included:

npm i -g kenso
kenso --version

To 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:

WaySystemsNeeds
Install script, abovemacOS, Linux (glibc)Nothing
Homebrew, abovemacOS, LinuxHomebrew
npm, aboveAnyNode 22 or newer
Standalone build: unpack it and put its bin folder on your PATHmacOS, Linux, WindowsNothing

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.fish

Update 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

  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 --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 --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>.

PageTopicWhat it covers
AuthenticationauthAPI keys, browser login, profiles, workspaces, doctor
LeadsleadsImport, update, remove, pause, tag and export leads, with recipes
Batch runsbatchDry run and apply, run folders, results files, resume, rate limits, --each
Output and errorsoutput-and-errorsThe output contract, error JSON, error codes, exit codes, live streams
CRM (beta)crmAccounts, people, opportunities and CRM sync
Studio (beta)studioPull, push, validate, preview and fill templates
Agent work (beta)workMy agent: your own coding agent writes Kenso's AI work with kenso work run, or pull and submit
WebhookswebhooksBuild a webhook handler locally: kenso webhooks listen --forward-to, trigger, the signature
Developer sandboxsandboxkenso sandbox: a workspace of your own where sends are simulated, its test key, the reserved test leads
Connect accountsconnectkenso connect: an inbox, calendar, CRM, GitHub or other OAuth account, signed in by the person in a browser
Coding agentsagentsClaude Code, Codex, Cursor, the Agent Skill, environment variables, sandboxes
Command referencereferenceEvery 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 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.

On this page