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 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

AI Skill Market Insights

Be Part of the 2,142+ Developer Community

Shortcut Kanban Integration

Prerequisites

Setup

Available Operations

List Stories

Show Story Details

Create Story

Update Story

Manage Checklist Tasks

Manage Comments

Workflow

Notes

Quick Start

Manual Installation

TEAR & SHARE

Tags

README

OpenClaw WhatsApp

Gotify

Reflect Notes

Farcaster Agent

Channels

Learn

Compare

Company