kan

name	kan
description	Manage kanban boards using the Kan CLI. Use when working with tasks, cards, boards, columns, or project tracking via the kan command.

Kan CLI

Kan is a file-based kanban board CLI. All data lives in .kan/ as plain files.

Full documentation ships inside the binary: run kan docs for the topic list, kan docs <topic> for a page, kan docs all for everything. Prefer it over fetching the web copy at amterp.dev/kan/docs, which is only a fallback for builds older than the command.

Getting Help

Every command supports --help for detailed usage:

kan --help
kan add --help
kan column --help

Board Setup Wizard

When a user asks to create a new board (kan board create) or initialize a new Kan project (kan init), run this interactive setup process rather than creating a board with defaults. This applies to both new projects and additional boards.

Before writing any config, run kan docs configuration and kan docs custom-fields to double-check available options and TOML structure.

Step 1: Understand the Project and User

Before suggesting anything, learn about what the user is building:

• What kind of project is this? (software, personal, team, open source, etc.)
• What workflow are they trying to track?
• Is this their first board or are they adding to an existing setup?

This context lets you make relevant, project-specific suggestions in later steps.

Also gauge whether the user is already familiar with Kan. If it's unclear, ask. If they're new, explain concepts (like wanted fields, card display roles, enum-set types) as they come up during the wizard. If they're experienced, keep it snappy.

Step 2: Columns

Ask the user what columns they want. Offer these templates as inspiration - they are not rigid. The user can mix, match, rename, add, or remove columns freely.

Simple - Good default for most projects:

Column	Description	Limit	on_move_default_position
backlog	Planned work not yet started		bottom
next	Ready to be picked up next	5	bottom
in-progress	Currently being worked on	5	top
done	Completed work		top

Prioritized Backlog - Splits the backlog for triage:

Column	Description	Limit	on_move_default_position
backlog-lo	Low priority planned work		bottom
backlog-hi	High priority planned work	10	bottom
next	Ready to be picked up next	5	bottom
in-progress	Currently being worked on	5	top
done	Completed work		top

With Ideas - Adds a staging area for uncommitted thoughts:

Column	Description	Limit	on_move_default_position
uncommitted	Ideas and thoughts not yet committed to		bottom
backlog	Planned work not yet started		bottom
next	Ready to be picked up next	5	bottom
in-progress	Currently being worked on	5	top
done	Completed work		top

Full - Prioritized backlog with ideas column:

Column	Description	Limit	on_move_default_position
uncommitted	Ideas and thoughts not yet committed to		bottom
backlog-lo	Low priority planned work		bottom
backlog-hi	High priority planned work	10	bottom
next	Ready to be picked up next	5	bottom
in-progress	Currently being worked on	5	top
done	Completed work		top

Important: Every column should have a description. Descriptions serve as self-documentation and help guide AI agents using the board. Suggest descriptions if the user doesn't provide them.

Column Limits: Columns can have an optional limit that caps how many cards they hold. When a column is full, adding or moving cards into it is refused. This is a core kanban practice for controlling flow. Suggest limits for active workflow columns (like next and in-progress) - leave unbounded columns (like backlog and done) without limits. The defaults in the templates above are good starting points; adjust based on preference.

Card Insertion: on_move_default_position decides where a card lands when it is moved into a column without saying where - via kan move, kan edit -c, the web UI's right-click move, column dropdown, or advance shortcut. Ask which model each column follows rather than taking the default silently:

• Queue columns, where position encodes priority (backlog, next, uncommitted), want bottom. An arriving card joins the back of the line instead of jumping ahead of work already triaged.
• Activity columns, where position encodes recency (in-progress, done), want top, so the card just touched is the one on screen.

top is the default when unset. The values in the templates above follow this rule and are good starting points. This does not affect kan add, which always appends, and an explicit placement flag always overrides it. Dragging is unaffected too - a drag always names a slot.

The first column in the list becomes the default column for new cards.

Step 3: Custom Fields

