# CRM (beta)

> **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 CRM commands work on Kenso's Accounts lane: accounts (companies), the people on them, and opportunities. They are beta: they need the `accounts` feature flag on your workspace (opportunities need `opportunities`, CRM sync needs `ingestion`). Help and `kenso describe` hide them until your workspace has the flag; `--all-commands` shows them.

| Command | What it does |
|---|---|
| `accounts import` | Create accounts from a CSV or JSONL file. Research is charged per created account |
| `people import` | Create or match people from a file, optionally onto accounts |
| `import accounts <file.csv>`, `import people <file.csv>`, `import deals <file.csv>` | Import a CSV export of another CRM, up to 50,000 rows: Kenso proposes the mapping, you approve once, it runs in the background and can be undone for 30 days |
| `accounts update --each`, `people update --each`, `opportunities update --each` | Edit many records from a file, one call per row |
| `accounts bulk-update`, `people bulk-update`, `opportunities bulk-update` | Set the same fields on many records at once, by ids or by a filter, with a preview first. Needs `bulk_edit` too |
| `accounts bulk-delete`, `people bulk-delete`, `opportunities bulk-delete` | Delete many records at once, by ids or by a filter, with a preview first. Not undone. Needs `bulk_edit` too |
| `changes list`, `get`, `rows`, `apply`, `cancel`, `undo` | Follow a bulk change, read what each record got, stop it, or put the old values back for 30 days |
| `accounts write-research`, `people write-research` | Store research you gathered as a record's latest research, free. `--each` writes many |
| `opportunities move <id> [--stage <key>] [--pipeline <pipelineId>] [--reason <key>]` | Move a deal to a stage or another pipeline, with its won or lost reason; a field the stage asks for never stops it |
| `opportunities stage-history <id>` | A deal's stage history: each stage, when, who moved it and how long it sat there |
| `notes list`, `notes add`, `notes edit`, `notes delete` | Notes and comments on accounts, people and deals (needs `record_notes`) |
| `deleted-accounts list`, `accounts restore <id>` | The accounts deleted in the last 30 days, and bringing one back |
| `accounts duplicates`, `accounts merge <id> --into <id>`, `accounts merges list` | The pairs that look like one company, merging a pair, and the log of merges |
| `export <accounts\|people\|deals>` | The list as CSV: everything, a saved Accounts view, or what the filters match |
| `capture status` | Your captured mailbox, its backfill progress and what teammates see of a captured email. Needs the `crm_capture` flag |
| `capture connect` | Turn capture on for your own mailbox. `--private` starts it hidden from teammates; `--provider google` prints a sign-in link when no account is connected yet |
| `capture private on\|off` | Hide your captured email from teammates, or show it again. Email only: meetings stay visible. `--thread <id>` sets the switch for one thread |
| `capture thread <threadId>` | One captured email thread: subject, people, time, Ken's summary, and each body you may open. The id is `capturedThread.id` on a timeline row |
| `capture sync` | Read your captured mailbox now, instead of waiting for the next two-minute poll. Prints what the pass read, logged and created |
| `capture disconnect` | Turn capture off and delete your stored email bodies. Asks first; `--yes` skips the question |
| `capture teammates-see summary\|full_email` | Workspace admin: what teammates see of captured email |
| `pipelines stage-rules` | List or set the fields a deal should have in each stage |
| `opportunity-reasons get`, `opportunity-reasons replace` | List or edit why deals are lost and won |
| `layouts show\|set\|reset <object>` | How every account, person or deal page in the workspace lays out its fields: header, rail sections and hidden fields (needs `record_layout`) |
| `crm-connections`, `crm-imports`, `crm-sync-issues` | Read and run CRM sync. Connecting a CRM stays in the app |
| `tasks add`, `tasks done`, `tasks assign`, `tasks queue` | Add a to-do for a member on an account, person or deal, complete it, hand it on, or read your open work (needs `tasks`) |

Import accounts first, then people: `people import` never creates an account.

## Import accounts

```bash
kenso accounts import --file accounts.csv
kenso accounts import --file accounts.csv --yes
```

```csv
name,domain,industry,employeeCount
Acme,acme.io,Software,120
Globex,globex.com,Manufacturing,"1,200"
```

- **Columns** map by name, ignoring case, spaces and dashes: `name` (or `company`, `companyName`, `accountName`), `domains` (several, split on `,` or `;`) or one `domain` (or `website`, `companyDomain`), `industry`, `employeeCount`, `hqLocation`, `linkedinUrl`, `stage`, `angle`, `whyNow`, `fitScore`, `fundingRound`, `cadenceDays`, `ownerMemberId`, `kenCompanyId`, `sendsFromInboxId`, `sendsFromLinkedInAccountId` and `source`.
- **A domain is required.** A file with no domain column is a usage error, and a row without a domain is `invalid` (`domain_required`).
- **The dry run prices the research.** It asks for a credit estimate per 1,000 accounts and puts the sum in the plan: `kind`, `accountCount`, `totalMillicredits`, `availableMillicredits` and `sufficient`.
- **Rows go 100 per call** to `POST /v1/accounts/bulk-create`.

