CLI reference
The npm package claude-code-kanban installs one command, claude-code-kanban. With no subcommand it starts the server. With a subcommand it talks to a server that already runs. It needs Node.js 20 or later.
npm install -g claude-code-kanbanclaude-code-kanban --opennpx claude-code-kanban runs the command with no global install. See Install the command.
Help and version
Section titled “Help and version”| Command | Result |
|---|---|
claude-code-kanban --help, -h |
Top-level help: each command with its subcommand names, server flags and environment. |
claude-code-kanban help <command> |
The subcommands of a command, for example help session. |
claude-code-kanban help <command> <subcommand> |
Flags, notes and examples of a subcommand, for example help session list. |
claude-code-kanban <command> [<subcommand>] --help |
Same as help <command> [<subcommand>]. |
claude-code-kanban --version, -v |
Prints the version and exits. |
An unknown command or subcommand, or a command without its subcommand, prints an error or the help, and exits with code 1. A missing argument prints the subcommand’s help. A bad value prints the error and the help command to run. Both exit with code 1.
Server
Section titled “Server”claude-code-kanban with no subcommand starts the server. On start it prints:
Claude Task Kanban running at http://localhost:3541| Flag | Environment variable | What it does |
|---|---|---|
--port <n> |
PORT |
Port to listen on. Default 3541. See Port. |
--open |
Opens the board in your browser after the server starts. | |
--dir <path> |
CLAUDE_CONFIG_DIR, then CLAUDE_DIR |
Claude config dir to read. Default ~/.claude. A leading ~ expands to your home dir. |
--enable-terminal |
CCK_TERMINAL='{"enabled":true}' |
Turns on the embedded terminal. It is off by default when Claude Code Kanban runs alone. |
--terminal-shell <value> |
CCK_TERMINAL_SHELL |
Shell for the terminal: gitbash, a program on PATH (pwsh, cmd, zsh) or a path. Default on Windows is pwsh, then powershell. Elsewhere it is $SHELL, then /bin/sh. |
--host <addr> |
HOST |
Address to listen on. Default 127.0.0.1. |
--allowed-hosts=<list> |
ALLOWED_HOSTS |
Comma-separated extra Host header values to accept. |
--marketplace-url <url> |
MARKETPLACE_URL |
Link to Claude Code Marketplace. |
--cost-url <url> |
COST_URL |
Link to Claude Code Cost. |
--memory-url <url> |
MEMORY_URL |
Link to Claude Code Memory. |
A flag wins over its environment variable.
Set the port with --port <n> or the PORT environment variable. The default is 3541.
claude-code-kanban --port 8080If the port is busy, the server prints Port 3541 in use, trying random port... and listens on a random free port.
Subcommands do not read --port. See How commands find the server.
Network access
Section titled “Network access”The server answers only requests addressed to localhost, and it has no authentication. To reach the board from another machine, use --host and --allowed-hosts. See Network and security.
Terminal banner
Section titled “Terminal banner”When the terminal is on and the server runs outside Claude Code Hub, the server also prints a link with the terminal token:
Terminal enabled - open http://localhost:3541/#t=<token>Open that link to use the terminal. The token changes on each start unless you set CCK_TERMINAL_TOKEN. If the terminal backend cannot load, the server prints Terminal unavailable: <reason>.
Install and uninstall
Section titled “Install and uninstall”| Flag | What it does |
|---|---|
--install |
Installs the Claude Code plugin: hooks, skills and the mod that records context use and cost. |
--uninstall |
Removes what --install added. |
--yes |
With --install: installs the plugin with no prompt. |
--dir <path> |
Installs into or removes from another Claude config dir. CLAUDE_CONFIG_DIR works too. |
claude-code-kanban --installclaude-code-kanban --uninstallclaude-code-kanban --install --dir ~/.claude-work--install asks a [Y/n] question before it installs the plugin, unless you pass --yes. It stops if the claude CLI is missing. For each install step and what --uninstall removes, see Install the integration.
How commands find the server
Section titled “How commands find the server”Every subcommand below sends requests to http://127.0.0.1:<port>. The CLI picks the server in this order:
- The
CCK_URLenvironment variable, a full base URL such ashttp://127.0.0.1:4795. - The
PORTenvironment variable. - The port in
<config-dir>/.cck/server.json. If the process that wrote it no longer runs, the command fails: port 3541 can be the board of another config dir. - 3541, when there is no
server.json.
The server writes server.json on start, so the CLI finds a server that fell back to a random port. Pass the same --dir (or CLAUDE_CONFIG_DIR) that the server uses. If no server answers, the command fails with:
Cannot reach cck server for ~/.claude on port 3541. Start it first with "claude-code-kanban".Commands that change the browser view (doc preview, session open) act on board tabs that are open at that moment. With no tab open, nothing shows. doc link, session pin and session group are also kept by the server, so a tab that opens later shows them.
doc preview is the only command that opens something on the user’s screen. doc link and pane add change nothing on screen, so prefer them while the user works.
Links documents to a session, or shows one in the preview. Where a command takes --session <id>, you can give the full session id or a unique prefix. Without the flag, the CLI uses $PREVIEW_SESSION, else $CLAUDE_CODE_SESSION_ID, which Claude Code sets for its own session. The one exception is doc preview of a file, which reads $PREVIEW_SESSION only, because there the session switches the focus of the board.
doc link
Section titled “doc link”claude-code-kanban doc link <file|url> [--session <id>]Links a file or a web URL to the session in the sidebar. It does not open the preview.
An argument that starts with http:// or https:// is linked as a URL. The server does not check that the page exists, and it stores the URL in a normal form: the scheme and host in lower case, with the rest as you typed it. Other schemes are refused. A file argument resolves against the current directory and must exist.
The server keeps linked documents in <config-dir>/.cck/linked-docs.json, up to 200 per session. Each board tab adds them to its own list when it connects, so a link made with no tab open shows when one opens. In that case the command also prints No browser tab is open; the board shows it when one opens. Unlinking in the board removes the server copy too. See Session log and details.
doc unlink
Section titled “doc unlink”claude-code-kanban doc unlink <file|url> [--session <id>]Removes the link. The file does not need to exist.
doc list
Section titled “doc list”claude-code-kanban doc list [--session <id>] [--json]Prints the documents the server keeps for the session.
doc preview
Section titled “doc preview”claude-code-kanban doc preview <file.md|file.html|url> [--session <id>]Opens a Markdown or HTML file in the preview modal on every connected board tab.
| Flag | What it does |
|---|---|
--session <id> |
Switches the focused session in the browser. It does not link the file to the session. $PREVIEW_SESSION is used when you omit the flag. For a URL, the session that the URL is linked to, with the usual default. |
Put the file path first. The CLI reads the first argument that does not start with -- as the file. On success it prints Preview opened: <absolute path>.
The preview cannot show a web page. With an http:// or https:// URL, doc preview links it to the session, the same as doc link, and prints URL linked to session <id>: <url>. A browser opens a new tab only after a click, so the board tab on screen shows a message with an Open button for 8 seconds. Tabs that are not on screen show the message without the button.
Adds live panes to a session’s view: a web URL or a local file, each a tab next to Board. The commands take --session like doc.
pane add
Section titled “pane add”claude-code-kanban pane add <url|file> [--title <text>] [--session <id>] [--json]Adds a pane and prints its id and title. The board does not switch to it; the user opens the tab. The same target added again prints the pane it already has, marked (already there). A URL on the board’s or the hub’s own origin is refused. A file must be one the board can preview: HTML, markdown, text or an image. A relative path resolves against the current directory.
A site whose headers refuse framing (X-Frame-Options or CSP frame-ancestors) is still added, and a note line says that its pane shows an “Open in new tab” card. --json prints the new pane with frameable: true, false, or null when the check could not tell.
pane rm
Section titled “pane rm”claude-code-kanban pane rm <pane-id> [--session <id>]Removes the pane.
pane list
Section titled “pane list”claude-code-kanban pane list [--session <id>] [--json]Lists the session’s panes in tab order as a table of id, kind, title and target. --json prints {rev, panes: [{id, kind, target, title, addedAt}], updatedAt}.
Puts web pages on the dock rail beside the embedded terminal. An add-on is for this session, or for every session with --global. See Add-ons in the dock.
addon add
Section titled “addon add”claude-code-kanban addon add <url> | --manifest <dir> [--title <text>] [--icon <glyph>] [--param <k=v> ...] [--global [--run <cmd> [--cwd <dir>]] [--offline]] [--session <id>] [--json]Adds a URL to the rail and prints its id and title. The board fills these placeholders for each session, URL-encoded: {sessionId}, {cwd}, {project}, and {<name>} from --param <name>=<value>. A placeholder with no value is refused, as is a URL on the board’s or the hub’s own origin. Quote the URL so the shell keeps the braces. --icon sets one or two characters on the rail button; the default is the first letter of the title. The same URL added again in the same scope prints the entry it already has. A session add-on goes when the session expires; a global one stays until addon rm.
--run <cmd> (with --global and a localhost URL) is the command that starts the page’s server. When you open the add-on and its port does not answer, the board runs the command in --cwd <dir>, with PORT set to the URL’s port, and loads the page once the port answers. The server stops with the board, and addon rm stops it. Its output goes to .cck/addons/<id>.log in the config dir. --run needs the board’s terminal, like dispatch start. To change the command, add the same URL again with a new --run.
--manifest <dir> adds the add-on in <dir> from its addon.json: url, title, icon and run, as a global entry whose command runs in <dir>. The manifest’s id is the entry’s key, so the same manifest added again updates that entry and keeps its id, also after the URL changes. An entry with the same URL and no key takes the key.
--offline (with --global) writes .cck/addons.json of the config dir directly, so it needs no board and no terminal token. A running board picks the change up, and stops a server it runs for the entry when its run, cwd or URL changed, so the next open starts the new one.
addon list
Section titled “addon list”claude-code-kanban addon list [--session <id>] [--json]Lists the global add-ons, then the session’s, as a table of id, scope, title, URL and params. --json prints {global, session, params}, where params holds the session’s own values by add-on id.
addon set
Section titled “addon set”claude-code-kanban addon set <id> <k=v> ... [--session <id>]Sets a param of an add-on for this session only. k= with no value goes back to the add-on’s own value.
addon rm
Section titled “addon rm”claude-code-kanban addon rm <id> | --key <key> [--offline] [--session <id>]Takes the add-on off the rail. A global add-on goes from every session. --key <key> names the global add-on with that key; when none has it, the command prints so and succeeds. --offline removes a global add-on from .cck/addons.json directly, and a running board stops its server.
session
Section titled “session”Lists and opens Claude Code sessions. Where a command takes <id>, you can give the full session id or a unique prefix. An ambiguous prefix prints the matching sessions and fails.
session list
Section titled “session list”claude-code-kanban session list [--all] [--days <n>] [--project <name>] [--limit <n|all>] [--no-pins] [--json]Lists the active sessions, the same ones the sidebar’s Active view shows. The server decides which sessions are active: a session that runs in the board terminal, or a session with messages and open tasks, live agents, a wait on the user or recent activity.
| Flag | What it does |
|---|---|
--all |
Every session, active or not. |
--days <n> |
Only sessions changed in the last n days. Fractions work, for example 0.5. |
--project <name> |
Only sessions of matching projects. An absolute path selects that one project. Other text matches any part of the project path. The match ignores case, and \ and / are the same. |
--limit <n|all> |
Maximum rows. By default the active view has no limit, and --all shows 20. all removes the limit. |
--no-pins |
Treats pinned sessions like other sessions. |
--json |
Prints JSON. Each entry has a pinState field. |
By default pinned and sticky sessions are always in the list, even when they are not active, past the limit or outside --days. --project still removes them. Sticky sessions come first. The table has the columns ID, PIN, STATUS (idle, active, busy or wait), AGE, TASKS, PROJECT and TITLE. When the limit cuts the list, the last line says <n> of <total> shown; --limit all shows every row. With --json that line goes to stderr, and stdout stays an array.
session search
Section titled “session search”claude-code-kanban session search <text> [--limit <n>] [--json]Finds sessions whose name or id contains the text, from every transcript, newest first. The text needs at least 3 characters. --limit sets the maximum rows; the default and maximum are 20. The table has the columns ID, STATUS, AGE, PROJECT and TITLE.
session open
Section titled “session open”claude-code-kanban session open <id>Focuses the session in connected board tabs.
session view
Section titled “session view”claude-code-kanban session view <id> [--json]Prints the session’s title, status, project, branch and task counts. When the plugin’s mod has recorded the session, it also prints the model, context window use, cost and rate limits. The last line is the path of the session’s transcript (Transcript: <path>.jsonl): to learn what a session did, read it. --json prints the full session object, with the path in jsonlPath.
session pin
Section titled “session pin”claude-code-kanban session pin <id> [--sticky] [--unpin]Pins the session in the sidebar. --sticky makes it sticky: always shown, at the top of the list. --unpin clears the pin and the sticky state. The server keeps pins in <config-dir>/.cck/pins.json, so session list and every board on the config dir see them.
session group
Section titled “session group”claude-code-kanban session group <id> (<group> | --with <session> | --parent <session>) [--no-parent] [--create] [--json]Moves the session into a group in the sidebar. <group> is a group name, in any case, or a group id, as group list prints them. The session leaves the group it was in. In a group that holds the session’s project, the session shows in that project’s block; else it shows on the group’s own level. With no group of that name, the command fails and lists the groups; --create makes the group instead. Two groups with the same name need the group id.
<group> can also be a path, such as auth-refactor/swarm-1: a top-level group, then a child group at each step. --create makes the steps that are missing. The sidebar shows a child group inside its parent.
--parent <session> shows the session indented under another session, when both show in the same list of the group. Any session can be a parent; the kind of session does not matter. With no <group> or --with, the session also joins the parent’s group. A move inside the group keeps the parent; a move to another group drops it. --no-parent drops it.
--with <session> puts the session in the group that another session shows in: the group that holds that session, else the group that holds its project. When that session is in no group, the command fails; --create makes a group named after it that holds both sessions. --json prints {group, name, path, created, left, rev}, where path is the group’s path from the top and left is the name of the group the session was in.
session ungroup
Section titled “session ungroup”claude-code-kanban session ungroup <id> [--json]Takes the session out of its group, as dragging it to Ungrouped does. A session whose project is in a group still shows in that group: move the project on the board. --json prints {left, rev}.
The server keeps groups in <config-dir>/.cck/groups.json, and connected board tabs show a change at once.
session plan
Section titled “session plan”claude-code-kanban session plan <id> [--json]Prints the plan that plan mode saved for the session, or No plan saved for session <id>. --json prints {content, slug}.
session agents
Section titled “session agents”claude-code-kanban session agents <id> [--json]Lists the subagents of the session with the columns AGENT, STATUS, AGE, TYPE and DESCRIPTION, and prints Waiting for the user. when the session waits for an answer. It needs the cck hooks in the config dir (--install). --json prints {agents, waitingForUser}.
session cost
Section titled “session cost”claude-code-kanban session cost <id> [--agent <agent id>]Sends the session, or one of its subagents (agent-…), to the board. Under the hub, the board opens it in the Cost tab. It also prints the Cost view URL when cck knows the cost server. It returns 1 when no board page under the hub is open and there is no URL.
group list
Section titled “group list”claude-code-kanban group list [--all] [--json]Lists the session groups in sidebar order, each with the members the sidebar’s Active view shows (active, pinned or sticky), and the projects that have such a session. Each group line ends with visible/total, the members shown and all members. --all shows every member. The table has the columns ID, STATUS, AGE, PIN and NAME. A nested group is indented under its parent, and its members under it. Pass a name, a path or an id from this list to session group.
A temporary group, made by dispatch start --group or group create --transient, has (transient) after its name. The board removes it when its Active view shows none of its sessions. See Groups from dispatch.
--json prints {rev, groups}, each group as {id, name, parent, visible, total, members}, plus transient: true for a temporary group. A session member has title, branch, status, pinned and age, so you do not need session list to describe it. A session member whose session is gone has missing: true. A project member has sessions, the count of its sessions shown.
group create
Section titled “group create”claude-code-kanban group create <name|path> [--transient] [--json]Makes a group. A path, such as auth-refactor/swarm-1, also makes the parents that are missing. The command fails when the group exists. --transient makes the new groups temporary: the board removes them when its Active view shows none of their sessions. --json prints {group, name, path, rev}.
group rename
Section titled “group rename”claude-code-kanban group rename <group> <new name> [--json]Renames a group. It keeps its place, its parent and its members. A temporary group becomes a group that stays. <group> is a name, a path or an id, as for session group. --json prints {group, name, path, rev}.
group rm
Section titled “group rm”claude-code-kanban group rm <group> [--json]Removes a group, as Delete on the board does. Its sessions show where they would show with no group: in their project’s group or the top level. Its child groups move up one level. --json prints {removed: {id, name, path}, ungrouped, rev}.
group prune
Section titled “group prune”claude-code-kanban group prune [--dry-run] [--json]Removes every empty group. A group is empty when no member is live and every child group is empty, so a parent that holds only empty groups goes too. A session member is live while its transcript exists, its terminal runs or its dispatch starts; a project member is always live. --dry-run lists the groups and changes nothing. --json prints {removed: [{id, name, path}], dryRun, rev}.
task list
Section titled “task list”claude-code-kanban task list (<session> | --project <path> | --all) [--status <s>] [--json]Lists tasks. Give one source: a session id or unique prefix, --project with a project path (as project list prints it), or --all for every task on the board. --status keeps only tasks in that status, for example in_progress. The table has the columns ID, STATUS and SUBJECT, plus SESSION for --project and --all. The command only reads; to change a task, use the board.
project list
Section titled “project list”claude-code-kanban project list [--json]Lists the project paths the board knows, newest activity first. These are the folders dispatch start --cwd accepts. A path under the OS temp dir is marked (temp).
claude-code-kanban new [prompt...] [--cwd <dir>] [--name <n>] [--model <m>] [--json] [-- <claude args>...]Starts Claude Code in the board’s embedded terminal from any shell, and shows it on the board. Use it in place of claude when you want the session in the board and not in the shell you typed it in.
| Flag | What it does |
|---|---|
[prompt...] |
The first message. The words are joined with spaces. With no words, the session waits for your first message. |
--cwd <dir> |
Folder to run in. Default is the current folder. |
--name <n> |
Session name. |
--model <m> |
fable, opus, sonnet or haiku. |
--json |
Prints {session, cwd}. |
-- <claude args> |
Passed to claude as they are, for example --permission-mode auto. |
Every open board tab adds the session’s card and opens its terminal. Under Claude Code Hub, the hub also switches to the Kanban tab. With no board tab open, the command fails with 409 no board tab is open, because the session would run where no one sees it. When tabs are open but none can show the terminal in 3 seconds (the terminal is off there, or its terminal token is from an earlier server run), the server ends the session and the command fails with 409 no open board tab can show the terminal. Like dispatch start, it needs the terminal token, so it runs on the machine of the cck server. The session is not marked as dispatched.
claude-code-kanban newclaude-code-kanban new fix the login redirect -- --permission-mode autodispatch
Section titled “dispatch”Starts a Claude Code session in the embedded terminal to do a task. See Dispatch tasks to other sessions for how to use it.
dispatch start
Section titled “dispatch start”claude-code-kanban dispatch start --cwd <dir> (--spec <text> | --spec-file <path>) (--child | --group <g>) [--name <n>] [--model <m>] [--worktree [name]] [--task-list [id]] [--json] [-- <claude args>...]| Flag | What it does |
|---|---|
--cwd <dir> |
Folder to run in. Default is the current folder. It can be any folder that exists. |
--spec <text> |
The task. Write it so that it makes sense with no other context. |
--spec-file <path> |
Reads the task from a file. |
--name <n> |
Session name: up to 80 letters, digits, spaces, ., _ and -. The first character must be a letter or a digit. It is also the session’s peer name for SendMessage. |
--child |
The work is part of the current session’s work. The new card shows under the current session’s card. Works only inside a Claude Code session. See Place in the sidebar. |
--group <g> |
Separate work. Adds the new session to this session group: a name, a path such as auth-refactor/api, or an id. A missing group is made as a temporary group. |
Pass exactly one of --child and --group.
| --model <m> | fable, opus, sonnet or haiku. |
| --worktree [name] | Runs the session in a new git worktree. |
| --task-list [id] | The session uses this task list instead of its own. With no value, it uses the current session’s list. Off unless given. See Share one task list. |
| --json | Prints JSON. |
| -- <claude args> | Everything after -- goes to claude as it is, for example -- --permission-mode auto. See Pass claude flags. |
On success it prints:
Started session <uuid> in <cwd> [child | group]cck sends no report back. Say in the spec how the session reports, for example with SendMessage.
dispatch start reads the terminal token from <config-dir>/.cck/terminal-tokens/<port>.json, where <port> is the port of the board it reaches. The server writes that file only when the terminal is on. Without it the command fails with No terminal token for <dir> at <board-url>. The cck server must be running with the terminal enabled. Other refusals:
404 folder does not existwhen the folder does not exist.429 30 terminals are open; end one firstwhen all terminals are in use (30 by default).400 invalid name,invalid worktree name,invalid task list id,invalid modelorinvalid promptwhen a value is not valid or the spec is longer than 32 KB.invalid claude arg: no quotes, % or control characters, orcck sets <flag>for a flag cck owns, after--.
The command records the session that ran it, from CLAUDE_CODE_SESSION_ID, as the parent. dispatch list uses it.
dispatch list
Section titled “dispatch list”claude-code-kanban dispatch list [--all] [--json]Lists the sessions that the current session started and that still run in the board’s terminal. Outside Claude Code, where CLAUDE_CODE_SESSION_ID is not set, it lists every one on the board. --all lists every one on this board.
A session leaves the list when its terminal ends. The board saves the list, so after a server restart it lists again the sessions that the board resumes.
dispatch end
Section titled “dispatch end”claude-code-kanban dispatch end (<session id or prefix> | --name <n>) [--json]Ends the terminal of one session from dispatch list, matched by its id, an id prefix or its --name. It finds the session in the same list as dispatch list without --all, so inside Claude Code it ends only sessions the current session started. When no session or more than one session matches, it prints the matches and exits with 1. It reads the terminal token the same way as dispatch start. The worktree stays.
terminal list
Section titled “terminal list”claude-code-kanban terminal list [--json]Lists every terminal that runs in the board, newest first, with the columns SESSION, AGE, KIND, NAME and CWD. KIND is one of these:
| Kind | Terminal |
|---|---|
dispatch (yours) |
Started by the current session with dispatch start. |
dispatch |
Started by another session, or from outside Claude Code, with dispatch start. |
claude |
A Claude Code session opened on the board. |
shell |
A plain shell opened on the board. |
kanbot |
Kanbot. |
The command only reads. When the list has a terminal of yours, it adds a line that says to end it with dispatch end. The user ends the other terminals from the board. --json prints the rows as the server returns them, with dispatched: {parent} on a dispatched terminal and kanbot: true on Kanbot.
skills get
Section titled “skills get”claude-code-kanban skills get <name>Prints a guide that ships with this version. The only guide now is dispatch, which the dispatch skill loads. An unknown name prints the known names.
Environment used by the CLI
Section titled “Environment used by the CLI”| Variable | Used by |
|---|---|
CCK_URL |
Full base URL that subcommands connect to. Wins over PORT and server.json. |
PORT |
The server port, and the port that subcommands connect to. |
CLAUDE_CONFIG_DIR, CLAUDE_DIR |
Config dir, when --dir is not given. |
CLAUDE_CODE_SESSION_ID |
Set by Claude Code. Default for --session in doc and pane, after PREVIEW_SESSION (see doc). dispatch start records it as the parent. dispatch list, dispatch end and terminal list use it to find your dispatches. |
PREVIEW_SESSION |
First default for --session in doc and pane. |
For server and terminal settings, see Configuration.