# Output and errors

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

Every command follows one contract, so a script or an agent can parse any of them the same way.

## stdout and stderr

- **stdout carries data only.** Progress, warnings, notices and errors go to stderr.
- No colors, spinners or pagers. On a terminal you get readable tables; in a pipe you get JSON.
- A batch command (an import, update, remove, tag or `--each` write) takes `--yes`; without it, the command plans or refuses.
- A command that deletes, archives or removes, such as `kenso tags delete --tag-id 7`, `kenso campaigns archive` or `kenso api DELETE /v1/tags/7`, needs `--yes` too. Without it, a person at a terminal is asked to confirm; anywhere else (a pipe, a script, CI, a coding agent) it sends nothing and fails with `confirmation_required`, whose `next` is the same command with `--yes`.
- Any other single write, such as `kenso tags create` or a write through `kenso api` or `kenso mcp call`, sends at once: add `--dry-run` to print the request first (it sends nothing), then run the command without it.
- A command with no dry run, such as `kenso contacts export`, `kenso auth logout` or `kenso workspace use`, refuses `--dry-run` with `usage_error` (exit 2) and does nothing. Its help ends with `No --dry-run`, and `kenso describe <resource> <action>` shows `"dryRun": false`.

## Formats

| What the command returns | stdout is a terminal | stdout is a pipe or file |
|---|---|---|
| One object | key-value lines | compact JSON on one line |
| A list | a table (first 8 scalar fields, cells cut at 60 characters) | NDJSON: one JSON object per line |
| A batch run | key-value lines | one JSON summary object |
| No content (HTTP 204) | nothing | nothing |

`-o` or `--output` picks the format: `json`, `ndjson`, `table` or `ids`. `--json` is the same as `-o json`.

- `-o json` on a list prints one JSON array. On a terminal, `-o json` pretty-prints an object.
- `-o ids` prints one id per line, ready for `--ids -`. Items without an `id` are skipped with one warning.

```bash
kenso campaigns list --limit 3
kenso campaigns list --limit 3 -o json
kenso contacts list --campaign-id 812 --all -o ids
```

## Shape the output

- `--fields a,b.c` keeps only those fields (dots reach into nested objects).
- `--query <JMESPath>` filters or reshapes in-process, so you need no `jq`. On a list it sees the whole list. There is no `--jq`: `--query` takes JMESPath, not jq syntax.
- Neither applies to a batch summary, which always prints in full.

```bash
kenso campaigns list --fields id,name,status
kenso campaigns list --all --query "[?status=='active'].id"
kenso me get --query "length(features)"
```

## Lists and pages

A list command prints one page. When there are more, it prints the command for the next page on stderr, for example `next: kenso tags list --limit 1 --cursor MQ`. `--all` follows every page and streams the items. `--limit` sets the page size and `--cursor` starts at a cursor.

`accounts search`, `contacts search` and `people search` page the same way: one page with the `next:` command, or every page with `--all`. A search that asks for counts (`countBy` in `--data`) prints the whole answer instead: `data`, `pagination` and `counts`. Counts cover every match whatever the page, so ask for them on one page (`--limit 1`): `--all` with `countBy` is a usage error.

```bash
kenso tags list --limit 50
kenso tags list --all
```

## Files: uploads and downloads

A command whose API action takes a multipart upload takes `--file <path>`: the CLI reads the file and sends it in the form, with a content type from its extension (a `.png` goes as `image/png`), and the other flags as form fields. `--file <field>=<path>` names the form field, for a form with more than one file. An upload that also takes JSON, such as a logo from a URL instead of a file, sends JSON when you leave `--file` out.

A command whose API action answers with a file (a CSV, an image, a ZIP) takes `--out <path>`: it saves the answer byte for byte (mode 0600) and prints `out`, `bytes` and `contentType`, so the file never passes through an agent's context. Without `--out`, a CSV prints as it came, and a binary file goes to stdout only when stdout is a pipe or a file: on a terminal it fails with `binary_output`, whose `next` adds `--out`.

`kenso api` takes both, for any route: `--file` (repeat it for more files) sends multipart with the keys of a `--data` object as form fields, and `--out` saves any answer.

```bash
kenso saved-lists create-upload --saved-list-id 12 --file people.csv
kenso workspaces replace-logo --workspace-id 42 --file ./logo.png
kenso workspaces replace-logo --workspace-id 42 --source-url https://example.com/logo.png
kenso attachments get-content --attachment-id att_123 --out ./invoice.pdf
kenso api POST /v1/campaigns/812/email-sequence/images --file ./hero.png
kenso api GET /v1/knowledge/exports/77/content --out knowledge.zip
```

## Live streams

`kenso sync events` and `kenso onboarding-builds events` follow a live stream of server-sent events. They print one JSON line per event as it arrives, on a terminal too, with the event's name, its id when it has one, and its data:

