import { KanbanSDK } from 'kanban-lite';

const sdk = new KanbanSDK({ dir: '.kanban' });

// Create a card
const card = await sdk.createCard({ title: 'Fix login bug', priority: 'high', status: 'todo' });

// Move it
await sdk.moveCard(card.id, 'in-progress');

// Subscribe to events
sdk.on('task.created', (card) => console.log('New card:', card.id));

Kanban Lite SDK

The KanbanSDK class is the core engine behind Kanban Lite. It provides a complete, async API for managing cards, comments, attachments, columns, and board settings. The CLI, MCP server, VSCode extension, and standalone web server all delegate to this single SDK — so behavior is consistent everywhere.

Installation

npm install kanban-lite

Import

import { KanbanSDK } from 'kanban-lite/sdk'

You can also import types and utilities:

import type { Card, CardStatus, Priority, KanbanColumn, CardDisplaySettings, CreateCardInput } from 'kanban-lite/sdk'
import { parseCardFile, serializeCard, getTitleFromContent, getDisplayTitleFromContent, DEFAULT_COLUMNS } from 'kanban-lite/sdk'
import { readConfig, writeConfig, configToSettings, settingsToConfig } from 'kanban-lite/sdk'

Callback runtime helpers are also exported from the SDK barrel:

import type { CallbackCapabilityNamespace, ResolvedCallbackCapabilities } from 'kanban-lite/sdk'
import { normalizeCallbackCapabilities } from 'kanban-lite/sdk'

Quick Start

import { KanbanSDK } from 'kanban-lite/sdk'

const sdk = new KanbanSDK('/path/to/project/.kanban')

// Create a card
const card = await sdk.createCard({
  content: '# Implement auth\n\nAdd OAuth2 login flow.',
  status: 'todo',
  priority: 'high',
  labels: ['backend', 'security']
})

// List all cards (sorted by order)
const cards = await sdk.listCards()

// Move card to a different column
await sdk.moveCard(card.id, 'in-progress')

// Add a comment
await sdk.addComment(card.id, 'alice', 'Started working on this')

// Clean up
await sdk.deleteCard(card.id)

Parser

parseCardFile(content, filePath) ⇒

Parses a markdown file with YAML frontmatter into a Card object.

The file is expected to have a YAML frontmatter block delimited by --- at the top, followed by the card body content. Additional --- delimited blocks after the body are parsed as comment sections (if they contain comment: true), otherwise they are treated as part of the body content.

Kind: global function
Returns: The parsed Card object, or null if no valid frontmatter block is found.

serializeCard(card) ⇒

Serializes a Card object back to markdown with YAML frontmatter.

Produces a string with a --- delimited YAML frontmatter block containing all card metadata, followed by the card body content. Any comments attached to the card are appended as additional --- delimited sections at the end of the file.

Kind: global function
Returns: The complete markdown string ready to be written to a .md file.

File Utilities

findWorkspaceRootSync(startDir) ⇒

Synchronously walks up from startDir looking for a workspace root.

Preference order:

1. A directory containing .git (authoritative project root)
2. The nearest directory containing .kanban.json
3. The nearest directory containing package.json

This ensures monorepo package folders do not shadow the actual repository root when a .git directory exists higher up the tree.

Kind: global function
Returns: The detected workspace root, or startDir on no match.

resolveWorkspaceRoot(startDir, configFilePath) ⇒

Resolves the workspace root from either an explicit config file path or the current directory tree.

Kind: global function
Returns: The absolute workspace root path.

resolveKanbanDir(startDir, configFilePath) ⇒

Resolves the kanban directory without an explicit path by locating the workspace root, then reading kanbanDirectory from the effective .kanban.json file (defaults to '.kanban').

Kind: global function
Returns: The absolute path to the kanban directory.

getCardFilePath(kanbanDir, status, filename) ⇒

Constructs the full file path for a card markdown file.

Kind: global function
Returns: The absolute path to the card file, including the .md extension.

ensureDirectories(kanbanDir) ⇒

Creates the kanban directory if it does not already exist.

Kind: global function
Returns: A promise that resolves when the directory has been created or already exists.

ensureStatusSubfolders(kanbanDir, statuses) ⇒

Creates subdirectories for each status column under the kanban directory.

Kind: global function
Returns: A promise that resolves when all status subdirectories have been created.

moveCardFile(currentPath, kanbanDir, newStatus, attachments) ⇒

Moves a card file to a new status directory, handling name collisions by appending a numeric suffix (e.g., card-1.md, card-2.md). Optionally co-moves attachment files from the source directory to the target directory.

Kind: global function
Returns: A promise that resolves to the new absolute path of the moved card file.

renameCardFile(currentPath, newFilename) ⇒

Renames a card file in place within its current directory.

Kind: global function
Returns: A promise that resolves to the new absolute path of the renamed card file.

getStatusFromPath(filePath, kanbanDir) ⇒

Extracts the status from a card's file path by examining the directory structure.

Expects the file to be located at {kanbanDir}/{status}/{filename}.md. If the relative path does not match this two-level structure, returns null.

Kind: global function
Returns: The status string extracted from the path, or null if the path structure is unexpected.

Data Storage

Cards are stored as markdown files with YAML frontmatter:

.kanban/
  boards/
    default/
      backlog/
        1-implement-auth.md
        2-setup-ci.md
      todo/
      in-progress/
      review/
      done/
    bugs/
      new/
      investigating/
      fixed/
  .kanban.json          # Board config, forms, labels, settings, and webhook definitions

Each card file contains YAML frontmatter (id, status, priority, assignee, dates, labels, order) followed by markdown content and optional comment sections.

Error Handling

All SDK methods throw standard Error objects with descriptive messages: