pkanban

pkanban

一款以 CLI 为先、供人类和 AI Agent 使用的看板。（“p”不发音，就像“pneumonia”中的“p”。）

大多数用户会连接到我们的托管服务 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 Agent 的登录方式（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 或向 Agent 授予访问权限，请使用 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>	以 JSON 格式打印原始 API 响应
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 header - 通过 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} - 获取一张卡片及其描述和评论
• 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。