Walk the user through what fields they want on their cards. For each field, discuss:

• What type? (string, enum, enum-set, free-set, date, boolean)
• What are the options/values? (for enum and enum-set types)
• Descriptions for the field itself and each of its options
• Should this field be wanted? (If the user is new, explain: wanted fields generate a warning when a card is created without them, encouraging consistent metadata across cards)

Type Field (Strongly Recommended)

Unless the user explicitly doesn't want one, recommend a type field (enum, wanted). This categorizes what kind of work a card represents. Suggest these default values:

Value	Color	Description
bug	#dc2626	A defect in existing functionality
enhancement	#2563eb	An improvement to existing functionality
feature	#16a34a	New functionality to be added
chore	#4b5563	Maintenance, refactoring, or housekeeping

The user can customize these - add, remove, rename, or change descriptions to fit their project.

Other Fields

The type field alone is often enough, especially for new boards. Lean toward simplicity. But if the user asks about other fields, or if their project clearly calls for one based on what you learned in Step 1, here are some examples to get their thinking going:

• labels (enum-set) - Flexible tagging. Example values: ai-hi (well-suited for autonomous AI work - low complexity, little judgment needed), ai-lo (likely suitable for AI but less certain). Cards without an AI label are implicitly not suitable for autonomous AI work.
• effort (enum) - T-shirt sizing for rough estimation: xs, s, m, l, xl
• area (enum-set) - What part of the project a card touches, e.g. backend, frontend, infra, docs

Don't actively suggest these - just mention that additional fields are possible and offer examples if the user is interested.

Step 4: Card Display

Configure how fields appear on cards in the web UI and CLI output. Apply sensible defaults without overwhelming the user with implementation details:

• If the user has a type field, set it as the type_indicator (colored badge on each card).
• Any enum-set or free-set fields (like labels) should go in badges (chip-style labels on cards).
• Other fields like dates or effort can go in metadata (small text below the card).
• If the user has an enum field they want to use for visual emphasis (like priority or urgency), it can be assigned to tint to wash the card's background with that option's color.
• To make the board open already sorted by a field (instead of manual order), set default_sort = "<field>" under [card_display], plus default_sort_desc = true for descending. This affects the web board view on load; anyone can still re-sort or switch to Manual order for their own session, and it never changes saved card positions. Only set it if the user asks for a default ordering - don't apply it proactively.

For new users, just set these defaults and briefly mention that their type will show as a colored badge on cards and any tags will show as labels. Don't expose config key names like type_indicator or badges unless the user asks for details.

Step 5: Pattern Hooks (Optional)

Pattern hooks automate actions when cards are created with titles matching a pattern. This is entirely optional - offer it, but don't push it.

If the user set up a type field, suggest the type shortcut hook: when creating a card in the web UI with !bug anywhere in the title (e.g. !bug Fix login crash or Fix login crash !bug), the hook automatically strips the !bug and sets the type field to bug. It also supports aliases like !feat for feature and !enh for enhancement.

For newcomers, keep the explanation focused on what it does rather than how: "This is a convenience shortcut. Instead of setting the type field manually after creating a card, you can just include !bug, !feat, !chore, etc. anywhere in your title and it gets set for you automatically."

If the user wants this hook:

1. Detect Rad: Silently run rad -v. If Rad is installed, ask whether they'd prefer the hook written in Rad or Bash. If not installed, silently default to Bash.

2. Create the hook script at .kan/hooks/type-shortcut.rad (or .sh if writing Bash). Here's the Rad version - translate to Bash if needed:

#!/usr/bin/env rad
---
Pattern hook for setting card type from title shortcuts like !bug, !feat, !chore.
Receives card_id and board_name as arguments from Kan pattern hooks.
---
args:
    card_id str
    board_name str

type_aliases = {
    "feat": "feature",
    "enh": "enhancement",
}

