# Set up Kenso

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

You are an AI agent setting up Kenso, the outbound platform, for a person. Run every step below yourself, in order, and stop only where a step says the person acts. When you finish, tell the person what is set up and what is left.

## What only the person can do

- Approve the sign-ins in their browser: the CLI login (step 2) and the MCP server (step 4).
- Create a Kenso account if they have none, at https://app.ken.so/get-started.
- Anything that sends email or spends money: a paid plan, domains or inboxes, connecting mailboxes, importing leads for real or launching a campaign. Nothing on this page does any of it.

## 1. Install the CLI

```sh
npm i -g kenso
kenso --version
```

It needs Node 22 or newer. Without it, on macOS or Linux, fetch the [install script](/install.sh) with `curl -fsSL` and pipe it to `sh`: it installs a build that brings its own Node.js. If a global install is not possible, run each command below as `npx -y kenso@latest <command>`.

## 2. Sign in

```sh
kenso auth login
```

It opens a browser sign-in (add `--no-browser` to print the link instead). Give the person the link and the code it prints, and wait while they approve. With an API key from https://app.ken.so/settings/api-keys instead: `printf '%s' "$KENSO_API_KEY" | kenso auth login --with-key`. Never put a key in a flag or a file you commit.

## 3. Pick the workspace

```sh
kenso workspace list
kenso workspace use <workspaceId>
```

With one workspace there is nothing to pick. With several, ask the person which one, unless they already said.

## 4. Connect the Kenso MCP server and skill

```sh
kenso agent setup
kenso agent setup -y
```

The first command prints the plan and changes nothing; the second installs the kenso-cli skill and registers `https://mcp.ken.so/mcp` with Claude Code, Codex, Cursor, Gemini CLI or OpenCode. Each client's `next` in the output says how the person signs in to the MCP server once (OAuth in the browser). `kenso agent setup --status --json` reports what is set up.

## 5. Check the setup

```sh
kenso doctor
```

It checks Node, the config, the API and the key. Follow the `next` of any check that fails.

## 6. Try an import without sending anything

```sh
kenso campaigns list --limit 5
kenso contacts import --template
```

Write `sample-leads.csv` with that header and two made-up rows on example.com addresses, then run the import as a dry run on one of the campaigns:

```sh
kenso contacts import --campaign <campaignId> --file sample-leads.csv --dry-run
```

It checks every row and prints the plan and the credit estimate. Do not run it with `--yes`: real leads are the person's call. If the workspace has no campaign yet, skip this step and say so.

## Done

Report to the person: the CLI version, the workspace, the MCP sign-in still to do in each agent (if any), and what `kenso doctor` said.

## Writing code against the API

- Base URL `https://api.ken.so/v1`; OpenAPI at https://api.ken.so/v1/docs/openapi.json.
- Send `Authorization: Bearer <key>`, `Ken-Version: 2026-11-02` and `X-Ken-Workspace-Id: <id>` on every request. Without the workspace header, a key that reaches more than one workspace gets `400 workspace_required`.
- Reference and guides: [/docs.md](/docs.md). Skills for agents: [/.well-known/skills/index.json](/.well-known/skills/index.json), including kenso-api for writing code against it.
- For the person's repo: the AGENTS.md section in [/cli/agents.md](/cli/agents.md).
