sk — SwiftKanban CLI & MCP Server

A command-line interface and MCP server for SwiftKanban. Manage boards, cards, and more from your terminal or through Claude AI.

Installation

npm install -g @nimblework/sk-cli

Or from source:

git clone <repo-url> sk-cli
cd sk-cli
npm install && npm run build
npm link

Configuration

Quick start: Login

The easiest way to get started is to log in with your SwiftKanban credentials:

sk login --user [email protected] --password yourpassword

This authenticates against the SwiftKanban API and stores the JWT token in your config file. Your account must have the Integration User role — contact your SwiftKanban admin if login fails with a permissions error.

You can also store credentials in config so sk login works without flags:

sk config set user [email protected]
sk config set password yourpassword
sk login

Manual token setup

If you already have a JWT token:

sk config set token eyJhbGciOiJIUz...

Server URL

The default server is https://login.swiftkanban.com. To use a different instance:

sk config set server https://your-instance.swiftkanban.com

Environment variables

export SK_SERVER=https://your-instance.swiftkanban.com
export SK_TOKEN=eyJhbGciOiJIUz...
export SK_BOARD_ID=BOARD-123   # optional default board
export [email protected]
export SK_PASSWORD=yourpassword

CLI flags

sk --server https://your-instance.swiftkanban.com --token eyJ... boards list

Configuration precedence

CLI flags > Environment variables > Config file (~/.config/sk-cli/config.json)

View current config

sk config show

Usage

Login

# Login with flags
sk login --user [email protected] --password yourpassword

# Login using stored/env credentials
sk login

Boards

# List all boards
sk boards list

# Get a specific board
sk boards get BOARD-123

Cards

Card IDs use the CardCode:numericId format (e.g., UserStory:679602). The workType and id fields from card list output combine to form this.

# List cards on a board
sk cards --board-id 1582582 list

# Get card details (CardCode:id format)
sk cards --board-id 1582582 get UserStory:679602

# Create a card
sk cards --board-id 1582582 create --name "Fix login bug" --description "Users can't log in on Safari"

# Create a card with full JSON payload
sk cards --board-id 1582582 create --json '{"name": "New feature", "description": "Add dark mode"}'

# Update a card
sk cards --board-id 1582582 update UserStory:679602 --name "Updated name"

# Update a card with JSON
sk cards --board-id 1582582 update UserStory:679602 --json '{"name": "New name", "description": "New desc"}'

# Delete a card
sk cards --board-id 1582582 delete UserStory:679602

Tip: Set a default board to avoid passing --board-id every time:

sk config set defaultBoardId 1582582

# Now these work without --board-id
sk cards list
sk cards create --name "Quick card"

Config

# Set a value
sk config set server https://my-instance.swiftkanban.com

# Get a value
sk config get server

# Show all config (tokens are redacted)
sk config show

Available config keys

| Key | Description | |---|---| | server | SwiftKanban server URL | | token | JWT auth token | | defaultBoardId | Default board ID | | format | Output format (json or table) | | user | Username (for JWT generation) | | password | Password (for JWT generation) |

Output Formats

JSON (default)

All commands output structured JSON to stdout:

{
  "ok": true,
  "data": [ ... ],
  "meta": { "total": 5 }
}

Errors go to stderr:

{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Card XYZ-123 was not found",
    "status": 404
  }
}

Table

Use --format table for human-readable output:

sk --format table boards list

┌──────────┬─────────────────┬────────┐
│ Board ID │ Name            │ State  │
├──────────┼─────────────────┼────────┤
│ 1570749  │ Engineering     │ Active │
│ 1571422  │ Marketing       │ Active │
└──────────┴─────────────────┴────────┘

Set table as default:

sk config set format table

Global Options

| Option | Description | |---|---| | --format <json\|table> | Output format (default: json) | | --server <url> | Override server URL | | --token <token> | Override auth token | | --verbose | Print debug info to stderr | | -V, --version | Show version | | -h, --help | Show help |

Exit Codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | Client error (bad input, not found, auth failure) | | 2 | Server error (5xx, timeout) | | 3 | Configuration error (missing token, bad config) |

MCP Server (Claude AI Integration)

sk-cli includes an MCP server that lets Claude interact with SwiftKanban directly.

Setup

1. Install the package:

npm install -g @nimblework/sk-cli

2. Get your auth token by logging in:

sk login --user [email protected] --password yourpassword

The token is saved to ~/.config/sk-cli/config.json. Copy it for the next step.

3. Find the full path to sk-mcp:

Claude Desktop does not inherit your shell PATH, so you must use the absolute path to sk-mcp.

which sk-mcp
# e.g., /Users/you/.npm-global/bin/sk-mcp

4. Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "swiftkanban": {
      "command": "/full/path/to/sk-mcp",
      "env": {
        "SK_TOKEN": "your-jwt-token",
        "SK_SERVER": "https://login.swiftkanban.com"
      }
    }
  }
}

Replace /full/path/to/sk-mcp with the output from step 3, and your-jwt-token with the token from step 2.

5. Restart Claude Desktop to pick up the new config.

Available MCP Tools

| Tool | Description | |---|---| | login | Authenticate with email/password, saves token | | get_config | Show current configuration | | list_boards | List all accessible boards | | get_board | Get board details | | list_cards | List cards on a board | | get_card | Get card details (use CardCode:id format) | | create_card | Create a new card | | update_card | Update an existing card | | delete_card | Delete a card |

All tools that require board_id will fall back to the SK_BOARD_ID env var if not provided.

Development

# Run in dev mode (no build needed)
npx tsx bin/sk.ts <command>

# Type check
npm run typecheck

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build
npm run build

# Lint
npm run lint

Project Structure

sk-cli/
├── bin/
│   ├── sk.ts              # CLI entry point
│   └── sk-mcp.ts          # MCP server entry point
├── src/
│   ├── cli/               # Command definitions (Commander.js)
│   ├── services/          # Business logic (shared by CLI + MCP)
│   ├── api/               # REST client, types, auth
│   ├── config/            # Config loading (CLI > env > file)
│   └── output/            # JSON/table formatting
├── test/
│   ├── unit/              # Unit tests (vitest + msw)
│   ├── integration/       # Integration tests (needs SK_TOKEN)
│   └── fixtures/          # Sample API responses
└── .claude/               # Claude Code config (skills, agents, rules)

Adding new commands

Use the Claude Code skills:

/add-endpoint cards move      # Scaffold a full endpoint
/add-command  cards archive   # Add a CLI command
/discover-api lanes           # Probe API for new endpoints

License

MIT