// Rad propagates a non-zero exit as an error, so a failed command is handled
// with a catch: block - testing the exit code on the next line never runs.
code, stdout = quiet $`kan show {card_id} -b {board_name} --json` catch:
    print_err("type-shortcut: cannot read card {card_id} (exit {code})")
    exit(1)

title = parse_json(stdout)["card"]["title"]

if not matches(title, "![a-zA-Z]+", partial=true):
    exit(0)

keyword = replace(title, ".*?!([a-zA-Z]+).*", "$1").lower()
card_type = keyword in type_aliases ? type_aliases[keyword] : keyword

code, stdout = quiet $`kan board describe -b {board_name} --json` catch:
    print_err("type-shortcut: cannot read board {board_name} (exit {code})")
    exit(1)

options = parse_json(stdout)["board"]["custom_fields"]["type"]["options"]
valid_types = [o["value"] for o in options]

// Bail before editing on an unrelated bang ("Fix the !important override").
// kan edit still applies -t when -f fails validation, so an unchecked edit
// would rename the card and leave the type unset.
if card_type not in valid_types:
    exit(0)

new_title = replace(title, "(?i)\\s*!{keyword}\\b\\s*", " ").trim()
new_title = replace(new_title, "\\s+", " ")

// A title that was nothing but the shortcut keeps its original text.
title_arg = new_title == "" ? "" : `-t "{new_title}"`

quiet $`kan edit {card_id} -b {board_name} {title_arg} -f type={card_type}` catch:
    print_err("type-shortcut: failed to set type={card_type} on card {card_id}")
    exit(1)

print("Set type to '{card_type}'")

The hook only strips the token it matched, and only after confirming it names a real type on that board - so a title carrying an unrelated bang is left exactly as typed. A Bash port needs jq to read the two JSON responses; keep the validation step either way, since skipping it renames cards on a typo.

3. Make executable: chmod +x .kan/hooks/type-shortcut.rad (or .sh)

4. Add the hook to the board config:

[[pattern_hooks]]
name = "type-shortcut"
pattern_title = "![a-zA-Z]+"
command = ".kan/hooks/type-shortcut.rad"  # or .sh for bash

5. Warn about background services: hooks inherit the environment of whatever started Kan. If the user runs kan serve as a background service (launchd, systemd) rather than from a terminal, it gets a bare PATH (/usr/bin:/bin:/usr/sbin:/sbin). The Rad hook needs rad on that PATH, and both variants shell back into kan — so a hook that works from the CLI can still fail under kan serve. Tell them to set an explicit PATH in the service definition if they run Kan that way. The failure is reported in the server log and as an error toast in the web UI.

Step 6: Execute and Verify

1. Create the board:

   • New project: kan init -c <columns> -n <board-name> -p <project-name>
   • Additional board: kan board create <board-name>, then edit the TOML to set up columns

2. Edit the board config at .kan/boards/<name>/config.toml to add:

   • Column descriptions (and column definitions if using kan board create)
   • Custom fields with types, options, descriptions, colors, and wanted flags
   • Card display configuration

3. Verify the result: kan board describe

Reference TOML format for custom fields and card display:

[custom_fields.type]
type = "enum"
wanted = true
description = "The category of work this card represents"

[[custom_fields.type.options]]
value = "bug"
color = "#dc2626"
description = "A defect in existing functionality"

[[custom_fields.type.options]]
value = "enhancement"
color = "#2563eb"
description = "An improvement to existing functionality"

[custom_fields.labels]
type = "enum-set"
description = "Flexible tags for categorization"

[[custom_fields.labels.options]]
value = "ai-hi"
description = "Well-suited for autonomous AI work"

[[custom_fields.labels.options]]
value = "ai-lo"
description = "Likely suitable for AI but less certain"

[card_display]
type_indicator = "type"
badges = ["labels"]

Column descriptions and limits are added to the [[columns]] entries:

[[columns]]
name = "backlog"
color = "#6b7280"
description = "Planned work not yet started"

[[columns]]
name = "in-progress"
color = "#f59e0b"
description = "Currently being worked on"
limit = 5

