Frequently Asked Questions

No. Node.js 18 or later plus npm is all you need. Install the CLI with npm install -g kanban-lite, then run kl init in any directory to create your first board. No database setup, no config file required.

Yes. Use npx kanban-lite init and npx kanban-lite serve for one-off runs. Everything works the same way — you just prefix with npx kanban-lite instead of kl.

In a .kanban/ directory created by kl init in your current working directory. Each card is a plain .md file with YAML frontmatter, organized into sub-directories by status (e.g. .kanban/in-progress/). Everything is human-readable text.

Yes — that is the main advantage. Every status change, card edit, and comment is a git commit. You get diffs, blame, pull request reviews, rollbacks, and branch-per-feature boards all for free. Add .kanban/ to your repo like any other directory.

Yes. Kanban Lite is a Node.js package and runs on any platform Node.js supports. The CLI, web server, and VS Code extension all work cross-platform.

From the CLI: kl move <card-id> in-progress. From the web UI: drag the card or use the status dropdown in the card detail panel. From the API: PATCH /api/tasks/:id with {"status": "in-progress"}.

Yes. Use --meta key=value in the CLI when creating or editing a card. Metadata is stored in the card frontmatter and is searchable with meta.field: value tokens from the toolbar or CLI. Example: kl add --title "New feature" --meta sprint=Q2 --meta points=5.

Labels are predefined, board-level tags for broad categories ("bug", "ux", "backend"). They display as colored chips on board cards. Metadata is arbitrary key-value data per card for structured fields like sprint, story points, Jira ticket IDs, or any other information you want to filter on. Use labels for visual categorization and metadata for queryable structured data.

Card IDs are auto-generated from the title and a timestamp — for example implement-dark-mode-2026-01-29. This keeps IDs stable, URL-safe, and human-readable. You cannot currently set a custom ID at creation time, but you can reference the auto-generated ID in all CLI, API, and MCP operations.

The default kl delete soft-deletes a card (moves to a deleted status column). It remains on disk and is recoverable from git history. Use kl permanent-delete <card-id> to remove it from disk entirely. If your board is in a git repo, git checkout HEAD -- .kanban/ can restore any card.

Yes, two ways: (1) commit .kanban/ to a shared git repo — each team member pulls changes and the board is in sync with code. (2) Run kl serve on a shared machine and let everyone connect to the web UI over the local network. The server streams updates to all clients via WebSocket.

The default markdown storage does not have row-level locking, so concurrent file writes can collide. For teams with many parallel editors, switch to the SQLite storage plugin (kl storage migrate-to-sqlite), which handles concurrent writes safely. The git-based workflow (commit and pull) also avoids collisions naturally.

Not by default — the server binds to localhost. For team deployments, use the auth plugin (see auth docs) to add identity and access control, or put a reverse proxy (nginx, Caddy, Cloudflare Tunnel) in front of the server to handle authentication at the network layer.

Yes. Run kl serve --port 8080 --no-browser in a Docker container or on a VPS and expose it over your internal network or VPN. Mount a volume at the .kanban/ directory path and set KANBAN_DIR to point to it. The REST API is then available for CI automation and scripting.

No. Default storage is plain markdown files — no database setup, no migration scripts, no connection strings. If you later need concurrent write performance (parallel CI jobs, many simultaneous team editors), switch to the bundled SQLite plugin with kl storage migrate-to-sqlite. External MySQL is available via a separate package.

Switch to SQLite when multiple processes write to the board simultaneously: parallel CI jobs, multiple MCP agents, or teams with more than a few members editing cards at the same time. The migration is non-destructive and reversible — kl storage migrate-to-markdown converts back.

There is no built-in importer yet. You can script a bulk import by reading a JSON export from those tools and calling kl add for each item, or POST /api/tasks for a programmatic approach. Community import scripts are welcome contributions.

If the board is in a git repo, git push is your backup. Otherwise: cp -r .kanban/ backup/ — it is just files. For SQLite users, back up the .kanban/kanban.db file like any other SQLite database.

Pass --dir <path> to any CLI command or set the KANBAN_DIR environment variable to point to the new location. All commands pick up the custom path at runtime.

The API is documented via OpenAPI/Swagger (browse interactively at /api/docs). Follow the CHANGELOG for breaking changes. The API follows the main package version and is stable within a major version.

The MCP (Model Context Protocol) server exposes all board operations as structured tools that AI agents like Claude, Codex, or OpenCode can call directly. You only need it if you want AI agents to interact with your board. Run kl mcp to start it on stdio transport. For human-only teams you can ignore it entirely.

Yes. The server runs locally — no internet connection required. The web UI loads all its assets locally from localhost:3000. There are no CDN dependencies at runtime.

Yes. The REST API is public and CORS-enabled (* origin by default). Query GET /api/tasks from any frontend to read card data, or use the SDK in a Node.js backend for server-side integration. SDK docs →

The extension is bundled in the same kanban-lite npm package. It renders the board as a webview panel inside VS Code using the same server and file storage as the standalone mode. Install the npm package and the extension activates automatically.

Yes. The board server runs inside the remote environment and the webview panel opens in your local VS Code window, just like any other VS Code extension webview. The .kanban/ directory is accessed from the remote filesystem.

Use kl columns add --id <id> --name <name>, kl columns update <id> --name <new-name>, or manage columns from the Board Settings panel in the web UI. Each board has its own independent column configuration.

Yes. The plugin system has a card.storage extension point. Implement the storage interface, publish it as an npm package, and select it in .kanban.json. See the storage plugin docs and the kanban-storage-plugin-author skill for a guided authoring workflow.

Kanban Lite sends a signed HMAC-SHA256 POST to your registered URL on each matching event. Register with kl webhooks add --url https://example.com/hook --events task.created,task.moved --secret mysecret. The delivery includes the full card payload and the event type. See webhooks docs →

Mount a volume at your .kanban/ path, set KANBAN_DIR to that path, expose port 3000, and run kanban-md --no-browser as the container entrypoint. A docker-compose.yml is included in the repository as a reference.

No. Kanban Lite is fully open source under the MIT license. There are no paid tiers, usage caps, or seat limits. You can use it privately, commercially, and internally without restrictions.

MIT. Free for personal, commercial, and internal use. See the LICENSE file on GitHub.