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

shortcut

Shortcut Kanban Integration

Prerequisites

Setup