Kanera CLI
@kanera/cli puts Kanera in your terminal. It is the fallback for an AI coding agent that can run shell commands but cannot use Kanera's connected MCP tools: any shell-capable agent can run kanera, with no MCP client configuration and no long-running server.
npm install --global @kanera/cli
Requires Node 22 or newer. The published package has no runtime dependencies.
To try it without installing:
npx @kanera/cli commands
Authenticate
The CLI uses an API key. Create one in Profile settings -> API keys, or in Workspace settings -> API when the credential should belong to a workspace rather than a person. See Kanera API for the difference.
kanera auth login
auth login opens your API keys page, prompts for the key with the terminal echo suppressed so it never lands in your shell scrollback, verifies it against Kanera, and stores it.
Choose a Read-only personal key when the credential is for an unattended agent. The CLI reports the scope it is holding, and refused writes exit with a distinct code so an agent can stop rather than retry.
kanera whoami # who am I, and what may this credential do?
kanera doctor # diagnose credentials, connectivity, and scope
In CI or an agent sandbox, skip the stored profile entirely and set KANERA_API_KEY.
Everyday commands
kanera work # your work across every accessible board
kanera boards # every board you can reach, including guest boards
kanera card MKT-42 # a card, by key, id, or URL
kanera card done MKT-42 # mark it complete
kanera comment MKT-42 "Shipped."
kanera search "renewal"
kanera priorities # an Up next queue
Card arguments accept a card key such as MKT-42, a card id, or a canonical card URL, so you can paste whatever you have in front of you.
kanera commands lists everything the CLI can do, and works before you log in. kanera commands --json is the machine-readable catalog an agent uses to discover the rest.
The full tool surface
The named commands above are ergonomic shortcuts over Kanera's MCP tool layer — the same tools an AI agent sees over MCP. Anything without a shortcut is still reachable:
kanera call kanera_bulk_move_cards --boardId "$BOARD" --listId "$LIST"
kanera help kanera_bulk_move_cards
Because the CLI reads the tool layer directly rather than re-implementing the public API, its command surface cannot drift from what agents see, and a newly added tool is callable from the shell the day it ships.
Arguments
Flags map onto tool arguments and are coerced using each tool's own JSON Schema, never by how the value looks — a card key can look numeric and an id can look boolean.
kanera card update MKT-42 --changes.title "Revised" # dots nest
kanera work --scope.boardIds[] "$A" --scope.boardIds[] "$B" # repeat for arrays
kanera call kanera_update_card --json-args '{"cardId":"MKT-42","changes":{"title":"Revised"}}'
Unknown flags, missing required arguments, malformed --json-args, and surplus positional arguments are usage errors. The CLI never silently discards an operand.
Output
| Flag | Output |
|---|---|
| (none) | Human-readable tables and summaries |
--json | A { ok, tool, data } envelope |
--quiet | The bare result, for piping into jq |
Failures always go to stderr, even in --json mode, so redirecting stdout to a file never mixes an error envelope into what the caller believes is result data.
Rate-limited and transient failures include retryable and, when Kanera supplies one, retryAfter.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | The request failed |
2 | Bad usage |
3 | No valid credential |
4 | Forbidden — often a read-only credential, or no Editor role on the board |
5 | Not found |
6 | Rate limited |
4 is deliberately distinct from 1. An agent holding a read-scoped key needs to tell "I may not do this" apart from "this did not work", and stop rather than retry.
Credentials and profiles
Resolution order: --api-key, then KANERA_API_KEY, then a stored profile.
Profiles live in ~/.config/kanera/config.json, written with mode 600. Named profiles let one machine hold several identities:
kanera auth login --profile agent --api-key "kanera_u_live_..."
kanera --profile agent work --json
| Command | Purpose |
|---|---|
kanera auth login | Store and verify a key |
kanera auth status | Show the active credential and its scope |
kanera auth list | List stored profiles |
kanera auth token | Print the active key, for KANERA_API_KEY=$(kanera auth token) |
kanera auth logout | Remove a stored profile |
A repository can select a profile without holding a secret, in .kanera/config.json:
{ "profile": "agent" }
That file cannot set an API origin. Origins receive the bearer credential, so a checked-out repository must not be able to redirect one. Use --url, KANERA_PUBLIC_API_URL, or the origin saved with the profile during auth login. Non-loopback origins must use HTTPS.
Self-hosted Kanera
Point the CLI at your own deployment during login, and it is saved with the profile:
kanera auth login --url https://api.your-kanera.example
Or set KANERA_PUBLIC_API_URL per command. kanera doctor reports the endpoint it resolved, which is usually the fastest way to find a misconfigured origin.
Use it from an AI agent
Two ways, and they are complementary.
As a shell tool. Install the CLI, give the agent a read-only key, and let it run commands. kanera setup writes the instructions the agent needs:
kanera setup claude # writes .claude/skills/kanera/SKILL.md
kanera setup codex # appends Kanera instructions to AGENTS.md
kanera skill # prints the portable Agent Skill document for any other harness
kanera setup codex is idempotent, so re-running it after an upgrade does not stack duplicate sections into a file you also edit by hand. Add --global to setup claude to install for your account rather than one project.
When the agent already has connected Kanera MCP tools, use those instead of the CLI. In either transport, supported card reads and updates should not fall back to browser automation merely because Kanera also has a web interface.
As an MCP server. kanera mcp serves the same tools over stdio MCP using the credential you already stored:
{
"mcpServers": {
"kanera": {
"command": "kanera",
"args": ["mcp"]
}
}
}
This means one kanera auth login covers both your terminal and your MCP client, instead of a second credential configured in a second place. For hosted remote MCP with OAuth — no key to create or store — see Connect Kanera to your AI agent instead.
Plan requirements
The CLI authenticates with an API key, so it inherits the API plan rules: API keys need Pro or the Pro trial. If a hosted organisation moves to Free, its keys are revoked and kanera commands begin failing with exit code 3 or 4 until the plan is restored.