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
- 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
- Initialize workflow states for your workspace:
scripts/shortcut-init-workflow.sh
This creates ~/.config/shortcut/workflow-states
with your workspace's actual state IDs.
- Optionally add to
~/.bashrc
for persistence:
export SHORTCUT_API_TOKEN=$(cat ~/.config/shortcut/api-token 2>/dev/null | tr -d '\n')
source ~/.config/shortcut/workflow-states
Available Operations
List Stories
scripts/shortcut-list-stories.sh [--active|--completed|--all] [--json]
Options:
--active
- Show only incomplete stories (default)--completed
- Show only completed stories--all
- Include archived stories--json
- Output raw JSON
Show Story Details
scripts/shortcut-show-story.sh <story-id>
Displays full story information including:
- Story name and status
- Description (if present)
- Checklist items with completion status
Create Story
scripts/shortcut-create-story.sh "Story name" [--description "text"] [--type feature|bug|chore]
Story types:
feature
(default) - New functionalitybug
- Bug fixchore
- Maintenance task
Update Story
scripts/shortcut-update-story.sh <story-id> [--complete|--todo|--in-progress] [--description "new text"]
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:
500000006
- To Do:
500000007
- In Progress:
500000008
- In Review:
500000009
- Done:
500000010
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:
scripts/shortcut-create-task.sh <story-id> "task description"
Update task completion status:
scripts/shortcut-update-task.sh <story-id> <task-id> [--complete|--incomplete]
Edit task description:
scripts/shortcut-edit-task.sh <story-id> <task-id> "new description"
Delete a task:
scripts/shortcut-delete-task.sh <story-id> <task-id>
Use
shortcut-show-story.sh
to see task IDs.
Manage Comments
Add a comment:
scripts/shortcut-add-comment.sh <story-id> "comment text"
Update a comment:
scripts/shortcut-update-comment.sh <story-id> <comment-id> "new text"
Delete a comment:
scripts/shortcut-delete-comment.sh <story-id> <comment-id>
Use
shortcut-show-story.sh
to see comment IDs.
Workflow
- 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 ~/.config/shortcut/api-token
- Stories are created in "Unstarted" state by default (workflow_state_id: 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
