Command line

The pi-kanban command starts the board. With a command, it talks to a running board instead. The pi skills use it, and you can too. pi-kanban help <command> prints the same text as this page.

The commands find the board through PK_URL, then the server.json file the server writes, then port 3460. Commands that act on one session take --session with a full id or a unique prefix. Without it, they use $PREVIEW_SESSION, else $PI_KANBAN_SESSION_ID.

Server

Run pi-kanban with no command to start the board. A flag wins over its env var.

Flag	Env var	What it does
--port <n>	PORT	Port (default 3460)
--open		Open the board in the browser
--dir <path>	PI_CODING_AGENT_DIR	pi agent dir (default ~/.pi/agent)
--session-dir <dir>	PI_CODING_AGENT_SESSION_DIR	pi session dir (default: sessionDir in pi settings)
--no-terminal		Turn off the board terminal
--new-token		Replace the saved terminal token
--terminal-shell <shell>	PK_TERMINAL_SHELL	gitbash, a program on PATH, or a path
--host <addr>	HOST	Listen address (default 127.0.0.1)
--allowed-hosts <list>	ALLOWED_HOSTS	Extra Host header values, comma-separated

doc

Show documents to the user: link them to a session, or open the preview.

doc link

Link a file or URL to a session, with no modal.

pi-kanban doc link <file|url> [--session <id>]

Argument	What it does
<file|url>	Any file type; one the preview cannot render shows a card with its path. An http(s) URL opens in a new tab.
--session <id>	Session, full id or unique prefix (default: $PREVIEW_SESSION, else $PI_KANBAN_SESSION_ID)

The server keeps the link, so it shows when a browser tab opens later. Prefer this over doc preview while the user works.

pi-kanban doc link ./design.md
pi-kanban doc link https://github.com/org/repo/pull/12

doc unlink

Remove a linked file or URL from a session.

pi-kanban doc unlink <file|url> [--session <id>]

Argument	What it does
<file|url>	The linked path or URL; the file need not exist
--session <id>	Session, full id or unique prefix (default: $PREVIEW_SESSION, else $PI_KANBAN_SESSION_ID)

pi-kanban doc unlink ./design.md

doc list

Print the docs linked to a session.

pi-kanban doc list [--session <id>] [--json]

Argument	What it does
--session <id>	Session, full id or unique prefix (default: $PREVIEW_SESSION, else $PI_KANBAN_SESSION_ID)
--json	Output JSON

doc preview

Open a markdown or HTML file in the preview modal on connected browser tabs.

pi-kanban doc preview <file.md|file.html|url> [--session <id>]

Argument	What it does
--session <id>	Switch focused session in the browser (does not link the file; default: $PREVIEW_SESSION). For a URL, the session it links to (default: $PREVIEW_SESSION, else $PI_KANBAN_SESSION_ID).

The modal opens on the user's screen: the only command that does. HTML renders in a sandboxed iframe; local stylesheets, scripts and images are inlined. Relative paths resolve against the current dir. An http(s) URL is linked to the session instead, and the tab on screen shows an Open button.

pi-kanban doc preview ./notes.md --session $PI_KANBAN_SESSION_ID

show

Show the user a card: a markdown or HTML file you wrote, rendered on the board.

pi-kanban show <file> [--title <text>] [--key <name>] [--base <dir>] [--session <id>]

Argument	What it does
<file>	A markdown, HTML, image or text file (relative paths resolve against the current dir)
--title <text>	Card title (default: the file name)
--key <name>	Card name, e.g. latency-chart: a card with the same key is replaced in place
--base <dir>	Folder that the card's path:line links resolve against, usually the repo root (default: the session cwd)
--session <id>	Session, full id or unique prefix (default: $PREVIEW_SESSION, else $PI_KANBAN_SESSION_ID)

From pi in the board terminal, the card opens in the overlay above the terminal. Elsewhere it opens as a background tab of the session, and --key and --base do nothing. The card refreshes on each save of the file. The show skill has the card guide.

pi-kanban show ./scratch/latency.html --title "p95 latency" --key latency-chart
pi-kanban show ./scratch/plan.md

pane

Add live panes (a URL or a local file) to a session's view, without switching to them.

pane add

Add a pane to a session; it opens as a tab next to Board, in the background.

pi-kanban pane add <url|file> | --companion <id> [--title <text>] [--session <id>] [--json]

