CLI Reference
The kl (or kanban-lite) CLI gives you full control of every board resource from the terminal. All mutations fire the same webhooks as the UI and REST API, making the CLI a first-class citizen in your automation pipelines.
- Create, update, move, and delete cards with
kl add/kl edit/kl move - Fuzzy and metadata-scoped search:
kl list --search "meta.team: backend" --fuzzy - Manage columns, webhooks, settings, and storage migrations
--jsonflag for machine-readable output in scripts- Start the web server or MCP server with
kl serve/kl mcp
Common commands
# Install
npm install -g kanban-lite
# Create and work with cards
kl add --title "Implement search" --priority high --label frontend
kl list --status todo
kl move implement-search in-progress
kl edit implement-search --assignee alice
# Start the board UI
kl serveCLI
Manage your kanban board from the terminal using kanban-lite or the shorthand kl:
# List all cards
kl list
# List with filters
kl list --status todo --priority high
# Exact and fuzzy search
kl list --search "release meta.team: backend"
kl list --search "meta.team: backnd api plumbng" --fuzzy
# Combine fuzzy search with structured metadata filters
kl list --search "release" --fuzzy --meta sprint=Q1 --meta links.jira=PROJ-123
# Create a card
kl add --title "Implement search" --priority high --label "frontend,search"
# Create a card with actions
kl add --title "Deploy service" --actions "retry,rollback,notify"
# Create a card with attached forms
kl add --title "Investigate outage" --forms '[{"name":"incident-report"}]'
# Update form attachments or persisted per-form data
kl edit investigate-outage --forms @forms.json --form-data @form-data.json
# Show card details
kl show implement-search
# Show the currently active/open card
kl active
# Move to a different column
kl move implement-search in-progress
# Update fields
kl edit implement-search --assignee alice --due 2026-03-01
# Add actions to an existing card
kl edit deploy-service --actions "retry,rollback,notify"
# Trigger an action
kl action trigger deploy-service retry
# Submit a card form payload
kl form submit investigate-outage incident-report --data '{"severity":"high","owner":"alice"}'
# Delete a card
kl delete implement-search
# Attachments
kl attach implement-search # List attachments
kl attach add implement-search ./screenshot.png # Attach a file
kl attach remove implement-search screenshot.png # Remove attachment
# Comments
kl comment implement-search # List comments
kl comment add implement-search --author alice \
--body "Looks good, needs tests" # Add a comment
kl comment edit implement-search c1 --body "Updated" # Edit a comment
kl comment remove implement-search c1 # Remove a comment
# Logs
kl log list implement-search # List log entries
kl log add implement-search --text "Build passed" # Add a log entry
kl log add implement-search --text "Deployed" \
--source ci --object '{"version":"1.0"}' # With source and data
kl log clear implement-search # Clear all logs
# Board Logs
kl board-log list # List board-level log entries
kl board-log add --text "Deployment complete" # Add a board log entry
kl board-log add --text "Pipeline passed" \
--source ci --object '{"build":"42"}' # With source and data
kl board-log clear # Clear all board logs
# Board Actions
kl board-actions list --board default # List board-level actions
kl board-actions add --board default \
--key deploy --title "Deploy to Production" # Add/update a board action
kl board-actions fire --board default deploy # Trigger a board action
# Boards
kl boards # List boards
kl boards add --id bugs --name "Bug Tracker" # Create a board
kl boards show bugs # Show board details
kl boards remove bugs # Remove an empty board
kl boards default bugs # Set default board
kl transfer card-42 --from default --to bugs # Transfer card between boards
# Target a specific board (works with most commands)
kl list --board bugs # List cards in a board
kl add --title "Login bug" --board bugs # Create card in a board
# Manage columns
kl columns # List columns
kl columns add --id testing --name Testing # Add column
kl columns update testing --color "#ff9900" # Update column
kl columns remove testing # Remove column
# Webhooks
kl webhooks # List webhooks
kl webhooks add --url https://example.com/hook # Register webhook
kl webhooks add --url https://example.com/hook \
--events task.created,task.moved --secret mykey # With event filter and secret
kl webhooks update wh_abc123 --active false # Disable a webhook
kl webhooks update wh_abc123 --events task.created # Change subscribed events
kl webhooks remove wh_abc123 # Remove webhook
# Settings
kl settings # Show current settings
kl settings update --compactMode true # Update a setting
# Workspace
kl pwd # Print workspace root path
# Storage providers
kl storage status # Show current provider + capability status
kl storage migrate-to-sqlite --sqlite-path .kanban/kanban.db # Migrate to SQLite
kl storage migrate-to-markdown # Migrate back to markdown
# Card state / unread
kl card-state status # Show active card.state backend + default actor contract / availability
kl card-state status <card-id> # Show side-effect-free actor-scoped unread/open summary (not active-card UI state)
kl card-state read <card-id> # Explicitly acknowledge unread activity for the current actor
kl card-state open <card-id> # Acknowledge unread and persist explicit actor-scoped open-card state
# Start web server
kl serve # Start on port 3000
kl serve --port 8080 --no-browser # Custom port, no auto-open
# Start MCP server (stdio transport for AI agent integrations)
kl mcp # Auto-detect directory
kl mcp --dir .kanban # Explicit directory
# Initialize features directory
kl init
# Other
kl version # Print version
kl help # Show help
kl help sdk # Show SDK documentation
kl help api # Show REST API documentation
Use --json for machine-readable output. Use --dir <path> to specify a custom features directory. Use --board <id> to target a specific board.
--forms accepts a JSON array of attached form descriptors, and --form-data accepts a JSON object keyed by resolved form id. Both flags also support @path/to/file.json.