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)
2. 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. Optionally add to ~/.bashrc for persistence:

   export SHORTCUT_API_TOKEN=$(cat ~/.config/shortcut/api-token 2>/dev/null | tr -d '\n')
   

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 functionality
• bug - Bug fix
• chore - Maintenance task

Update Story

scripts/shortcut-update-story.sh <story-id> [--complete|--todo|--in-progress] [--description "new text"]

Workflow state IDs vary by workspace. Common defaults:

• To Do (typically 500000006)
• In Progress (typically 500000007)
• Done (typically 500000010)

To find your workspace's state IDs, use the Shortcut API or check your board settings.

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

1. List existing stories to understand current board state
2. Create new stories with descriptive names and appropriate types
3. 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