Argument	What it does
<url|file>	An http(s) URL, or a local HTML, markdown, text or image file (relative paths resolve against the current dir)
--companion <id>	pi-cost (the session's cost, tokens and models) or pi-inspect (what pi loaded), in place of a target. The board starts the tool; needs the terminal token, like dispatch start.
--title <text>	Tab title (default: the host, file name or companion)
--session <id>	Session, full id or unique prefix (default: $PREVIEW_SESSION, else $PI_KANBAN_SESSION_ID)
--json	Output JSON (the new pane, with frameable: true, false, or null when unknown)

The board does not switch to the new pane; the user opens it. Prints the pane id. The same target added again prints the pane it already has. A URL on the board's own origin is refused, and a file must be one the board can preview. A site whose headers refuse framing (X-Frame-Options, CSP frame-ancestors) is still added, but its pane shows an "Open in new tab" card, and a note line says so.

pi-kanban pane add http://localhost:5173
pi-kanban pane add ./report.html --title Report
pi-kanban pane add --companion pi-cost --session $PI_KANBAN_SESSION_ID

pane rm

Remove a pane from a session.

pi-kanban pane rm <pane-id> [--session <id>]

Argument	What it does
<pane-id>	The id `pane add` or `pane list` printed
--session <id>	Session, full id or unique prefix (default: $PREVIEW_SESSION, else $PI_KANBAN_SESSION_ID)

pi-kanban pane rm p3

pane list

List the panes of a session, in tab order.

pi-kanban pane list [--session <id>] [--json]

Argument	What it does
--session <id>	Session, full id or unique prefix (default: $PREVIEW_SESSION, else $PI_KANBAN_SESSION_ID)
--json	Output JSON ({rev, panes: [{id, kind, target, title, addedAt}], updatedAt})

session

List, search, open, inspect and group pi sessions.

session list

List the active sessions, as the sidebar's Active view shows them (pinned/sticky always included).

pi-kanban session list [--all] [--days <n>] [--project <name>] [--limit <n|all>] [--no-pins] [--json]

Argument	What it does
--all	Every session, active or not
--days <n>	Only sessions modified within the last N days (fractional ok, e.g. 0.5)
--project <name>	Filter by project: an absolute path selects one project, other text matches a part of the path
--limit <n|all>	Max rows to display (default: every active row; 20 with --all). Pinned sessions are kept past it.
--no-pins	Disable always-include and sticky-first ordering for pinned sessions
--json	Output JSON instead of a table

Active: running in the terminal, or with messages and open tasks, live agents, a wait on the user or recent activity. STATUS is idle, active, busy (a task in progress) or wait. When --limit cuts the list, a last line says how many rows it shows of how many (on stderr with --json).

pi-kanban session list
pi-kanban session list --all --days 0.5 --limit 20 --project my-repo

session search

Find sessions whose name or id contains the text, from any transcript.

pi-kanban session search <text> [--limit <n>] [--json]

Argument	What it does
<text>	At least 3 characters; matched against the session name and id
--limit <n>	Max rows (default and max: 20)
--json	Output JSON instead of a table

pi-kanban session search login-redirect

session open

Focus a session in the browser (Active tab).

pi-kanban session open <id>

Argument	What it does
<id>	Full session id, or a unique prefix; `--session <id>` works too

pi-kanban session open $PI_KANBAN_SESSION_ID

session view

Show full session stats (metadata + context window + cost) and the transcript path.

pi-kanban session view <id> [--json]

Argument	What it does
<id>	Full session id, or a unique prefix; `--session <id>` works too
--json	Output JSON instead of formatted sections

To learn what a session did, read its transcript (a .jsonl file, newest lines last).

pi-kanban session view $PI_KANBAN_SESSION_ID

session agents

List the subagents a session has run, and whether it waits for the user.

pi-kanban session agents <id> [--json]

Argument	What it does
<id>	Full session id, or a unique prefix; `--session <id>` works too
--json	Output JSON ({agents, waitingForUser})

The pi-kanban pi package records the runs of pi-subagents. Without both packages in pi, the list is empty.

pi-kanban session agents $PI_KANBAN_SESSION_ID

session cost

Open pi-cost for a session as a board tab: cost, tokens and models.

pi-kanban session cost [<id>]

Argument	What it does
<id>	Full session id, or a unique prefix; `--session <id>` works too (default: $PI_KANBAN_SESSION_ID)

From pi in the board terminal, the board switches to the tab. Needs the terminal token, like dispatch start.

session inspect

Open pi-inspect for a session as a board tab: the system prompt, tools, extensions, skills and context pi loaded.

pi-kanban session inspect [<id>]

Argument	What it does
<id>	Full session id, or a unique prefix; `--session <id>` works too (default: $PI_KANBAN_SESSION_ID)

From pi in the board terminal, the board switches to the tab. Needs the terminal token, like dispatch start.

session pin

Pin (or unpin) a session in the sidebar; every board on this config dir shows it.

pi-kanban session pin <id> [--sticky] [--unpin]

Argument	What it does
<id>	Full session id, or a unique prefix; `--session <id>` works too
--sticky	Set sticky state (always shown in the list)
--unpin	Clear pin/sticky state

pi-kanban session pin $PI_KANBAN_SESSION_ID --sticky
pi-kanban session pin $PI_KANBAN_SESSION_ID --unpin

session group

Move a session into a group in the sidebar.

pi-kanban session group <id> (<group> | --with <session> | --parent <session>) [--no-parent] [--create] [--json]

Argument	What it does
<id>	Full session id, or a unique prefix; `--session <id>` works too
<group>	Group name (any case), path from the top (parent/child) or id, from `group list`
--with <session>	Join the group this other session shows in (id or unique prefix)
--parent <session>	Show the session under this one, indented, when both are in the same list; alone, it also joins its group
--no-parent	Show the session on its own again
--create	Make the group, and the missing parents of a path, when none matches; with --with, it holds both sessions
--json	Output JSON ({group, name, path, created, left, rev})

The session leaves the group it was in. In a group that holds its project, it shows in that project's block.

pi-kanban session group $PI_KANBAN_SESSION_ID "Auth refactor"
pi-kanban session group 3fa9c1 auth-refactor/swarm-1 --create
pi-kanban session group 3fa9c1 --with $PI_KANBAN_SESSION_ID --create
pi-kanban session group 3fa9c1 --parent $PI_KANBAN_SESSION_ID

session ungroup

Take a session out of its group.

pi-kanban session ungroup <id> [--json]

Argument	What it does
<id>	Full session id, or a unique prefix; `--session <id>` works too
--json	Output JSON ({left, rev})

A session whose project is in a group still shows there; move the project on the board.

pi-kanban session ungroup $PI_KANBAN_SESSION_ID

group

Read and change the session groups in the sidebar.

group list

List the groups in sidebar order, nested groups under their parent, with the members the sidebar's Active view shows (active, pinned or sticky).

pi-kanban group list [--all] [--json]

Argument	What it does
--all	Every member, active or not
--json	Output JSON ({rev, groups: [{id, name, parent, transient?, visible, total, members}]}); a session member has title, branch, status, pinned and age, or missing: true; a project member has sessions (its shown sessions)

A project member shows when it has a session the Active view shows. visible/total counts the members shown. A group marked (transient) goes when the board's Active view shows none of its sessions; Keep or a rename on the board, or group rename, keeps it. dispatch start --group and group create --transient make transient groups. Pass a group's name, path (parent/child) or id to session group.

pi-kanban group list
pi-kanban group list --all --json

group create

Make a group, and the missing parents of a path.

pi-kanban group create <name|path> [--transient] [--json]

Argument	What it does
<name|path>	Name of a new top-level group, or a path from the top (parent/child)
--transient	The groups it makes go when the Active view shows none of their sessions
--json	Output JSON ({group, name, path, rev})

Fails when the group exists.

pi-kanban group create "Auth refactor"
pi-kanban group create auth-refactor/swarm-1

group rename

Rename a group; it keeps its place, parent and members.

pi-kanban group rename <group> <new name> [--json]

Argument	What it does
<group>	Group name (any case), path from the top (parent/child) or id, from `group list`
<new name>	The new name
--json	Output JSON ({group, name, path, rev})

pi-kanban group rename auth-refactor "Auth v2"

group rm

Remove a group, as Delete on the board does.

pi-kanban group rm <group> [--json]

Argument	What it does
<group>	Group name (any case), path from the top (parent/child) or id, from `group list`
--json	Output JSON ({removed: {id, name, path}, ungrouped, rev})

Its members leave the group and show as with no group: in their project's group or the top level. Its child groups move up one level.

pi-kanban group rm presales-cloud

group prune

Remove every empty group.

pi-kanban group prune [--dry-run] [--json]

Argument	What it does
--dry-run	List the groups it would remove, and remove none
--json	Output JSON ({removed: [{id, name, path}], dryRun, rev})

Empty: no session whose transcript still exists, no project, and no child group that is not empty. It checks every member, not only the ones the Active view shows.

pi-kanban group prune --dry-run
pi-kanban group prune

task

Read the tasks on the board.

task list

List the tasks of a session, a project, or every session.

pi-kanban task list (<session> | --project <path> | --all) [--status <s>] [--json]

Argument	What it does
<session>	Full session id, or a unique prefix; `--session <id>` works too
--project <path>	Every task of the sessions in this project (absolute path, as in `project list`)
--all	Every task on the board
--status <s>	Only tasks in this status: pending, in_progress or completed
--json	Output JSON instead of a table

pi-kanban task list $PI_KANBAN_SESSION_ID
pi-kanban task list --all --status in_progress

project

Read the projects the board knows.

project list

List known project paths, newest activity first.

pi-kanban project list [--json]

Argument	What it does
--json	Output JSON instead of a table

These are the folders dispatch start --cwd accepts.

dispatch

Start, wait for, list and end pi sessions for tasks in pi-kanban's terminal.

dispatch start

Start pi in pi-kanban's terminal with a task; prints the session id.

pi-kanban dispatch start --cwd <dir> (--spec <text> | --spec-file <path>) [--name <n>] [--group <g>] [--model <m>] [--thinking <level>] [--json] [-- <pi args>...]

Argument	What it does
--cwd <dir>	Folder to run in (any existing folder, default: current dir)
--spec <text>	The task, self-contained; sent as the first message
--spec-file <path>	Read the task from a file
--name <n>	Session name
--group <g>	Add it to this group: a name, path or id. The groups it makes are transient (see `help group list`)
--model <m>	pi model pattern, provider/id (see `pi --list-models`)
--thinking <level>	off, minimal, low, medium, high, xhigh, max
--json	Output JSON
-- <pi args>	Passed to pi as they are, e.g. --tools read,bash. No quotes, % or control characters; pi-kanban sets --session-id, --name, --model and --thinking

Needs the terminal token, so it runs on the machine of the pi-kanban server. The session gets the dispatch_report tool and reports through the board; read the report with dispatch wait. Run pi-kanban skills get dispatch for how to write the spec.

pi-kanban dispatch start --cwd . --spec-file spec.md --name fix-login-redirect --group auth-refactor --thinking high
pi-kanban dispatch start --cwd . --spec "Run the tests and report the failures" --model codemie/gpt-6-luna

dispatch wait

Wait for the reports of sessions this session started, and print them.

pi-kanban dispatch wait <session id>...

Argument	What it does
<session id>	The full id `dispatch start` printed; give several to wait for each in turn; `--session <id>` works too

Prints a report at once when it is already in, and says so when the session's terminal ended without one.

pi-kanban dispatch wait 01a30000-0000-7000-8000-000000000004

dispatch list

List sessions this session started that still run in pi-kanban's terminal.

pi-kanban dispatch list [--all] [--json]

Argument	What it does
--all	Every dispatch on this board
--json	Output JSON

dispatch end

End the terminal of a session this session started.

pi-kanban dispatch end (<session id or prefix> | --name <n>) [--json]

Argument	What it does
<session id or prefix>	A session from `dispatch list`; `--session <id>` works too
--name <n>	The session's --name from dispatch start
--json	Output JSON

Needs the terminal token, like dispatch start.

pi-kanban dispatch end --name api-worker

terminal

Read the terminals running in pi-kanban.

terminal list

List every terminal in pk: dispatched and opened by hand.

pi-kanban terminal list [--json]

Argument	What it does
--json	Output JSON

Read-only. dispatch end ends a terminal this session dispatched; the user ends the others from the board.

skills

Print a skill bundled with this version.

skills get

Print the SKILL.md of a skill.

pi-kanban skills get <name>

Argument	What it does
<name>	Skill name, e.g. dispatch

pi-kanban skills get dispatch