Skip to Content
Topics

Output and errors

View as Markdown

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 returnsstdout is a terminalstdout is a pipe or file
One objectkey-value linescompact JSON on one line
A lista table (first 8 scalar fields, cells cut at 60 characters)NDJSON: one JSON object per line
A batch runkey-value linesone JSON summary object
No content (HTTP 204)nothingnothing

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

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:

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

FlagEnds 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
--onceWhen 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"}}
KeyAlways thereMeaning
codeyesA stable snake_case code to branch on
messageyesOne sentence for a person
fieldnoThe flag or input field at fault
hintnoWhat to change
nextnoThe exact command to run next, such as kenso auth login, kenso workspace list --search <name> or the same command with --yes
httpStatusnoThe API's HTTP status, when the API answered
requestIdnoThe 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 statusDefault codeExit
400, 422validation_failed2
401unauthorized (next: kenso auth login)3
403forbidden: the key's user or role cannot do this in this workspace3
404not_found4
409conflict7
429rate_limited, after the CLI waited and retried6
5xxserver_error, after retries where they are safe8
anything elsehttp_error1

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

CodeExitWhen
usage_error2A 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_command2No such command; hint suggests the closest one
unknown_flag, invalid_flag, invalid_flag_value, unexpected_argument2A flag or argument the command does not take
invalid_query2--query is not valid JMESPath
confirmation_required2A delete, archive or remove ran without --yes where nobody can confirm: nothing was sent; next adds --yes
cancelled2A person answered no to the confirmation: nothing was sent
file_unreadable2An 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_invalid2~/.kenso/config.json is not valid JSON: fix or delete it
feature_not_enabled2Every action of the resource is a beta command your workspace has not enabled
invalid_key_format, key_required2auth login --with-key read something that is not a Kenso key, or stdin is a terminal instead of a pipe
invalid_workspace_id2kenso workspace use got an id that is not a positive whole number
unknown_topic2kenso docs got a topic it does not have; hint lists the topics
file_unwritable2 or 1An output file cannot be written: --out on contacts export, kenso api or a download command (2), skill install (1)
binary_output2The answer is a binary file and stdout is a terminal: nothing was printed; next saves it with --out
no_api_key3No key in KENSO_API_KEY or the profile (next: kenso auth login)
browser_login_unavailable, access_denied, login_expired3Browser login is off, was denied, or timed out
run_not_found4kenso runs show or resume got an unknown run id
docs_not_found4kenso docs reference before the reference was generated (a source checkout without pnpm build)
run_in_progress, already_filled7Another process is working on the run, or studio fill already ran with this file and these flags
skill_exists7kenso skill install found a different SKILL.md; next adds --force to replace it
job_timeout, job_failed, job_canceled1kenso jobs wait (or a command that waits on a job) ran out of time, or the job failed or was canceled
mcp_tool_error1kenso mcp call: the MCP tool answered with an error
unsafe_path1studio pull refused a file path that would land outside --dir
network_error8The API could not be reached after retries
upload_failed, download_failed8 or 1A 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_incomplete8studio pull: a file came back with neither text nor a download link
unexpected_response1 or 8The API answered something the CLI could not read
unexpected_error1A bug: run again with --verbose and report it
interrupted130Ctrl-C

Exit codes

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

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.

On this page