Git Worktree Support

When you run kan commands inside a git worktree, Kan automatically uses the board from the main worktree. This means all worktrees share the same kanban board by default - you don't need to initialize or manage separate boards per worktree.

If you run kan init inside a worktree, Kan warns that this will create a separate, independent board. If you confirm, the worktree gets its own .kan/ directory and worktree_independent = true is set in its project config.

Initialize

kan init                              # Create .kan/ in current directory
kan init -l .kanboard                 # Custom location
kan init -c todo,doing,done           # Custom columns
kan init -n myboard                   # Custom board name
kan init -p myproject                 # Custom project name for favicon/title
kan init -c a,b,c -n project          # Both custom columns and name

Flag	Description
-l, --location	Custom location for .kan directory
-c, --columns	Comma-separated column names (default: backlog,next,in-progress,done)
-n, --name	Board name (default: main)
-p, --project-name	Project name for favicon and page title (default: git repo or directory name)

Adding Cards

kan add "Fix login bug"                         # Add card, prompted for details
kan add "Fix login bug" -c backlog              # Add to specific column
kan add "Feature" -b features -c todo           # Specify board and column
kan add "Title" "Description here" -c backlog   # Title + description
kan add "Subtask" -p 12                         # Add as child of card 12
kan add "Task" -f priority=high -f type=bug     # Add with custom fields
kan add "Task" -f component=core -f component=cli  # Set fields: repeat or use -f component=core,cli
kan add "Urgent" -c backlog --top               # Insert at top of column
kan add "Follow-up" --after fix                  # Insert after card "fix" (in its column)
kan add "Buy milk" -g                            # Add to the global board from anywhere

Flag	Description
-b, --board	Target board
-c, --column	Target column
-p, --parent	Parent card ID or alias
--position	Insert at index (0 = top, -1 = end, negatives count from end)
--top	Insert at the top of the column
--bottom	Insert at the bottom of the column
--before	Insert before this card (ID or alias)
--after	Insert after this card (ID or alias)
-f, --field	Custom field (key=value, repeatable; set fields also accept comma-separated values)
--strict	Error if wanted fields are missing (default: warn)
-g, --global	Target the designated global board (see Global Board)

--position/--before/--after are mutually exclusive; default is end of column. Without -c, the card is placed in the anchor card's column. Prefer --before/--after for non-boundary spots (kan list shows no indices to count against).

Listing Cards

kan list                          # List all cards grouped by column
kan list -c done                  # Filter by column
kan list -b myboard               # Filter by board
kan list --sort priority          # Sort each column by a custom field
kan list --sort priority --descending  # Sort high to low

--sort <field> orders cards within each column by a custom field instead of by manual position. For enum/enum-set fields the order follows the option order in the board config (not alphabetical); cards with no value are listed last. Add --descending (-d) to sort high to low. It's a view sort - saved card positions are unchanged.

Showing Card Details

kan show 12              # Show card by ID
kan show fix             # Show card by alias or partial match
kan show fix -b myboard  # Specify board

Card identifiers accept partial substring matches against a card's alias or ID (case-insensitive, min 3 chars). A single match resolves; multiple matches produce a disambiguation error listing up to 5 candidates. Exact ID or alias always wins over fuzzy. This applies to show, history, edit, delete, and comment add.

kan show also displays how long the card has been in its current column (e.g. Column: review (3 days)), tracked natively by Kan rather than inferred from VCS commits.

Card History

kan history 12              # Show the card's column transition timeline
kan history fix -b myboard  # Specify board
kan history fix --json      # Machine-readable history entries

Kan records each column transition (with its event time) on the card, so you can see the full journey and how long the card spent in each column - independent of how often you commit. Title/description edit history is left to your VCS (git log), which already tracks content changes well.

Editing Cards

