pkanban

pkanban

A CLI-first Kanban board for humans and AI agents. (The "p" is silent, like in "pneumonia".)

Most users will connect to our hosted service at pkanban.pearachute.com. If you want to run your own server, see the Self-Hosting section below.

Quick Start

macOS, Linux, WSL:

curl -fsSL https://pkanban.pearachute.com/install.sh | sh

Windows PowerShell:

irm https://pkanban.pearachute.com/install.ps1 | iex

Windows CMD:

curl -fsSL https://pkanban.pearachute.com/install.cmd -o install.cmd && install.cmd && del install.cmd

The installer uses uv or pipx if you have one, and installs uv (which brings its own Python) if you don't. Already have Python? pip install pkanban works too.

The CLI connects to the hosted service at https://pkanban.pearachute.com by default, so you can log in right away:

pkanban login

Your browser opens on an approval page; click Approve and the terminal is signed in. Nothing secret is typed into the terminal, so this is also how to sign in an AI agent (pkanban login --no-wait, approve, then pkanban login again). Prefer a password? pkanban login <username> prompts for one.

Self-hosting? Point the CLI at your own server first with pkanban config --url http://localhost:8000 — see Self-Hosting.

Common Commands

# List your boards
pkanban board list

# Create a new board
pkanban board create "My Project"

# View a board with its columns and cards
pkanban board get 1

# Add a column
pkanban column create 1 "To Do" 0

# Add a card
pkanban card create 1 "First task" --description "Getting started"

# Share a board with a team
pkanban share 1 <team-id>

API Keys

For automation, CI/CD, or giving access to agents, use API keys instead of passwords:

# Create a key (shown only once!)
pkanban apikey create "CI Agent"

# Save it once; subsequent commands use it automatically
pkanban apikey save pkanban_abc123...
pkanban board list

# Or pass it per command
pkanban --api-key pkanban_abc123... board list

API keys can be revoked and reactivated at any time. They're stored securely (bcrypt-hashed) and track their last usage.

Scripting: JSON output

--json makes any command print the raw API response instead of formatted text, so scripts never have to scrape prose for values like IDs:

pkanban board create "Roadmap" --json
pkanban board get 1 --json | jq '.columns[] | {id, name}'

PKANBAN_OUTPUT=json does the same for a whole run:

export PKANBAN_OUTPUT=json

The flag works in either position (pkanban --json board list and pkanban board list --json are equivalent). In JSON mode stdout carries only the response, and errors go to stderr as {"error": ..., "status": ...} with a non-zero exit code — so stdout is always safe to pipe into a parser.

pkanban login --json deliberately omits the access token: it is already saved to ~/.pkanban.yaml, and stdout is what CI logs capture.

Command Reference

Command	Description
pkanban config [--url URL]	Show or set server URL
pkanban login	Sign in by approving in your browser
pkanban login <user>	Sign in with a password (prompted)
pkanban logout	Logout and clear credentials
pkanban --api-key <key>	Use API key for authentication
pkanban --json <command>	Print the raw API response as JSON
pkanban apikey create <name>	Generate a new API key
pkanban apikey list	List your API keys
pkanban apikey revoke <id>	Revoke an API key
pkanban apikey activate <id>	Reactivate a revoked key
pkanban board list	List all boards
pkanban board create <name>	Create a new board
pkanban board get <id>	Show board details
pkanban board delete <id>	Delete a board
pkanban board update <id> <name>	Update board name
pkanban share <board_id> <team_id|private>	Share board or make private
pkanban column create <board_id> <name> [position]	Create a column (appends by default)
pkanban column delete <id>	Delete a column
pkanban card get <id>	Show a card's description and comments
pkanban card create <column_id> <title> [options]	Create a card
pkanban card update <id> [title] [options]	Update a card; omitted fields are unchanged
pkanban card move <id> --column <n> [-p <pos>]	Move a card without touching its text
pkanban card delete <id>	Delete a card
pkanban card comment <id> [text] [--file <path>]	Comment on a card (- reads stdin)
pkanban org list	List all organizations
pkanban org create <name>	Create an organization
pkanban org get <org-id>	Show organization details
pkanban org members <org-id>	List organization members
pkanban org member-add <org-id> <username>	Add member to organization
pkanban org member-remove <org-id> <user-id>	Remove member
pkanban team list --org-id <org-id>	List teams in organization
pkanban team create <org-id> <name>	Create a new team
pkanban team get <team-id>	Show team details
pkanban team members <team-id>	List team members
pkanban team member-add <team-id> <username>	Add member to team
pkanban team member-remove <team-id> <user-id>	Remove member from team

Self-Hosting

Want to run your own server? Here's how:

1. Clone and setup

git clone https://github.com/japherwocky/pkanban.git
cd pkanban
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r backend/requirements.txt
cd frontend && npm install && cd ..

2. Initialize and run

python manage.py init
python manage.py user-create admin mypassword --admin
python manage.py server

The server runs at http://localhost:8000 by default.

3. Connect the CLI

The CLI defaults to the hosted service, so point it at your local server first, then log in (you'll be prompted for the password):

pkanban config --url http://localhost:8000
pkanban login admin

Development

# Run the server with auto-reload
python manage.py server

# Run frontend dev server (hot reload)
cd frontend && npm run dev

# Run tests
python -m pytest backend/tests/

Database commands

python manage.py init          # Create tables
python manage.py wipe          # Drop and recreate tables
python manage.py status        # Check database status
python manage.py user-create <user> <pass> [--admin]

API Reference

The backend exposes a REST API at /api/:

Authentication

• POST /api/token - Login (returns JWT)
• X-API-Key header - Alternative auth via API key

API Keys

• GET /api/api-keys - List your keys
• POST /api/api-keys - Create a key
• DELETE /api/api-keys/{id} - Revoke a key
• POST /api/api-keys/{id}/activate - Reactivate a key

Boards

• GET /api/boards - List accessible boards
• POST /api/boards - Create a board
• GET /api/boards/{id} - Get board details (archived cards hidden; ?include_archived=true adds them)
• POST /api/boards/{id} - Update board
• DELETE /api/boards/{id} - Delete board

Columns

• POST /api/columns - Create column
• PUT /api/columns/{id} - Update column
• DELETE /api/columns/{id} - Delete column

Cards

• GET /api/cards/{id} - Get one card with its description and comments
• POST /api/cards - Create card
• PUT /api/cards/{id} - Update card
• DELETE /api/cards/{id} - Delete card
• POST /api/cards/{id}/archive - Archive a card: hidden from board views, still found by search
• POST /api/cards/{id}/unarchive - Bring it back, at the bottom of its column

Comments

• GET /api/cards/{id}/comments - List a card's comments
• POST /api/comments - Comment on a card (card_id, content)
• PUT /api/comments/{id} - Edit a comment (author only)
• DELETE /api/comments/{id} - Delete a comment (author only)
• GET /api/search?q=... - Search card titles and descriptions on every board you can open (board_id, limit optional)

For multi-tenant organization details, see docs/multi-tenant.md.