```json
{"event":"hello","data":{"buildId":"obd_2x","status":"building","stage":"read","lastEventId":0}}
{"event":"stage","id":"41","data":{"stage":"plan"}}
{"event":"done","id":"42","data":{}}
```

A stream has no time limit while events arrive. The server ends each connection after 15 minutes with a `bye` event; the command then connects again at once, and after a dropped connection or 60 s without even a keepalive, after a second. A connection that brought nothing but `hello` and `bye` (a server that is restarting) backs off 1, 2, 4 ... 30 s. Once events carry an id (`onboarding-builds events`), it sends the last whole event's id as `Last-Event-ID`, so no event is lost or printed twice. A refusal (401, 403, 404) ends it at once; eight failed or empty connects in a row end it with the last error.

It runs until Ctrl-C (exit 130; every line printed is whole), or until one of these:

| Flag | Ends the command |
|---|---|
| `--until <event>` | After the first event with that name; several names are comma-separated: `--until done,error` |
| `--max-events <n>` | After n events, `hello` and `bye` included |
| `--once` | When the server closes the connection, instead of connecting again |

```bash
kenso onboarding-builds events --build-id obd_2x --until done,error
kenso sync events --max-events 2   # hello, then the first poke
```

`--output`, `--fields` and `--query` do not apply to a stream. `--last-event-id` starts an onboarding build stream after that id.

## Errors

When stderr is not a terminal, an error is one JSON line on stderr:

```json
{"error":{"code":"unknown_flag","message":"Unknown flag --fiel for kenso contacts import.","field":"fiel","hint":"did you mean --file?","next":"kenso contacts import --help"}}
```

| Key | Always there | Meaning |
|---|---|---|
| `code` | yes | A stable snake_case code to branch on |
| `message` | yes | One sentence for a person |
| `field` | no | The flag or input field at fault |
| `hint` | no | What to change |
| `next` | no | The exact command to run next, such as `kenso auth login`, `kenso workspace list --search <name>` or the same command with `--yes` |
| `httpStatus` | no | The API's HTTP status, when the API answered |
| `requestId` | no | The API's request id: quote it when you contact Kenso support |

On a terminal the same error prints as text: `Error: <message>`, then `field:`, `hint:`, `next:` and `requestId:` lines. The key never appears in an error.

### How API errors map

The CLI looks at the HTTP status first, then at the API's own `error.code`, which wins when present.

| HTTP status | Default code | Exit |
|---|---|---|
| 400, 422 | `validation_failed` | 2 |
| 401 | `unauthorized` (`next`: `kenso auth login`) | 3 |
| 403 | `forbidden`: the key's user or role cannot do this in this workspace | 3 |
| 404 | `not_found` | 4 |
| 409 | `conflict` | 7 |
| 429 | `rate_limited`, after the CLI waited and retried | 6 |
| 5xx | `server_error`, after retries where they are safe | 8 |
| anything else | `http_error` | 1 |

Two API codes change the exit code: `workspace_required` exits 2 with `"next":"kenso workspace list --search <name>"`, and `limit_reached` (the plan's or the campaign's lead limit) exits 6.

### Errors from the CLI itself

