Shortcut Kanban Integration
Manage tasks and stories on Shortcut.com project boards via API.
Prerequisites
- - Shortcut API token configured via one of:
- Environment variable:
SHORTCUT_API_TOKEN
- File:
~/.config/shortcut/api-token
- - Access to a Shortcut workspace with appropriate permissions
Setup
- 1. Get your API token from Shortcut.com (Settings → API Tokens)
- Store it either:
- As environment variable:
export SHORTCUT_API_TOKEN="your-token"
- In a file:
echo "your-token" > ~/.config/shortcut/api-token && chmod 600 ~/.config/shortcut/api-token
- 3. Initialize workflow states for your workspace:
scripts/shortcut-init-workflow.sh
This creates
~/.config/shortcut/workflow-states with your workspace's actual state IDs.
- 4. Optionally add to
~/.bashrc for persistence:
CODEBLOCK1
Available Operations
List Stories
CODEBLOCK2
Options:
- -
--active - Show only incomplete stories (default) - INLINECODE7 - Show only completed stories
- INLINECODE8 - Include archived stories
- INLINECODE9 - Output raw JSON
Show Story Details
CODEBLOCK3
Displays full story information including:
- - Story name and status
- Description (if present)
- Checklist items with completion status
Create Story
CODEBLOCK4
Story types:
- -
feature (default) - New functionality - INLINECODE11 - Bug fix
- INLINECODE12 - Maintenance task
Update Story
CODEBLOCK5
Workflow states: The script uses state IDs from ~/.config/shortcut/workflow-states (created by shortcut-init-workflow.sh). If not configured, it falls back to common defaults:
- - Backlog: INLINECODE15
- To Do: INLINECODE16
- In Progress: INLINECODE17
- In Review: INLINECODE18
- Done: INLINECODE19
Note: Different Shortcut workspaces may use different state IDs. Always run shortcut-init-workflow.sh to configure your workspace's actual IDs.
Manage Checklist Tasks
Create a task:
CODEBLOCK6
Update task completion status:
CODEBLOCK7
Edit task description:
CODEBLOCK8
Delete a task:
CODEBLOCK9
Use shortcut-show-story.sh to see task IDs.
Manage Comments
Add a comment:
CODEBLOCK10
Update a comment:
CODEBLOCK11
Delete a comment:
CODEBLOCK12
Use shortcut-show-story.sh to see comment IDs.
Workflow
- 1. List existing stories to understand current board state
- Create new stories with descriptive names and appropriate types
- Update story status as work progresses
Notes
- - Scripts use
SHORTCUT_API_TOKEN environment variable or fall back to INLINECODE24 - Stories are created in "Unstarted" state by default (workflowstateid: 500000006)
- If your workspace uses different workflow state IDs, you may need to adjust the scripts
- The token must have permissions for the workspace you want to manage
Shortcut看板集成
通过API管理Shortcut.com项目看板上的任务和故事。
前置条件
- - 通过以下任一方式配置Shortcut API令牌：
- 环境变量：SHORTCUT
APITOKEN
- 文件：~/.config/shortcut/api-token
- - 拥有具备相应权限的Shortcut工作区访问权限
设置
- 1. 从Shortcut.com获取API令牌（设置 → API令牌）
- 通过以下任一方式存储：
- 作为环境变量：export SHORTCUT
APITOKEN=your-token
- 写入文件：echo your-token > ~/.config/shortcut/api-token && chmod 600 ~/.config/shortcut/api-token
- 3. 为工作区初始化工作流状态：
bash
scripts/shortcut-init-workflow.sh
该命令会在~/.config/shortcut/workflow-states中创建工作区的实际状态ID。
- 4. 可选：将以下内容添加到~/.bashrc以实现持久化：
bash
export SHORTCUT
APITOKEN=$(cat ~/.config/shortcut/api-token 2>/dev/null | tr -d \n)
source ~/.config/shortcut/workflow-states
可用操作
列出故事
bash
scripts/shortcut-list-stories.sh [--active|--completed|--all] [--json]
选项：
- - --active - 仅显示未完成的故事（默认）
- --completed - 仅显示已完成的故事
- --all - 包含已归档的故事
- --json - 输出原始JSON格式
查看故事详情
bash
scripts/shortcut-show-story.sh <故事ID>
显示完整的故事信息，包括：
- - 故事名称和状态
- 描述（如有）
- 检查清单项及其完成状态
创建故事
bash
scripts/shortcut-create-story.sh 故事名称 [--description 文本] [--type feature|bug|chore]
故事类型：
- - feature（默认）- 新功能
- bug - 缺陷修复
- chore - 维护任务
更新故事
bash
scripts/shortcut-update-story.sh <故事ID> [--complete|--todo|--in-progress] [--description 新文本]
工作流状态： 脚本使用~/.config/shortcut/workflow-states中的状态ID（由shortcut-init-workflow.sh创建）。如果未配置，则回退到通用默认值：
- - 待办事项：500000006
- 待处理：500000007
- 进行中：500000008
- 审核中：500000009
- 已完成：500000010
注意： 不同的Shortcut工作区可能使用不同的状态ID。请始终运行shortcut-init-workflow.sh来配置工作区的实际ID。
管理检查清单任务
创建任务：
bash
scripts/shortcut-create-task.sh <故事ID> 任务描述
更新任务完成状态：
bash
scripts/shortcut-update-task.sh <故事ID> <任务ID> [--complete|--incomplete]
编辑任务描述：
bash
scripts/shortcut-edit-task.sh <故事ID> <任务ID> 新描述
删除任务：
bash
scripts/shortcut-delete-task.sh <故事ID> <任务ID>
使用shortcut-show-story.sh查看任务ID。
管理评论
添加评论：
bash
scripts/shortcut-add-comment.sh <故事ID> 评论内容
更新评论：
bash
scripts/shortcut-update-comment.sh <故事ID> <评论ID> 新文本
删除评论：
bash
scripts/shortcut-delete-comment.sh <故事ID> <评论ID>
使用shortcut-show-story.sh查看评论ID。
工作流程
- 1. 列出现有故事以了解当前看板状态
- 使用描述性名称和适当类型创建新故事
- 随着工作进展更新故事状态
注意事项
- - 脚本使用SHORTCUTAPITOKEN环境变量，或回退到~/.config/shortcut/api-token
- 故事默认创建为未开始状态（workflowstateid: 500000006）
- 如果工作区使用不同的工作流状态ID，可能需要调整脚本
- 令牌必须具有要管理工作区的相应权限
