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.
• The CLI never prompts. A batch command (an import, update, remove, tag or --each write) takes --yes; without it, the command plans or refuses. A single generated write, such as kenso tags delete --tag-id 7, and a write through kenso api send at once: add --dry-run to see the request first, then run the command without it.

Formats

-o or --output picks the format: json, ndjson, table or ids.

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

kenso tags list --limit 50
kenso tags list --all

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"}}

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.

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

Errors from the CLI itself

Exit codes

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