kan edit 12                              # Edit interactively
kan edit fix -t "New title"              # Update title
kan edit fix -c done -t "Shipped"        # Move and edit in one command
kan edit fix -c done --top               # Move to top of a column
kan edit fix --before deploy             # Reorder relative to another card
kan edit fix -d "New description"        # Update description
kan edit fix -f priority=low             # Update custom field

Flag	Description
-b, --board	Board name
-t, --title	Set card title
-d, --description	Set card description
-c, --column	Move card to column
-p, --parent	Set parent card
--position	Move to index in column (0 = top, -1 = end, negatives count from end)
--top	Move to the top of the column
--bottom	Move to the bottom of the column
--before	Move before this card (ID or alias)
--after	Move after this card (ID or alias)
-a, --alias	Set explicit alias
-f, --field	Set custom field (key=value, repeatable; set fields also accept comma-separated values)
--strict	Error if wanted fields are missing (default: warn)

The five placement flags are mutually exclusive. They reorder within the current column or place precisely when moving columns. Without -c, the card is placed in the anchor card's column. Prefer --before/--after for non-boundary spots.

Use kan move to just move a card. Reach for edit -c when the same command also changes other fields.

Moving Cards

kan move fix done                # Move to the done column
kan move fix next --bottom       # Back of the queue
kan move fix in-progress --top   # Front of the column
kan move fix --after deploy      # Column inferred from the anchor card

Flag	Description
-b, --board	Board name
--position	Move to index in column (0 = top, -1 = end, negatives count from end)
--top	Move to the top of the column
--bottom	Move to the bottom of the column
--before	Move before this card (ID or alias)
--after	Move after this card (ID or alias)
-g, --global	Target the designated global board

The column argument is optional when --before/--after is given - the card follows the anchor into its column.

With no placement flag, the destination column's on_move_default_position decides where the card lands: top unless the column is configured bottom. Moving a card to the column it already occupies does nothing; pass a placement flag to reorder it.

Deleting Cards

kan delete 12                  # Delete card by ID (prompts for confirmation)
kan delete fix-login           # Delete card by alias
kan delete 12 -b myboard       # Specify board
printf 'y\n' | kan delete 12   # Scripted: pipe the confirmation in

Flag	Description
-b, --board	Board name
-g, --global	Target the designated global board

kan delete always prompts - there is no --force or --yes flag to skip it, and -I makes it fail rather than proceed. Pipe the confirmation in to delete non-interactively.

Board Management

kan board create features    # Create a new board
kan board list               # List all boards
kan board delete features    # Delete board and all its cards (prompts for confirmation)
kan board describe           # Show board documentation (columns, fields, settings)
kan board describe --json    # Machine-readable board docs

kan board delete prompts and has no skip flag, same as kan delete - pipe the confirmation in (printf 'y\n' | kan board delete features) to script it.

Column Management

kan column add review                                    # Add column to end
kan column add review --color "#9333ea"                  # With custom color
kan column add review --position 2                       # Insert at position
kan column add review --description "Cards under review" # With description
kan column add review --limit 5                          # With column limit
kan column add review --on-move-default-position bottom  # Moved-in cards go to the back
kan column delete review                 # Delete column
kan column rename review code-review     # Rename column
kan column edit review --color "#ec4899" # Change column color
kan column edit review --description "Updated purpose"   # Change description
kan column edit review --limit 3         # Set column limit
kan column edit review --limit 0         # Clear column limit
kan column edit review --on-move-default-position bottom  # Moved-in cards to the back
kan column edit review --on-move-default-position top     # ...to the front (default)
kan column list                          # List columns
kan column move review --position 1      # Reorder column
kan column move review --after backlog   # Insert after another

Comments

kan comment add fix-login "Found the issue"   # Add comment to card
kan comment add fix-login                     # Add comment (opens editor)
kan comment edit c_9kL2x "Updated text"       # Edit comment by ID
kan comment delete c_9kL2x                    # Delete comment

Flag	Description
-b, --board	Board name

Committing Kan Files

