Authentication
The CLI calls the Kenso API with a Kenso API key (kenso_live_ plus 49 characters, or an older key: ken_ plus 43 characters). It sends the key as Authorization: Bearer <key> and never prints it, logs it or puts it in an error.
kenso login, kenso logout and kenso whoami are the same commands as kenso auth login, kenso auth logout and kenso auth status.
Log in with an API key
- In app.ken.so, go to Settings > Integrations > API keys and create a key.
- Pipe it to
kenso auth login --with-key. The key is read from stdin, never from a flag, so it stays out of your shell history and process list.
echo $KEY | kenso auth login --with-key
kenso auth login --with-key --profile client-a --workspace 1234 < key.txtThe CLI checks the key with GET /v1/me, then saves it to ~/.kenso/config.json (file mode 0600, folder mode 0700). It prints:
{"profile":"default","email":"[email protected]","workspaceId":"1234","workspaceCount":1}A developer sandbox does not count here unless every workspace is one: a key whose user has one workspace and a sandbox saves that workspace. When the key reaches several workspaces and you did not pass --workspace, no workspace is saved and the output carries "next":"kenso workspace list --search <name>". A key in the wrong format exits 2 (invalid_key_format). A key Kenso rejects exits 3.
Browser login
kenso auth login
kenso auth login --no-browser --device-name "build box"Browser login is available to every workspace. The CLI prints a link and a code on stderr. You open the link, sign in to app.ken.so, check that the code matches the one in your terminal, pick the workspace to start in and approve. The CLI then saves a new API key to the profile and prints:
{"profile":"default","email":"[email protected]","workspaceId":"1234","keyExpiresAt":"2027-02-02T06:26:59Z"}The key is the same kind you create in the app. It is named Kenso CLI - <device name> (--device-name, else kenso-cli on <hostname>), lasts 90 days, and shows in your API key list at Settings > Integrations > API keys, where you can revoke it. The CLI opens the browser itself only when no coding agent is detected and the machine has a display. An agent prints the link and asks you to open it. The login expires after 10 minutes (login_expired, exit 3), and a denied login exits 3 with access_denied. If the API answers that browser login is off (browser_login_unavailable, exit 3, "next":"kenso auth login --with-key"), log in with an API key as above.
CI, scripts and agents: use the environment
You do not need to log in on a machine that has the key in its environment:
export KENSO_API_KEY=kenso_live_...
export KENSO_WORKSPACE_ID=1234
kenso auth statusKENSO_API_KEY wins over any saved profile. Store it as a secret in your CI or agent platform, never in a file in the repo.
Workspaces
A key reaches every workspace its user belongs to. Each command runs in one workspace, picked in this order:
--workspace <id>on the commandKENSO_WORKSPACE_ID- the workspace saved in the profile (
kenso workspace use)
kenso workspace list --search acme
kenso workspace use 1234
kenso campaigns list --workspace 5678workspace list prints one page and says on stderr when there are more: add --all for every page. A command that needs a workspace when none is picked fails with workspace_required (exit 2) and "next":"kenso workspace list --search <name>".
Profiles
A profile holds a key, a workspace, an optional API URL and the email. Use one per client or per key:
kenso auth login --with-key --profile client-a < client-a-key.txt
kenso campaigns list --profile client-a
KENSO_PROFILE=client-a kenso auth statusThe profile is --profile, else KENSO_PROFILE, else the active one (the last one you logged in to).
Check the setup
kenso auth status
kenso doctorauth status prints who the key belongs to and when it expires, and warns on stderr when that is within 14 days:
{"email":"[email protected]","workspaceCount":3,"activeWorkspace":{"id":"1234","name":"Acme"},"keyExpiresAt":"2027-01-31T00:00:00Z","keySource":"profile","profile":"default"}doctor prints the version, Node, the config folder, the profile, the key source, the API URL, the workspace and the detected agent, then four checks: node_version, config_permissions, api_reachable and key_valid. It exits 0 when every check passes, 3 when the key is missing or rejected, else 1.
Log out
kenso auth logout
kenso auth logout --profile client-a
kenso auth logout --keep-keyThis removes the profile and its key from this machine. When browser login made the key, logout revokes it first, so it stops working everywhere; --keep-key leaves it valid. If the revoke fails (no network, or the key was already revoked), logout warns and still removes the profile. A key you saved with --with-key was made by you in the app, so logout leaves it valid: revoke it at Settings > Integrations > API keys. The output adds revoked: true or false.
Where things live
| What | Default | Override |
|---|---|---|
| Config file with profiles and keys | ~/.kenso/config.json | KENSO_CONFIG_DIR |
| Run folders | ~/.kenso/runs/ | KENSO_RUNS_DIR |
| Cached workspace features (1 hour) | ~/.kenso/cache/ | follows KENSO_CONFIG_DIR |
| Last update check (once every 7 days) | ~/.kenso/update-check.json | follows KENSO_CONFIG_DIR; KENSO_NO_UPDATE_NOTIFIER=1 turns the check off |
| API | https://api.ken.so | KENSO_API_URL |
MCP (for kenso mcp) | https://mcp.ken.so/mcp | KENSO_MCP_URL |
--verbose prints each request line to stderr with the key redacted.