Each row comes back `created` (`id` is the new account; its research is queued, `researchQueued`, or waits for credits, `researchWaitingCredits`), `skipped` with reason `domain_taken` (already an account; `id` is that account) or `failed` (`reason` is the API's code, `error` names the field; an item Kenso failed to save is sent once more first). Rerunning the same file is safe: accounts that exist come back `domain_taken`.

## Import people

```bash
kenso people import --file people.csv
kenso people import --file people.csv --find-emails --yes
kenso people import --file people.jsonl --dry-run
```

```csv
fullName,email,title,accountDomain,role
Ann Lee,ann@acme.io,VP Sales,acme.io,champion
Bob Ray,,CTO,acme.io,
```

- **Columns** map by name, ignoring case, spaces and dashes: `email`, `fullName` (or `name`), `firstName`, `lastName`, `title`, `linkedinUrl` (or `linkedin`, `profileUrl`), `accountDomain` (or `domain`, `website`, `companyDomain`), `accountId`, `role` and `priority`. Other columns are ignored with one warning.
- **A person needs a name:** `fullName`, or `firstName`, `lastName` or both (the CLI joins them). A row with none of them is `invalid` (`name_required`).
- **To put a person on an account,** give `accountDomain` or `accountId`. A row with both sends only `accountId`.
- **`--find-emails`** queues an email find (charged in credits) for each person without an email.
- **Rows go 200 per call** to `POST /v1/people/batch`.

People already in the workspace are matched by email, then LinkedIn URL, so running the same file again creates nobody twice. A row comes back `created` (a new person), `updated` (an existing person added to the account), `skipped` with reason `already_on_account`, `matched` (no account asked) or `previously_removed`, or `failed`: `account_not_found` saves the person without an account (import the account, then rerun to place them), any other reason is the API's. The summary adds `matched`, `addedToAccounts` and `emailFindsQueued`.

## List and search accounts

`accounts list` and `accounts search` sort and page on the server, so they reach every account in the workspace, however many there are.

```bash
kenso accounts list --sort score:desc --limit 100          # one page; the output's next: line is the following one
kenso accounts list --sort score:desc --limit 100 --all    # every page, to the end
kenso accounts search --search hiring --sort latestSignalAt:desc --data '{"qFields": ["name", "latestSignal"]}'
kenso accounts search --limit 1 --data '{"countBy": ["stage"]}'   # how many accounts sit in each stage
kenso accounts search --data '{"where": {"match": "all", "conditions": [{"field": "tier", "operator": "is", "values": ["1"]}]}, "sort": "tier,-pipelineAmount"}' --all
kenso accounts search --data '{"where": {"match": "all", "conditions": [{"field": "hqLocation", "operator": "contains", "values": ["Germany"]}]}}' --all
# tier 1 accounts with no meeting in 30 days: none since then, or none ever
kenso accounts search --data '{"where": {"match": "all", "conditions": [{"field": "tier", "operator": "is", "values": ["1"]}, {"match": "any", "conditions": [{"field": "lastMeeting", "operator": "older_than_days", "values": ["30"]}, {"field": "lastMeeting", "operator": "is_empty"}]}]}}' --all
```

- **`--sort`** takes up to 3 comma-separated keys, each `field` (ascending), `field:asc` or `field:desc`. The API's `-field` form needs the equals sign here, `--sort=-score`, because a value that starts with a dash reads as a flag. Fields: `createdAt`, `name`, `score`, `tier` (ascending is tier 1 first), `latestSignalAt`, `committee`, `pipelineAmount`, `nextTouchAt`, `lastTouchAt`. An account with no value for a key comes last in both directions. The default is `-createdAt`.
- **`--limit`** is 1 to 1000 (default 50). `--cursor` takes the previous page's `nextCursor` with the same filters and sort; `--all` follows the cursors for you.
- **`--search`** (also `--q`) matches the name or a domain.
- **Lists and objects go in `--data`** on `search`, as the API takes them (`kenso describe accounts search`); a flag beside it sets or replaces one key:
  - `qFields` picks where the search text looks: `name`, `domain`, `latestSignal` (the latest signal's title).
  - `countBy` (`stage`, `stageGroup`) adds `counts` to the output: every value with the number of matching accounts that hold it, whatever the page. The output is then one object: `data`, `pagination` and `counts`.
  - `filters` and `where` narrow the accounts.

An account's timeline pages the same way. `kenso accounts activity 812` returns the newest 100 earlier rows and, when older ones exist, `data.nextCursor`. Pass it back as `--cursor` (with the same `--category`) for the rows before them, until a page comes without one.

## Edit accounts, people and opportunities

To set the same fields on many records, use `bulk-update` (below; it needs the `bulk_edit` flag). When every row gets its own values, or the workspace has no `bulk_edit`, run the generated `update` command once per row with `--each`. Columns are the command's flags by API name or flag name, and the id column fills the route:

```bash
kenso accounts update --each accounts-edit.csv --dry-run   # then the same with --yes
kenso people update --each people-edit.csv --dry-run
kenso opportunities update --each deals.csv --dry-run
```

```csv
accountId,stage,ownerMemberId,overwritePinned
501,engaged,42,true
502,customer,42,true
```

A row that changes a field someone pinned in the app fails as a whole (`409 conflict`, `pinned_by_user`: nothing on that record changes, the other fields of the row included), unless the row sets `overwritePinned` to `true` (or you pass `--overwrite-pinned`, only with the person's OK). Every flag of an update command: `kenso accounts update --help`.

## Change many accounts at once

```bash
kenso accounts bulk-update --filter '{"filters":[{"field":"stage","operator":"is","values":["new"]}]}' --set owner=42 --dry-run
kenso changes apply --change-id 31
kenso accounts bulk-update --ids 812,813 --set stage=engaged --set tier=2 --yes
kenso changes get --change-id 31
```

`accounts bulk-update` sets the same fields on every account you name: `--ids` (1,000 at most), everything a `--filter` matches (the body `kenso accounts search --data` takes: `filters`, `where`, `q`; up to 50,000), or `--all`. A filter that holds only options and no condition (`--filter '{"includeImportOnly":true}'`) takes `--all` beside it. `--exclude-ids` leaves some of a filter's accounts out. `--set field=value` takes `ownerMemberId` (or `owner`), `stage`, `tierOverride` (or `tier`), `industry`, `fundingRound`, `employeeCount`, `hqLocation` and `cadenceDays`, and a custom field as `custom.<key>` (`--set custom.region=EMEA`; `kenso api GET '/v1/fields?object=account'` gives the keys); a value of `null` clears the field. A text field's value is sent as you type it (`--set hqLocation=10001` is the text "10001"); a custom field's type is not known to the CLI, so quote its text when it reads as a number or as true or false: `--set 'custom.code="10001"'`. Use `accounts update --each` when every row gets its own values.

It makes a change set: the accounts it names and, for each, the field, its value before and its value after. Without `--yes` (or with `--dry-run`) it previews: it prints `count` and a `sample`, writes nothing, and `next` is the `kenso changes apply` command that writes exactly those accounts. With `--yes` it writes in the background and waits (`--timeout`, default 10m), then prints the change with its `counts`: `applied`, `unchanged` (already had the value), `conflict` (the account changed after the preview, so it was left alone) and `failed` (for example `pinned`: a person set the field by hand; `--overwrite-pinned` replaces it). Exit 5 when some accounts failed or conflicted. It needs the `bulk_edit` flag as well as `accounts`.

`kenso accounts bulk-update` used to be the generated command for the route's older one-field body, which sets one `accountType` on up to 500 accounts and needs only `accounts`. The route still takes that body, but this command no longer sends it: use `kenso accounts update --each` with an `accountType` column, or `kenso api POST /v1/accounts/bulk-update --data '{"accountIds":[812,813],"accountType":"lost"}'`.

`people bulk-update` and `opportunities bulk-update` work the same way. People take `--set` for `ownerMemberId` (or `owner`), `leadStatus`, `title`, `seniority`, `department` and `location`, and a `--filter` of `kenso people search --data` fields (`leadStatus`, `roles`, `tagIds`, `q` and the rest). Deals take `stage` (a live stage key), `ownerMemberId` (or `owner`), `closeDate` (or `close`), `amount`, `dealType` and `nextStep`, and a `--filter` of `kenso opportunities search --data` fields (`filters`, `accountId`, `q`):

```bash
kenso opportunities bulk-update --filter '{"filters":[{"field":"stageCategory","operator":"is","values":["open"]}]}' --set stage=proposal --dry-run
kenso people bulk-update --ids 501,502 --set owner=42 --yes
```

### Delete many records at once

```bash
kenso people bulk-delete --filter '{"onAccount":"none","leadStatus":["disqualified"]}' --dry-run
kenso changes apply --change-id 32
kenso opportunities bulk-delete --ids 71,72,73 --yes
```

`accounts bulk-delete`, `people bulk-delete` and `opportunities bulk-delete` name their records the way `bulk-update` does (`--ids`, `--filter`, `--all`, `--exclude-ids`) and take no `--set`. Without `--yes` they preview: `count`, a `sample`, and `next` is the `kenso changes apply` command that deletes exactly those records. The API itself previews a delete whose body leaves `dryRun` out, so `--yes` sends `dryRun: false`. Each record is deleted as its own `delete` command deletes it, so one that cannot be deleted (a person still on an account) is counted as `failed` and the rest go on. A delete is not undone with `kenso changes undo`.

### Follow, stop and undo a change

```bash
kenso changes list --object accounts
kenso changes rows --change-id 31 --status conflict,failed
kenso changes cancel --change-id 31
kenso changes undo --change-id 31
```

`changes list` shows the workspace's bulk changes, newest first, whoever made them. `changes rows` lists a change's records with the value before (`from`) and after (`to`) and a `status`; `--status conflict,failed` reads what a change missed. `changes cancel` drops a preview or stops a change that is still writing; what it already wrote stays. `changes undo` puts the old value back on every record that still holds the value the change wrote, for 30 days after it was applied (`undoUntil`). A record someone changed again since keeps its newer value: `counts.undone` is how many went back, `counts.applied` how many still hold the change. Undo answers `409 invalid_state` with `undo_expired`, `still_running`, `nothing_applied` or `not_undoable` when there is nothing it can put back.

## Search opportunities

`kenso opportunities search` works as `accounts search` does: it takes `--search`, `--sort`, `--limit`, `--cursor`, `--all`, and its lists in `--data`.

```bash
kenso opportunities search --data '{"filters": [{"field": "stageCategory", "operator": "is", "values": ["open"]}]}' --all
kenso opportunities search --data '{"filters": [{"field": "ownerMemberId", "operator": "is", "values": ["none"]}, {"field": "closeDate", "operator": "is", "values": ["past_due", "next_30_days"]}]}'
kenso opportunities search --limit 1 --data '{"countBy": ["stage", "ownerMemberId"]}'   # how many opportunities hold each value
```

- **`filters`** is a list of `{field, operator, values}`, all of which must hold. Fields: `stage` (a stage key), `stageCategory` (`open`, `won`, `lost`), `ownerMemberId`, `closeDate` (`past_due`, `next_30_days`, `later`, `none`) and `sourceCampaignId`. `operator` is `is` or `is_not`; the values of one condition are OR. `none` in `values` matches an opportunity with no owner, no source campaign or no close date.
- **`countBy`** takes the same field names and adds `counts` to the output: per field, every value with the number of matching opportunities that hold it.
- `--account-id` keeps the search to one account. `closeDate` counts days in the member's app time zone.

One person's deals, meetings and campaign contacts, as their person page lists them:

```bash
kenso opportunities list --person-id 9001   # the deals they are on, or are the primary person of
kenso meetings list --person-id 9001        # the meetings they attend, among the ones you can see
kenso contacts list --person-id 9001        # their contact in each campaign they are in
```

## Write research you gathered

`accounts write-research` and `people write-research` store research you gathered outside Kenso as the record's latest research (`PUT /v1/accounts/{accountId}/research`, `PUT /v1/people/{personId}/research`). The Research tab shows it like a Ken run, with `trigger: agent` and `researchedAt` now. Nothing is charged, and no account or person field changes: set an account's own `fitScore`, `whyNow` or `angle` with `accounts update`. They need the `accounts_research` flag and accounts edit.

The body is the research block `accounts get --expand research` (or `people get-research`) returns, without its read-only fields: leave out `id`, `status`, `trigger`, `errorCode`, `researchedAt`, `isStale` and `appliedPrompt` (for a person also `mode`, `requestedAt`, `researchedMode`, `firecrawlCredits` and `webNote`), or the write fails with `unknown_field`. Pass it with `--data @file`:

```bash
kenso accounts write-research --account-id 501 --data @acme-dossier.json
kenso people write-research --person-id 9001 --data @jane.json
```

```json
{
  "tagline": { "text": "Payroll for EU contractors", "sourceUrls": ["https://acme.example"] },
  "description": { "text": "Acme runs payroll and compliance for companies hiring contractors in 30 EU countries.", "sourceUrls": ["https://acme.example"] },
  "links": { "website": "https://acme.example" },
  "whyNow": { "text": "Raised a $40M Series B in October", "sourceUrls": ["https://news.example/acme-b"], "date": "2026-10" },
  "fitScore": 82,
  "angle": "Lead with contractor onboarding time."
}
```

Many records: one JSONL line per record, with the id next to the block's fields. Nested objects are sent as written. Use JSONL, not CSV: the block's fields are objects and lists, which a CSV cell cannot carry.

```bash
kenso accounts write-research --each dossiers.jsonl --dry-run   # then the same with --yes
kenso people write-research --each people-research.jsonl --yes --concurrency 8
```

```jsonl
{"accountId": 501, "tagline": {"text": "Payroll for EU contractors"}, "links": {"website": "https://acme.example"}}
{"accountId": 502, "description": {"text": "Cloud cost tooling for retailers."}, "links": {"website": "https://beta.example"}}
```

A row fails as a whole with the API's code: `validation_failed` (an unknown field is `unknown_field`, and `error.details` names every bad field), `research_in_progress` (`409`: Ken is researching that record now, write it again once the run ends; an account run waiting for credits counts too: it runs once the workspace has credits, and the write stays refused until that run ends) or `not_found`. Rerunning a file is safe: each write replaces the record's research shown.

## CRM sync

CRM sync has generated commands only: read connections, preview, start an import, and work through sync issues. Connect the CRM itself in the app.

```bash
kenso crm-connections list
kenso crm-connections get --connection-id 7
kenso crm-imports create --connection-id 7 --dry-run
kenso crm-sync-issues list --connection-id 7 --all
```

Run `kenso crm-connections --help` (or add `--all-commands` when the actions are hidden) to see every action.

## Pipelines

A workspace with the `pipelines` flag on can run several deal pipelines, each with its own stages. These are generated commands (beta):

```bash
kenso pipelines list
kenso pipelines list --query "[].{id: id, name: name, default: isDefault, stages: stages[].key}"
kenso pipelines get --pipeline-id 5
```

`list` prints every pipeline in display order, archived ones included: `id`, `name`, `routingRule` (the one sentence Ken reads to decide whether a new deal belongs there), `isDefault`, `isArchived`, `position`, `opportunityCount`, `amountTotal` and `stages`, each stage as `kenso opportunity-stages list` prints it. A stage key is unique in the workspace, across pipelines, so a deal's `stage` names its pipeline and its `pipelineId` repeats it. The first read turns the workspace's stage list into its default pipeline, named Sales, with every deal in it. The same rows as the MCP's `pipelines(operation="list")`.

Shaping them needs the `workspace_settings` permission:

```bash
kenso pipelines create --name Renewals --routing-rule "The account is already a customer" --data '{"stages": [{"label": "Up for renewal", "category": "open"}, {"label": "Won", "category": "won"}, {"label": "Lost", "category": "lost"}]}'
kenso pipelines update --pipeline-id 6 --name Expansion --position 0
kenso pipelines update --pipeline-id 6 --data @stages.json
kenso pipelines archive --pipeline-id 6
kenso pipelines restore --pipeline-id 6
kenso pipelines propose --description "upsells and renewals for customers"
```

- **`create`** takes a unique `name`, the pipeline's `stages` in display order (at least one `open`, one `won` and one `lost`) and an optional `routingRule`: one sentence that says which deals belong there, which Ken reads to route a new deal that names no pipeline. Each stage gets a key from its label; a key another pipeline already uses gets the pipeline's name in front (`renewals_won`). A workspace has at most 10 pipelines.
- **`update`** changes what you send. `stages` is the pipeline's whole stage list: read it with `pipelines get`, keep each stage's `key`, and add a new stage without one. A stage with live deals in it cannot be left out; archive it with `"isArchived": true` instead.
- **`propose`** asks Ken to draft a pipeline from one sentence: a `name`, a `routingRule` and `stages`, in the shape `create` takes. It saves nothing. Read it, change what you want, and send it to `create`.
- **`archive`** stops new deals from entering a pipeline and keeps the deals in it. The default pipeline cannot be archived, and nothing is deleted: `restore` brings a pipeline back.

## Deals in a pipeline

A deal's stage names its pipeline, and the deal's `pipelineId` repeats it. To work one pipeline's deals, or move a deal between pipelines:

```bash
kenso opportunities list --pipeline-id 6
kenso opportunities search --pipeline-id 6 --data '{"countBy": ["stage"]}'
kenso opportunities create --account-id 501 --pipeline-id 6
kenso opportunities move 77 --pipeline 6
kenso opportunities move 77 --pipeline 6 --stage negotiating
```

- **`create --pipeline-id`** opens the deal in that pipeline's first live open stage. Without it, and without a `stage`, Ken reads each pipeline's `routingRule` and opens the deal in the pipeline whose rule clearly fits the account, else in the default pipeline. A pipeline you name always wins.
- **`move --pipeline`** alone keeps the deal's category (`open`, `won` or `lost`): it lands in that pipeline's live stage of the category with the same label as its stage now, else in the category's first live stage. The printed deal says where it landed. With `--stage`, the stage must be that pipeline's; the error lists the pipeline's stage keys otherwise.
- An archived pipeline takes no deal from another pipeline (`pipeline_archived`). The deals already in it still move between its stages.
- A move is a stage change: it writes the same history, and a stage a person set is refused with `pinned_by_user` unless you pass `--overwrite-pinned`.

## Restore a deleted account

```bash
kenso deleted-accounts list
kenso accounts restore 812
```

A deleted account can be restored for 30 days. `deleted-accounts list` shows each one with who deleted it, `expiresAt` (restore works until then) and what comes back: `personCount`, `opportunityCount` and `touchCount`. `accounts restore <id>` brings the account back with its domains, its people, its deals and its planned touches, which wait for approval again. A domain another account took since stays with that account and is listed in `domainsTaken`. A merged account is not listed and cannot be restored: a merge has no undo. Both commands are behind the `crm_import_export` feature flag (`404` while it is off).

## Import a CSV export of another CRM

```bash
kenso import accounts companies.csv
kenso import accounts companies.csv --map "Company=name" --map "Notes=" --yes
kenso import accounts --id 42 --yes
kenso record-import-rows list --import-id 42 --outcome skipped
kenso record-imports undo --import-id 42
```

`kenso import accounts <file.csv>` uploads the file (a header row, at most 50,000 rows) and prints Kenso's plan: which field each column fills, which columns it skips, how owner and stage values are read (`valueMaps`) and what it could not settle (`questions`). Headers of Kenso, Twenty, HubSpot, Attio and Salesforce exports are recognized. Nothing is written to your accounts yet. `--map "Header=field"` changes a column and `--map "Header="` skips it. A column fills a custom field with `--map "Header=custom.<key>"` (`kenso fields list --object account` has the keys; people are `person`, deals `opportunity`), and `--map "Header=new"` adds the custom field Kenso proposes for a column no field matches (`new:text` picks the type), and a column whose header is a custom field's label is mapped to it already; owner and stage values change with `kenso record-imports update --import-id <id>`.

With `--yes` the import starts and the command waits for it (`--timeout`, default 30m; the import keeps running on the server either way), then prints how many rows were created, updated, restored, left unchanged and skipped. Without `--yes` it stops at the plan and prints the command that starts that import (`--id <importId> --yes`), so the file is uploaded once. `--dry-run` sends nothing: with a file it prints the upload it would make, since the plan needs the upload, and with `--id` it reads the planned import and prints what `--map`, `--source` and `--research` would change on it. `--source twenty` names the system the file's record ids come from: pass the same one for every file of an export, so the people and deals files find the accounts by their old ids. `kenso record-imports delete --import-id <id>` discards an import that was planned and never started; one left planned for 30 days is discarded by itself.

Per row: a domain no account has creates an account; a domain that is already an account fills only that account's empty fields, so nothing you entered is overwritten; an account deleted in the last 30 days is restored; a row with no usable domain is skipped, and `kenso record-import-rows list --import-id <id> --outcome skipped` says why. Research of new accounts is off unless you pass `--research`, which is charged per account. It needs the `accounts` and `crm_import_export` flags. This is a different command from `accounts import`, which creates accounts row by row from the machine running the CLI.

`kenso record-imports undo --import-id <id>` takes a finished import back in the background (`kenso record-imports get --import-id <id>` reads `undoing`, then `undone`): an account the import created is deleted, and can be restored for 30 days, unless someone changed it since, it holds a deal, a person was added to it since, or it was merged; a field the import filled is emptied while it still holds the imported value. `kenso record-import-rows list --import-id <id>` shows each row's `undoOutcome`.

`kenso import people <file.csv>` works the same way for people. Import the accounts file first: a people row's company id (Twenty's `Company Id`, HubSpot's associated company id) places the person on the account that kept that id, and without one the person goes on the account that holds their email's or company's domain. A people import never creates an account; a person whose company is no account comes in without one and the row says so. A row matches a person by email, then LinkedIn URL, then name on the company, as every other way into People does; a matched person gets only their empty fields filled (a phone only when they have none). A row with none of the three is skipped, and a row with only a name needs a company that is an account with a domain. `kenso record-imports undo --import-id <id>` takes a people import back too: a person it created leaves the accounts the row placed them on and is deleted, unless someone changed them since, they were contacted or have a touch planned, or they are on an open deal; a field it filled is emptied while it still holds the imported value. `kenso people import` stays the JSONL and enrichment path (`--find-emails`); `kenso import people` is the CRM file with a plan, a row report and one approval.

`kenso import deals <file.csv>` works the same way for deals, after the accounts file and the people file. A row opens a deal on the account that kept its company id (Twenty's `Company Id`, HubSpot's associated company id), else on the account that holds its company domain; a row whose account Kenso does not know is skipped and says so. Its contact is the person a people import kept the row's contact id for (Twenty's `Point of Contact Id`). The plan maps each stage in the file to one of the workspace's deal stages (`valueMaps`, field `stage`): a stage's key or label matches by itself, Closed Won and Closed Lost go to the first won and lost stage, and a value with no match opens in the first open stage until you pick one with `kenso record-imports update`. Amounts stay in the workspace currency: an amount in another currency is left out with a warning, never converted. A row whose deal id an earlier import kept is that deal and only gets its empty fields filled; a file with no id column opens every deal again each time it is imported, and the plan says so (`no_source_id`). `kenso record-imports undo --import-id <id>` takes a deals import back: a deal it opened is deleted unless someone changed it since, and a field it filled is emptied while it still holds the imported value. Undo in the reverse order of the imports (deals, then people, then accounts): an account that holds a deal is kept.

## Export accounts, people or deals

```bash
kenso export accounts --out accounts.csv
kenso export accounts --view 12 --out tier-1.csv
kenso export deals --filters '[{"field":"stageCategory","operator":"is","values":["open"]}]' > open-deals.csv
```

It writes the CSV that `POST /v1/accounts/export`, `/v1/people/export` or `/v1/opportunities/export` returns, to stdout or to `--out` (then it prints the file and its row count). With no filter it exports every record. More than 50,000 rows is refused: narrow the filters. `--view <id>` exports a saved Accounts view (`kenso account-views list` shows the ids). `--filters`, `--where` (accounts), `--q` and `--sort` are the search operation's own fields, so a deals or people view exports with its filters and sort. The accounts and deals files start with `id` and import back as they are. Each export writes an audit-log entry and needs the export permission. Accounts and deals also need the `crm_import_export` flag while it is in beta.

## Duplicates and merges

```bash
kenso accounts duplicates --scan
kenso accounts merge 812 --into 77 --dry-run
kenso accounts merge 812 --into 77 --yes
kenso accounts merges list --merged-by system
kenso accounts merges 41
```

These need the `crm_import_export` flag beside `accounts`. `accounts duplicates` lists the pairs of accounts that look like one company: both accounts, why they were paired (`reasons`: `domain`, `linkedin`, `name`) and `isCertain`, true when the two share the name and the domain apart from its ending (acme.com and acme.co). `--scan` compares every account first; a scan also runs after each accounts import. `--status dismissed` or `merged` shows the answered pairs. `kenso account-duplicates dismiss --duplicate-id <duplicateId>` answers that a pair is not a duplicate, for good.

`accounts merge <accountId> --into <id>` merges the first account into the second, the one you keep. A merge cannot be undone, so look first: `--dry-run` prints `mergeSummary` (each field that changes with its value before and after, and how many people, deals, touches and domains move) and writes nothing. The merge itself needs `--yes` when no person is at the terminal. It answers the kept account with the same summary and a `mergeId`.

`accounts merges list` is the log, newest first, and `accounts merges <mergeId>` opens one merge with `mergedValues`: the merged-away account as it was. `--merged-by system` shows the merges Ken made itself. Where automatic merging is on for the workspace, Ken merges only certain pairs, keeps the customer, then the owned, then the last touched account, and leaves a pair for you when both are customers, the two have different owners, or one is being worked and the other is set aside (`heldReason` on the pair says which). That job is off unless it was turned on for the workspace.

## A deal's stage history

```bash
kenso opportunities stage-history 77
kenso opportunities stage-history 77 --query "entries[].{to: stageLabel, at: enteredAt, by: changedBy}"
```

It prints `GET /v1/opportunities/{id}/stage-history` as it is, the same rows as the deal page and the MCP's `opportunities(operation="get-stage-history")`: the stage now, `isComplete` and `entries`, oldest first, each with `fromStage`, `stage`, `stageLabel`, `enteredAt`, `leftAt`, `durationSeconds`, `actorKind`, `actorMemberId` and Ken's `reason` on a move its stage judge made. With the `deal_stage_rules` flag on, each entry also has `changedBy` (`member`, `agent`, `api_key`, `workflow`, `stage_judge`, `crm_sync` or `ken_automation`), `crmProvider` on a CRM sync, and on a move `fromStageLabel` and `fromStageDurationSeconds`, how long the deal sat in the stage it left. `isComplete` false means Kenso has no record of part of the history.

## Notes on accounts, people and deals

With the `record_notes` feature on, everyone who can see a record reads its notes. Name the record with exactly one of `--account`, `--person` and `--deal`:

```bash
kenso notes list --account 5
kenso notes add --account 5 --body 'Budget approved, @[Jane Doe](41) please send the DPA'
kenso notes add --parent 900 --body 'Sent it this morning'          # a comment under note 900
cat call-notes.md | kenso notes add --deal 77 --body -              # the body from stdin
kenso notes edit 900 --body 'Budget approved for Q1'                # the author only
kenso notes edit 900 --pin
kenso notes delete 900 --yes                                        # kenso notes restore 900 brings it back
```

The body is markdown, up to 20,000 characters. Mention a teammate as `@[Name](memberId)`: they get a notification that opens the note. A note shows on the record's Notes tab and its Activity timeline, and Ken's account brief quotes the account's notes. The MCP's `notes` tool does the same. A note on an account needs the accounts plan feature; people and deals work on every plan.

## Required fields per stage

```bash
kenso pipelines stage-rules
kenso pipelines stage-rules proposal --require amount,closeDate,custom.tier
kenso pipelines stage-rules proposal --none
kenso pipelines stage-rules lost --default
```

With the `deal_stage_rules` flag on, each stage can name the fields a deal should have in it. Without a stage the command prints every stage's `key`, `label`, `category`, `isArchived`, `requiredFields` and `isDefault`, plus `requirableFields`: `amount`, `closeDate`, `ownerMemberId`, `primaryPersonId`, `nextStep`, `lostReasonKey`, `wonReasonKey` and `custom.<key>` for each custom deal field. `--require` sets the stage's whole list, in order, at most 10. `--none` requires nothing, and `--default` goes back to the default: a lost stage asks for `lostReasonKey`, any other stage nothing. Setting a rule needs the `workspace_settings` permission. The same as the MCP's `opportunities(operation="stages-set-required-fields")`.

A missing field never stops a move. The deal moves, and it is flagged Missing on the board, the list and the deal page until the field is filled. A rule also applies to deals already in the stage.

```bash
kenso opportunities update --opportunity-id 4401 --stage proposal
kenso opportunities list --missing-fields
```

Every deal then carries `missingFields` (`[{field, label}]`). A create, or an update that sends a stage, answers `warnings` beside the deal for each field the stage asks for that the deal leaves empty: each prints on stderr as `warning: <message>`, stdout stays the deal and the exit code stays 0. `--missing-fields` keeps only the deals flagged Missing (also `missingFields: true` on `kenso opportunities search`).

## Won and lost reasons

```bash
kenso opportunity-reasons get
kenso opportunity-reasons replace --kind lost --data '{"reasons":[{"key":"no_budget","label":"No budget"},{"label":"Built it in-house"}]}'
kenso opportunities move 4401 --stage lost --reason built_it_in_house
```

`kenso opportunities move <id> --stage <key> [--reason <key>]` sends the reason as `lostReasonKey` for a lost stage or `wonReasonKey` for a won stage; an open stage takes none. Each field the new stage asks for that the deal leaves empty prints a warning on stderr, and the move still goes through.

With the `deal_stage_rules` flag on, each workspace edits why its deals are lost and won. `get` prints `lost` and `won`, each `{isDefault, reasons: [{key, label, isArchived}]}`. `replace` takes a kind's whole list in order, as `get` prints it: keep a reason by its `key`, leave `key` out for a new one, and set `isArchived` to archive a reason or bring one back. A reason left out is archived too: deals keep it, and no write can pick it again. At least one reason stays live and at most 30, and labels stay unique, archived ones included. A deal takes a live key in `lostReasonKey` (a lost stage) or `wonReasonKey` (a won stage). A move to Lost without a reason still goes through, with a warning and "Missing: Lost reason" on the deal. Editing the lists needs the `workspace_settings` permission. The same as the MCP's `pipelines(operation="reasons-get")` and `reasons-replace`.

## Record page layouts

```bash
kenso layouts show account
kenso layouts set account --header tier,ownerMemberId,score,custom.arr
kenso layouts show account > layout.json && kenso layouts set account --data @layout.json
kenso layouts reset account
```

With the `record_layout` flag on, a workspace lays out each record page once, for every member: `account`, `person` or `opportunity` (a deal). `show` prints `GET /v1/record-layouts/{object}`: `isDefault`, `version`, `headerFields` (up to 6, pinned under the record's name), `railSections` (`{name, fields}`), `hiddenFields` (under the rail's More), `sections` (`{key, label, placement, locked, hidden}`, in page order) and `availableFields`. Field keys are the field catalog's (`ownerMemberId`, `closeDate`, `primaryDomain`); a custom field is `custom.<field_key>`, and a new one joins the last rail section.

`set --header` pins up to 6 fields and keeps the rest of the saved layout; the fields it unpins go to the top of the first rail section. `set --data` saves a whole layout, so group the rail into sections or hide a section that way, starting from `show`. A save made after someone else's answers a conflict: show it again. `reset` puts the page back to Kenso's default. Saving needs the `workspace_settings` permission, and the account page also needs the `accounts` plan. The same as the MCP's `account_views` operations `record-layouts-get`, `record-layouts-replace` and `record-layouts-reset`.

## Tasks

Tasks are to-dos a member owes: a title, an optional due day or time, an assignee and at most one account, person or deal. They need the `tasks` flag. The app calls deals "Deals"; the CLI keeps `--deal` for an opportunity id.

```bash
kenso tasks add "Send the deck" --due tomorrow --account 812
kenso tasks add "Call Ada back" --due friday --at 16:00 --person 501 --assignee ada@acme.com
kenso tasks list --assignee me --due overdue,today
kenso tasks queue --scope mine
kenso tasks assign 7 me
kenso tasks done 7 8 9
kenso tasks done 7 --undo
```

- `tasks add` sends `POST /v1/tasks`. `--due` takes `today`, `tomorrow`, a weekday (the next one: `friday` or `fri`), a day (`2026-11-20`) or an ISO 8601 time; `--at HH:MM` puts a time on that day (today without `--due`). Day words and `--at` read this computer's clock and time zone (`TZ`); a time's day is read in the assignee's app time zone. `--assignee` takes `me`, a member id or an email; without it the task is yours.
- `tasks done` completes each task it names, in order (`PATCH /v1/tasks/{id}` with `status: done`); `--undo` reopens them. `tasks assign` gives a task to `me`, a member id or a member's email; that member gets a `task_assigned` notification.
- `tasks queue` is `task-queue list` under the name you would try: the Tasks screen's open work by due day, with `--scope mine|assigned_by_me|everyone`. It lists tasks, manual touches, call tasks, inbox threads with a reminder due (when you can view the Inbox) and Ken's follow-ups to you, each with the app path in `href` (null for a task, which opens in its panel).
- `tasks list`, `get`, `update`, `delete`, `restore` and `task-queue list` are generated from the API: `kenso tasks --help` lists them.

## More for developers

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