# Kenso CLI

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

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](/install.sh): 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:

```bash
brew install ken-technology/tap/kenso
```

`brew upgrade kenso` updates it.

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

```bash
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:

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

```bash
# 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:

```bash
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`:

```json
{"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`:

```json
{"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](/mcp)).
- **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>`.

| Page | Topic | What it covers |
|---|---|---|
| [Authentication](/cli/auth) | `auth` | API keys, browser login, profiles, workspaces, `doctor` |
| [Leads](/cli/leads) | `leads` | Import, update, remove, pause, tag and export leads, with recipes |
| [Batch runs](/cli/batch) | `batch` | Dry run and apply, run folders, results files, resume, rate limits, `--each` |
| [Output and errors](/cli/output-and-errors) | `output-and-errors` | The output contract, error JSON, error codes, exit codes, live streams |
| [CRM (beta)](/cli/crm) | `crm` | Accounts, people, opportunities and CRM sync |
| [Studio (beta)](/cli/studio) | `studio` | Pull, push, validate, preview and fill templates |
| [Agent work (beta)](/cli/work) | `work` | My agent: your own coding agent writes Kenso's AI work with `kenso work run`, or pull and submit |
| [Webhooks](/cli/webhooks) | `webhooks` | Build a webhook handler locally: `kenso webhooks listen --forward-to`, `trigger`, the signature |
| [Developer sandbox](/cli/sandbox) | `sandbox` | `kenso sandbox`: a workspace of your own where sends are simulated, its test key, the reserved test leads |
| [Connect accounts](/cli/connect) | `connect` | `kenso connect`: an inbox, calendar, CRM, GitHub or other OAuth account, signed in by the person in a browser |
| [Coding agents](/cli/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 |

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

## More for developers

- [API docs](/docs)
- [MCP server](/mcp)
- [Interactive API reference](https://developer.ken.so/reference/)
- [Changelog](/docs/changelog)
