pkanban

pkanban

人間と AI エージェント向けの、CLI ファーストなカンバンボードです。（「p」は「pneumonia」のように発音しません。）

ほとんどのユーザーは、ホスト型サービス pkanban.pearachute.com に接続します。独自のサーバーを実行する場合は、以下の「セルフホスティング」セクションをご覧ください。

クイックスタート

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

インストーラーは、uv または pipx がある場合はそれを使用し、ない場合は uv（独自の Python を同梱）をインストールします。すでに Python がインストールされている場合は、pip install pkanban でも動作します。

CLI はデフォルトでホスト型サービス https://pkanban.pearachute.com に接続するため、すぐにログインできます。

pkanban login

ブラウザーで承認ページが開くので、Approve をクリックすると、ターミナルでサインインが完了します。ターミナルに秘密情報を入力する必要がないため、AI エージェントへのサインインにも同じ方法を使えます（pkanban login --no-wait を実行して承認し、その後もう一度 pkanban login を実行します）。パスワードを使いたい場合は、pkanban login <username> を実行すると入力を求められます。

セルフホストする場合は、まず pkanban config --url http://localhost:8000 で CLI の接続先を独自サーバーに設定してください。詳しくはセルフホスティングをご覧ください。

よく使うコマンド

# 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 (read, write or admin)
pkanban share 1 <team-id> -p write

API キー

自動化、CI/CD、またはエージェントへのアクセス権付与には、パスワードの代わりに API キーを使用してください。

# 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 キーはいつでも取り消したり、再有効化したりできます。安全に保存され（bcrypt でハッシュ化）、最後に使用された日時が記録されます。

スクリプト：JSON 出力

--json を指定すると、どのコマンドでも整形済みテキストではなく、生の API レスポンスが出力されるため、スクリプトで ID などの値を取得するために説明文をスクレイピングする必要がありません。

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

PKANBAN_OUTPUT=json を設定すると、実行全体で同じ動作になります。

export PKANBAN_OUTPUT=json

このフラグはどちらの位置でも使用できます（pkanban --json board list と pkanban board list --json は同じです）。JSON モードでは stdout にレスポンスのみが出力され、エラーは {"error": ..., "status": ...} として stderr に出力され、ゼロ以外の終了コードが返されます。そのため、stdout は常にパーサーにパイプしても安全です。

pkanban login --json では、意図的にアクセストークンを出力しません。トークンはすでに ~/.pkanban.yaml に保存されており、stdout の内容は CI のログに記録されるためです。

コマンドリファレンス

コマンド	説明
pkanban config [--url URL]	サーバー URL の表示または設定
pkanban login	ブラウザーで承認してサインイン
pkanban login <user>	パスワードを入力してサインイン（入力を求められます）
pkanban logout	ログアウトして認証情報を消去
pkanban --api-key <key>	API キーを使って認証
pkanban --json <command>	API レスポンスを未加工の JSON として出力
pkanban apikey create <name>	新しい API キーを生成
pkanban apikey list	API キーを一覧表示
pkanban apikey revoke <id>	API キーを無効化
pkanban apikey activate <id>	無効化したキーを再有効化
pkanban board list	すべてのボードを一覧表示
pkanban board create <name>	新しいボードを作成
pkanban board get <id>	ボードの詳細を表示
pkanban board delete <id>	ボードを削除
pkanban board update <id> <name>	ボード名を更新
pkanban share <board_id> <team_id|private> [-p read|write|admin] [--remove]	指定した権限レベルでチームとボードを共有、または非公開に設定
pkanban column create <board_id> <name> [position]	列を作成（デフォルトでは末尾に追加）
pkanban column delete <id>	列を削除
pkanban card get <id>	カードの説明とコメントを表示
pkanban card create <column_id> <title> [options]	カードを作成
pkanban card update <id> [title] [options]	カードを更新。省略したフィールドは変更されません
pkanban card move <id> --column <n> [-p <pos>]	テキストを変更せずにカードを移動
pkanban card delete <id>	カードを削除
pkanban card comment <id> [text] [--file <path>]	カードにコメントを追加（- は標準入力を読み込みます）
pkanban org list	すべての組織を一覧表示
pkanban org create <name>	組織を作成
pkanban org get <org-id>	組織の詳細を表示
pkanban org members <org-id>	組織のメンバーを一覧表示
pkanban org member-add <org-id> <username>	組織にメンバーを追加
pkanban org member-remove <org-id> <user-id>	メンバーを削除
pkanban team list --org-id <org-id>	組織内のチームを一覧表示
pkanban team create <org-id> <name>	新しいチームを作成
pkanban team get <team-id>	チームの詳細を表示
pkanban team members <team-id>	チームのメンバーを一覧表示
pkanban team member-add <team-id> <username>	チームにメンバーを追加
pkanban team member-remove <team-id> <user-id>	チームからメンバーを削除

セルフホスティング

独自のサーバーを実行したい場合は、以下の手順に従ってください。

1. クローンしてセットアップ

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. 初期化して実行

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

デフォルトでは、サーバーは http://localhost:8000 で実行されます。

3. CLI を接続

CLI はデフォルトでホステッドサービスを使用するため、まずローカルサーバーを指定してから、 ログインしてください（パスワードの入力を求められます）。

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

開発

# 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/

データベースコマンド

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 リファレンス

バックエンドは /api/ で REST API を公開しています：

認証

• POST /api/token - ログイン（JWT を返します）
• X-API-Key ヘッダー - API キーによる代替認証

API キー

• GET /api/api-keys - 自分のキーを一覧表示
• POST /api/api-keys - キーを作成
• DELETE /api/api-keys/{id} - キーを無効化
• POST /api/api-keys/{id}/activate - キーを再有効化

ボード

• GET /api/boards - アクセス可能なボードを一覧表示
• POST /api/boards - ボードを作成
• GET /api/boards/{id} - ボードの詳細を取得（アーカイブ済みカードは非表示です。?include_archived=true を指定すると含まれます）
• POST /api/boards/{id} - ボードを更新
• DELETE /api/boards/{id} - ボードを削除

列

• POST /api/columns - 列を作成
• PUT /api/columns/{id} - 列を更新
• DELETE /api/columns/{id} - 列を削除

カード

• GET /api/cards/{id} - 説明とコメントを含むカードを1件取得
• POST /api/cards - カードを作成
• PUT /api/cards/{id} - カードを更新
• DELETE /api/cards/{id} - カードを削除
• POST /api/cards/{id}/archive - カードをアーカイブ：ボードの表示では非表示になりますが、検索では引き続き見つかります
• POST /api/cards/{id}/unarchive - カードを復元し、列の一番下に移動

コメント

• GET /api/cards/{id}/comments - カードのコメントを一覧表示
• POST /api/comments - カードにコメントを投稿（card_id、content）
• PUT /api/comments/{id} - コメントを編集（投稿者のみ）
• DELETE /api/comments/{id} - コメントを削除（投稿者のみ）
• GET /api/search?q=... - アクセス可能なすべてのボードでカードのタイトルと説明を検索（board_id、limit は任意）

マルチテナントの組織に関する詳細は、docs/multi-tenant.md をご覧ください。