Work with coding agents from the terminal

A terminal coding agent such as Claude Code or Codex can take a Kanera card from pick-up to done: read the card, announce that it is working, report progress, flag when it needs a person, and mark the card complete. This guide sets that loop up with the Kanera CLI, which works for any agent that can run shell commands.

Connected MCP tools come first

If your agent can connect to Kanera's hosted MCP server, use that instead. Paste the setup prompt from Connect Kanera to your AI agent and the agent gets the same tools over OAuth, with its work labelled via <agent>. The CLI is the route for an agent that has a shell but no MCP connection. The loop below is the same either way; only the transport changes.

Install the CLI once on the machine the agent runs on. It needs Node 22 or newer.

npm install --global @kanera/cli
kanera auth login

kanera auth login opens your API keys page, prompts for a key without echoing it, checks it against Kanera, and stores it. Create the key in Profile settings -> API keys. Then confirm what the agent will be able to do:

kanera whoami     # the user and the key's scope
kanera doctor     # credentials, connectivity, and the API address in use

For a sandbox or CI job, skip the stored profile and set KANERA_API_KEY instead. See Kanera CLI for named profiles and self-hosted addresses.

Read-only or write

Choose the key's scope for the job, not for convenience.

Read-only suits an agent that only needs to find and read work: triaging, summarising a card before you start, or answering "what is on my plate?". Kanera refuses every change at the API, whatever the agent tries.
Write is needed for everything else on this page: opening a run, commenting, and completing cards. Kanera still checks your role on each board, so the agent cannot change a board where you are an Observer.

A refused write exits with code 4, distinct from an ordinary failure, so the agent can stop and tell you rather than retry. Agent security covers how to scope an agent's access.

Install the agent instructions

kanera setup writes instructions that teach the agent how to use the CLI safely: check the key's scope first, discover commands with kanera commands --json instead of guessing, use --quiet or --json when parsing output, and treat destructive tools as needing an explicit request.

kanera setup claude            # writes .claude/skills/kanera/SKILL.md in the current directory
kanera setup claude --global   # writes ~/.claude/skills/kanera/SKILL.md for every project
kanera setup codex             # adds a Kanera section to AGENTS.md in the current directory
kanera skill                   # prints the skill document, for any other agent

setup claude installs Kanera's Agent Skill, which Claude Code loads when Kanera comes up. It will not overwrite an existing SKILL.md; re-run with --force to replace it after upgrading the CLI.
setup codex creates AGENTS.md if it does not exist, or appends a short Kanera section. It is safe to re-run: when the file already documents Kanera, it changes nothing. kanera setup agents does the same, for any agent that reads AGENTS.md.

The CLI's instructions cover reading and changing work. They do not tell the agent to open runs, so add the project instructions below if you want that.

The work loop

Each step below is a command the agent runs. Card arguments accept a key such as MKT-42, a card id, or a card URL.

1. Pick up work

kanera work --json                          # your assigned work across every board
kanera work --filters.q "checkout" --json   # narrowed by card text
kanera priorities --json                    # your ranked Up next queue
kanera card MKT-42 --json                   # the card itself: description, checklists, fields
kanera card history MKT-42 --json           # its activity and comments

kanera priorities is useful when you keep an Up next queue: the agent can take the top card rather than choosing for itself.

2. Open a run

Before starting multi-step work, check that nobody else is on the card, then open a run. Runs are not named commands, so they use kanera call:

kanera call runs.list --cardId MKT-42 --json

RUN_ID=$(kanera call runs.start --cardId MKT-42 \
  --title "Fixing the checkout rounding bug" \
  --externalUrl "https://github.com/acme/shop/pull/318" \
  --quiet | jq -r .id)

The card tile now shows a live chip saying the agent is working, and card detail shows the run with its title and progress note. --externalUrl is optional; give it the pull request, branch, or session log a person can open. See Agent runs and attribution for what everyone else sees.

3. Report progress

Update the run as the work moves. Every update is also a heartbeat, and a run that goes fifteen minutes without one is marked stalled, so on long tasks the agent should update at least every ten minutes.

kanera call runs.update --runId "$RUN_ID" --summary "Reproduced; fix drafted, running the test suite"

The run summary is a status line that each update replaces. For anything the team should keep, comment on the card:

kanera comment MKT-42 "Root cause: totals were rounded per line, not per order. Fix in PR 318."

Comments are not idempotent. If a comment command fails ambiguously, check the card's comments before retrying, or pass the same --idempotencyKey UUID on the retry.

4. Flag a blocker

When the agent needs a decision, an approval, or access it does not have, mark the run blocked and say what it needs:

kanera call runs.update --runId "$RUN_ID" --status blocked \
  --summary "Need a decision: round half up or half even?"
kanera comment MKT-42 "Blocked: should order totals round half up or half even? Both are drafted in PR 318."

The chip turns amber and card detail shows Waiting on you. Marking a run blocked does not notify anyone by itself, which is why the comment matters: it reaches the card's watchers and assignees. When the agent resumes, it sets the run back to --status running.

5. Finish

Close the run with an outcome, then complete the card:

kanera call runs.update --runId "$RUN_ID" --status succeeded \
  --summary "Merged PR 318; rounding is per order and the suite is green."
kanera card done MKT-42

The run's closing summary becomes a finished row in the card's activity. If the work did not land, end the run with --status failed or --status cancelled and a summary saying why, and leave the card open. An ended run cannot be changed; if work resumes later, start a new run.

To move the card to another list rather than completing it, use kanera card move; run kanera help cards.move for its anchor arguments.

Who the work is attributed to

The CLI authenticates with an API key, and that decides how the agent's work is labelled:

Key	Comments and card changes	Run chip label
Personal API key	As you, with no via badge	API client
Workspace or board API key	As the key's name	The key's name

This is the one real difference from an OAuth connection over MCP, where the agent's work carries a via <agent> badge, groups separately in your notifications, and is kept apart from your own work in Work Done. If you want the team to see which changes an agent made, connect the agent over MCP with OAuth; see Set up Claude or Set up Codex. kanera mcp, the CLI's local MCP server, uses the same stored key and so the same attribution as the CLI.

Add it to your project instructions

To make the loop the default, add your own section to the repository's CLAUDE.md or AGENTS.md. This text is yours to adapt; Kanera does not generate it.

## Kanera

Work is tracked in Kanera. Use the `kanera` CLI, not the web interface.

- Before starting a card, run `kanera card <key> --json` and `kanera call runs.list --cardId <key>`.
  If another run is live, stop and tell me.
- Open a run with `kanera call runs.start --cardId <key> --title "<short description>"` and keep its id.
- Update it with `kanera call runs.update --runId <id> --summary "<progress>"` at least every
  10 minutes while working.
- If you need a decision from me, set `--status blocked`, and comment on the card saying what you need.
- When done, end the run with `--status succeeded` and a one-line outcome, comment with a summary
  and any pull request link, then run `kanera card done <key>`.
- If you stop without finishing, end the run with `--status failed` or `--status cancelled`.
  Never leave a run open when you are not working.
- If a command exits with code 4, the key cannot make that change. Stop and tell me.

Pair it with a write key. With a read-only key, keep only the reading steps.

Install and sign in​

Read-only or write​

Install the agent instructions​

The work loop​

1. Pick up work​

2. Open a run​

3. Report progress​

4. Flag a blocker​

5. Finish​

Who the work is attributed to​

Add it to your project instructions​

Related pages​

Install and sign in