Output and errors
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
--eachwrite) 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 archiveorkenso api DELETE /v1/tags/7, needs--yestoo. 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 withconfirmation_required, whosenextis the same command with--yes. - Any other single write, such as
kenso tags createor a write throughkenso apiorkenso mcp call, sends at once: add--dry-runto 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 logoutorkenso workspace use, refuses--dry-runwithusage_error(exit 2) and does nothing. Its help ends withNo --dry-run, andkenso 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 jsonon a list prints one JSON array. On a terminal,-o jsonpretty-prints an object.-o idsprints one id per line, ready for--ids -. Items without anidare skipped with one warning.
kenso campaigns list --limit 3
kenso campaigns list --limit 3 -o json
kenso contacts list --campaign-id 812 --all -o idsShape the output
--fields a,b.ckeeps only those fields (dots reach into nested objects).--query <JMESPath>filters or reshapes in-process, so you need nojq. On a list it sees the whole list. There is no--jq:--querytakes JMESPath, not jq syntax.- Neither applies to a batch summary, which always prints in full.
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.
kenso tags list --limit 50
kenso tags list --allFiles: 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.
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.zipLive 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:
{"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 |
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:
{"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=trueand--flag=false. - A flag that carries a secret (
--password,--api-key,--api-secret, any--…-tokenor--…-secret) also takes-(read stdin),@file(read the file) orenv: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 @@Spring2026sends@Spring2026); one that is exactly-or starts withenv:has to come through@fileorenv:NAME.-refuses a terminal, an empty value is refused, and only one flag can read stdin.--dry-runshows a secret as***. With--each, the plan, itsnextand the run record keep@fileorenv:NAMEas typed andkenso runs resumereads it again; a secret from stdin is refused there. --helpon 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.
kenso --help --all-commands
kenso describe --all-commandsWhat 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.