| Code | Exit | When |
|---|---|---|
| `usage_error` | 2 | A required flag or argument is missing, two flags conflict (`--yes` with `--dry-run`), or `--dry-run` on a command that has no dry run |
| `unknown_command` | 2 | No such command; `hint` suggests the closest one |
| `unknown_flag`, `invalid_flag`, `invalid_flag_value`, `unexpected_argument` | 2 | A flag or argument the command does not take |
| `invalid_query` | 2 | `--query` is not valid JMESPath |
| `confirmation_required` | 2 | A delete, archive or remove ran without `--yes` where nobody can confirm: nothing was sent; `next` adds `--yes` |
| `cancelled` | 2 | A person answered no to the confirmation: nothing was sent |
| `file_unreadable` | 2 | An input file is missing, is a folder, cannot be opened, or cannot be parsed; the message names the line, such as `leads.csv line 3: a quote is not closed.` |
| `config_invalid` | 2 | `~/.kenso/config.json` is not valid JSON: fix or delete it |
| `feature_not_enabled` | 2 | Every action of the resource is a beta command your workspace has not enabled |
| `invalid_key_format`, `key_required` | 2 | `auth login --with-key` read something that is not a Kenso key, or stdin is a terminal instead of a pipe |
| `invalid_workspace_id` | 2 | `kenso workspace use` got an id that is not a positive whole number |
| `unknown_topic` | 2 | `kenso docs` got a topic it does not have; `hint` lists the topics |
| `file_unwritable` | 2 or 1 | An output file cannot be written: `--out` on `contacts export`, `kenso api` or a download command (2), `skill install` (1) |
| `binary_output` | 2 | The answer is a binary file and stdout is a terminal: nothing was printed; `next` saves it with `--out` |
| `no_api_key` | 3 | No key in `KENSO_API_KEY` or the profile (`next`: `kenso auth login`) |
| `browser_login_unavailable`, `access_denied`, `login_expired` | 3 | Browser login is off, was denied, or timed out |
| `run_not_found` | 4 | `kenso runs show` or `resume` got an unknown run id |
| `docs_not_found` | 4 | `kenso docs reference` before the reference was generated (a source checkout without `pnpm build`) |
| `run_in_progress`, `already_filled` | 7 | Another process is working on the run, or `studio fill` already ran with this file and these flags |
| `skill_exists` | 7 | `kenso skill install` found a different `SKILL.md`; `next` adds `--force` to replace it |
| `job_timeout`, `job_failed`, `job_canceled` | 1 | `kenso jobs wait` (or a command that waits on a job) ran out of time, or the job failed or was canceled |
| `mcp_tool_error` | 1 | `kenso mcp call`: the MCP tool answered with an error |
| `unsafe_path` | 1 | `studio pull` refused a file path that would land outside `--dir` |
| `network_error` | 8 | The API could not be reached after retries |
| `upload_failed`, `download_failed` | 8 or 1 | A signed upload or download of a Studio file failed: 8 when storage was unreachable or answered 5xx, 1 on a 4xx (often an expired link: run the command again) |
| `pull_incomplete` | 8 | `studio pull`: a file came back with neither text nor a download link |
| `unexpected_response` | 1 or 8 | The API answered something the CLI could not read |
| `unexpected_error` | 1 | A bug: run again with `--verbose` and report it |
| `interrupted` | 130 | Ctrl-C |

## Exit codes

| Code | Meaning |
|---|---|
| 0 | OK, including a batch where every row succeeded or was skipped |
| 1 | Unexpected error |
| 2 | Usage or input error: a bad flag, a bad file, a validation error |
| 3 | Auth: no key, an invalid, revoked or expired key, or HTTP 401 or 403 |
| 4 | Not found |
| 5 | Partial: the batch finished and some rows failed, were not found or were invalid. See `results.csv` |
| 6 | Rate limited after retries, or a plan or campaign lead limit stopped the run (`limit_reached`) |
| 7 | Conflict or invalid state (HTTP 409), or a run another process holds |
| 8 | Server error after retries (5xx), or the API is unreachable |
| 9 | Answer refused: a Kenso sandbox run stopped because an answer held a credential or something shaped like one |
| 130 | Interrupted. A batch run can be resumed: see its `next` |

Skipped rows (duplicates, blocklisted, already contacted) are not failures: a batch with only created, updated and skipped rows exits 0.

## Flags

- Command flags go after the command: `kenso contacts import --campaign 812`. Global flags can go anywhere.
- A boolean flag takes `--flag`, `--no-flag`, `--flag=true` and `--flag=false`.
- A flag that carries a secret (`--password`, `--api-key`, `--api-secret`, any `--…-token` or `--…-secret`) also takes `-` (read stdin), `@file` (read the file) or `env:NAME` (read that environment variable), so the value stays out of shell history: `printf '%s' "$FATHOM_KEY" | kenso fathom-connection connect --api-key -`. A value typed on the command line still works and prints one warning. A typed secret that itself starts with `@` is written `@@` (`--password @@Spring2026` sends `@Spring2026`); one that is exactly `-` or starts with `env:` has to come through `@file` or `env:NAME`. `-` refuses a terminal, an empty value is refused, and only one flag can read stdin. `--dry-run` shows a secret as `***`. With `--each`, the plan, its `next` and the run record keep `@file` or `env:NAME` as typed and `kenso runs resume` reads it again; a secret from stdin is refused there.
- `--help` on any command prints its flags, arguments and examples. `kenso describe <resource> <action>` prints the same as JSON, with the body schema.

## Beta commands

Commands that need a workspace feature flag (CRM, Studio and others) are beta. Help and `kenso describe` hide the ones your workspace has not enabled and say how many they hid; `--all-commands` shows them. Calling a hidden command still works: Kenso decides. `kenso <resource>` on a resource whose every action is hidden answers `feature_not_enabled` (exit 2) and names the flags it needs.

```bash
kenso --help --all-commands
kenso describe --all-commands
```

## What the CLI sends

Every API call carries `Authorization: Bearer <key>`, `Ken-Version: 1.1`, `X-Ken-Workspace-Id` (when a workspace is picked), `User-Agent: kenso-cli/<version> (node <version>; <platform>)` and `X-Ken-Client: Kenso CLI`. When a coding agent runs the CLI, `X-Ken-Client` names it (`Kenso CLI via Claude Code`) and writes carry `X-Ken-Actor: agent`, so Kenso's activity log shows who made a change.

## More for developers

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