Kanera CLI
@kanera/cli puts Kanera in your terminal so you can find cards, manage work, and automate tasks from shell scripts. AI coding agents that can run shell commands can also use it, with no MCP client configuration and no long-running server.
Install
Requires Node.js 22 or newer. Run this command in your terminal to install the kanera command globally:
npm install --global @kanera/cli
The published package has no runtime dependencies. Confirm the command is available:
kanera commands
To try it without installing:
npx @kanera/cli commands
Authenticate
Sign in through your browser:
kanera auth login
auth login uses the OAuth device flow, the same way Claude and Codex connect. It prints a link and a short code, opens the link in your browser, and finishes on its own once you approve. Check that the code on the page matches your terminal before choosing Allow access. Over SSH or on a headless machine, open the link on any device; pass --no-browser to skip launching one.
The CLI then stores a short-lived access token and a refresh token, and renews them automatically. The sign-in appears under Settings -> AI agents as Kanera CLI (your computer's name), and changes it makes are labelled with that name in card history. Revoke it there, or run kanera auth logout, which ends it on the server too.
Name the agent
When an AI agent drives the CLI, name it at sign-in so its work is labelled as that agent's:
kanera auth login --agent "Claude Code"
The sign-in then appears as Claude Code (Kanera CLI on your computer's name) on the consent screen, under Settings -> AI agents, and as via Claude Code (Kanera CLI on …) on every comment, card change, notification, and agent run it makes. KANERA_AGENT_NAME sets the same name from the environment. The name is fixed for the life of the sign-in, so give each agent its own profile with --profile when several share a machine. --agent does not apply to API keys, because work done with a personal key is recorded as you.
Use an API key instead
Use an API key for CI, cron jobs, and unattended agents, where nobody is present to approve a browser sign-in, or when you want a credential that Kanera enforces as read-only. 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 --with-api-key
On hosted Kanera, this opens your API keys page at https://board.kanera.app/settings/api-keys, prompts for the key with the terminal echo suppressed so it never lands in your shell scrollback, verifies it against Kanera, and stores it.
Changes made with a personal key are recorded as you, with no via badge, so a browser sign-in is the better choice when you want an agent's work labelled. 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 my-day # overdue, due this week, idle, and Up next in one view
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
kanera separator create "$BOARD" "$LIST" "This week" --color blue
kanera capture "Renew the venue insurance" # a task in your private Scratchpad Inbox, no board needed
kanera remind MKT-42 "friday 3pm" # a private reminder on a card, up to 8 weeks ahead
kanera remind clear MKT-42
kanera reminders # your pending reminders, soonest first
kanera watch MKT-42 # follow a card's activity; kanera unwatch MKT-42 stops
kanera inbox # your latest notifications; then kanera inbox --since "<cursor>" for only what is new
kanera card upload-link MKT-42 test-run.log # a one-time URL; then curl -fsS -T ./test-run.log "<uploadUrl>"
kanera card attachment MKT-42 "$ATTACHMENT" # an attachment's text, or an image's details
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. Date arguments accept YYYY-MM-DD or phrases such as "tomorrow 1pm" or "next friday", read in your profile's time zone: kanera card update MKT-42 --changes.dueDateLocalDate "friday 3pm".
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 cards.bulk_move --boardId "$BOARD" --cardIds[] MKT-42 --cardIds[] MKT-43 --listId "$LIST"
kanera help cards.bulk_move
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.
Board separators
Create a titled, optionally colored divider and position it relative to a card or another separator:
kanera separator create "$BOARD" "$LIST" "This week" --color blue \
--anchor.side before --anchor.item.type card --anchor.item.id "$CARD"
kanera separator move "$SEPARATOR" "$LIST" \
--anchor.side after --anchor.item.type separator --anchor.item.id "$OTHER_SEPARATOR"
kanera separator update "$SEPARATOR" --title "Next up" --color green
kanera separator delete "$SEPARATOR"
For a list edge, pass --anchor.side after --anchor.item null for the top or --anchor.side before --anchor.item null for the bottom. Separator deletion changes no cards. kanera card move accepts the same typed anchor, so cards can be placed immediately before or after a separator.
Card relationships
These commands read left to right: the first card blocks the second. Both must belong to the same workspace.
kanera card block MKT-42 WEB-18 # MKT-42 blocks WEB-18
kanera card unblock MKT-42 WEB-18 # remove that dependency
kanera card relate MKT-42 WEB-18 # connect them without a required order
kanera card WEB-18 # full detail includes relationships
kanera work --filters.blockedOnly true # find waiting work
kanera work --filters.atRiskOnly true # blocker overdue or due after the card
For the inverse direction or several targets, use the underlying tool:
kanera call cards.set_relations --cardId WEB-18 --direction blocked_by \
--otherCardIds[] MKT-42 --otherCardIds[] MKT-43
Pass --remove true to remove the selected relationships. Inspect failed and notAttemptedCardIds on a partial result: successful additions remain saved when another target is refused. A result with relationsUnavailable names successful writes in addedCardIds or removedCardIds when the final read failed. Successful removals are also reported beside per-card refusals. See Card Relationships and Blocking for permissions, handoffs, and completion warnings.
Dependency graphs
Use kanera deps to read prerequisites and downstream work in one call:
kanera deps MKT-42 # one card's blocking neighbourhood
kanera deps --boardId "$BOARD" # chains touching a board
kanera deps --workspaceId "$WORKSPACE" # chains in a workspace
Pass exactly one scope. A card argument accepts its key, UUID, or canonical URL. Card-scoped output adds focus with direct blockedBy / blocks IDs, transitive upstream / downstream IDs in nearest-first order, relatedTo, and onMap. Cards include readable board and list names and active/off-map blocker counts. The result is capped at 400 cards and reports truncated. See the MCP graph reference.
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 cards.update --json-args '{"cardId":"MKT-42","changes":{"title":"Revised"}}'
An array argument also accepts one JSON array, the simplest way to pass a list of objects. This builds a checklist, its items, and a sub-checklist in one call, then completes two items in another:
kanera call checklists.create --cardId MKT-42 --title Launch \
--items '[{"text":"Prepare release","subChecklists":[{"title":"Verification","items":[{"text":"Run smoke tests"}]}]},{"text":"Announce launch"}]'
kanera call checklists.update_items --cardId MKT-42 \
--updates '[{"itemId":"<itemId>","changes":{"completed":true}},{"itemId":"<itemId>","changes":{"completed":true}}]'
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, which holds either a browser sign-in or an API key. An explicit key always wins, so a CI job never runs through a developer's personal sign-in.
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 | Sign in through the browser (--with-api-key or --api-key for a key) |
kanera auth status | Show the active credential and its scope |
kanera auth list | List stored profiles |
kanera auth token | Print the active API key, for KANERA_API_KEY=$(kanera auth token). Browser sign-ins have no key to print. |
kanera auth logout | Remove a stored profile, and end a browser sign-in on the server |
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.
Updates
The CLI checks npm for a newer release at most once a day. When it finds one, it asks after your command finishes:
A new Kanera CLI is available: 1.7.0 → 1.8.0
Update now? [y/N]
Answer y to run npm install --global @kanera/cli@<version>. Any other answer skips the update. The CLI does not ask again for a day, and prints the command so you can update later.
The CLI only asks when a person is at an interactive terminal. It never checks or asks in --json or --quiet mode, when input or output is not a terminal (which covers agents, scripts, and pipes), when CI is set, or when you run it through npx, which fetches its own copy. Set KANERA_NO_UPDATE_CHECK=1 to turn the check off entirely.
Self-hosted Kanera
A browser sign-in is tied to your deployment's MCP address, so pass it during login:
kanera auth login --mcp-url https://your-kanera.example/mcp
Or set KANERA_MCP_URL. The CLI reads the MCP server's OAuth metadata to find your Kanera sign-in page, so nothing else needs configuring.
For an API key, point the CLI at your public API instead, and it is saved with the profile:
kanera auth login --with-api-key --url https://api.your-kanera.example
The CLI cannot tell where a self-hosted web app lives from its API origin, so with an API key it does not open a browser. Create the key in your Kanera web app under Settings -> API Keys, then paste it at the prompt.
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. With a browser sign-in, kanera mcp relays your Kanera MCP server and renews the token as it runs. It speaks both the current MCP protocol and the earlier revisions, so any MCP host can launch it. Event subscriptions are not offered over stdio, since a local host has no hosted callback to deliver to. If your client supports remote MCP with OAuth itself, you can also connect it directly; see Connect Kanera to your AI agent.
Plan requirements
Browser sign-ins and personal API keys work on every hosted plan, including Free, and self-hosted Kanera has no plan checks. Workspace and board API keys need Pro or the Pro trial; if a hosted organisation moves to Free they are revoked, and kanera commands using one fail with exit code 3 or 4 until the plan is restored. Requests follow the API rate limits of the board's organisation, and the CLI waits and retries when it is briefly over them.