kan commit                     # Stage and commit all .kan/ changes
kan commit -m "update board"   # Custom commit message

Flag	Description
-m, --message	Commit message (default: "chore: update kan files")

Only kan data files are committed, leaving any other staged changes untouched. Requires being inside a git repository.

Global Board

Designate one board as the global board so you can act on it from any working directory with -g/--global - useful for an "inbox" board captured to from anywhere.

kan global set            # designate the current project's board (interactive / single-board)
kan global set inbox      # designate a specific board by name
kan global show           # show the current designation (warns if stale)
kan global unset          # clear the designation

kan add -g "Buy milk"     # from anywhere, lands on the global board
kan list -g               # the global board's cards
kan edit -g buy-milk -c done

-g works on add, list, show, history, edit, delete, and comment add/edit/delete. It targets the global board's project with the designated board as default; an explicit -b overrides it (kan add -g -b other "..."). There is no implicit fallback - -g must be explicit, and bare commands outside a project still error rather than capturing to the global board.

Web Interface

kan serve                # Start web UI (opens browser)
kan serve -p 8080        # Custom port
kan serve --no-open      # Don't auto-open browser

Migration

kan migrate              # Migrate data to current schema
kan migrate --dry-run    # Preview changes without applying
kan migrate --all        # Migrate all projects in global config
kan migrate --all --dry-run  # Preview changes for all projects

Flag	Description
--dry-run	Show what would be changed without modifying files
--all	Migrate all projects registered in global config

Health Checks

kan doctor               # Check for consistency issues
kan doctor --fix         # Apply automatic fixes
kan doctor --dry-run     # Preview fixes without applying
kan doctor -b main       # Check specific board only
kan doctor --json        # Machine-readable output

Exit codes: 0 = no errors (warnings OK), 1 = errors found

Fixable issues: orphaned cards, missing card references, duplicate IDs, invalid default column, invalid parent refs.

Shell Completion

kan completion bash   # Output bash completion script
kan completion zsh    # Output zsh completion script

# Enable (add to shell profile):
eval "$(kan completion zsh)"
eval "$(kan completion bash)"

Completion supports commands, flags, board names, card IDs/aliases, and column names.

Global Flags

Flag	Description
-I, --non-interactive	Fail instead of prompting for input
--json	Output results as JSON (supported by: show, list, add, edit, history, board list, board describe, column list, comment add, doctor, docs)

Board Configuration

Board configuration is stored in .kan/boards/<boardname>/config.toml. Key features:

Pattern Hooks

Run commands when cards are created with matching titles:

[[pattern_hooks]]
name = "jira-sync"
pattern_title = "^[A-Z]+-\\d+$"  # Matches JIRA-123, PROJ-456
command = ".kan/hooks/jira-sync.sh"
timeout = 60  # Optional, defaults to 30s

Hooks receive <card_id> <board_name> as arguments and run after card creation. The command must be a path to an executable (not a shell command with arguments). Use ~ for home directory.

Link Rules

Auto-link patterns in card descriptions:

[[link_rules]]
name = "jira"
pattern = "([A-Z]+-\\d+)"
url = "https://jira.example.com/browse/{1}"

JSON Output

Use --json for programmatic access to Kan data:

kan show fix-login --json | jq .card.title
kan list --json | jq '.cards | length'
kan add "New task" --json | jq .card.id
kan board list --json | jq .boards
kan column list --json | jq '.columns[].name'
kan comment add fix-login "Note" --json | jq .comment.id

Tips

• Cards are identified by flexible IDs: numeric ID, alias, or partial match
• Use -I for scripting to ensure commands fail rather than prompt
• Use --json for programmatic access to card data

Documentation

kan docs                # List topics, each with its sections
kan docs configuration  # Print one page
kan docs all            # Print every page

Consult these when setting up boards or editing config files to verify available options and TOML structure. They ship in the binary, so they match the installed version - read them instead of fetching the web copy at amterp.dev/kan/docs, which is the fallback if kan docs is unavailable.