Shortcut Tool Reference

Use shortcut-api-read for read operations and shortcut-api-write for write operations.

Pattern: shortcut-api-{read|write} <entity> <operation> [args...]

Operations

Stories

Stories are the standard unit of work in Shortcut.

Get a story:

shortcut-api-read stories get <story-id>

Search stories:

shortcut-api-read stories search \
  --query "search text" \
  --owner-ids <user-id> \
  --team-id <team-id> \
  --iteration-id <iteration-id> \
  --epic-id <epic-id> \
  --workflow-state-id <state-id> \
  --story-type feature|bug|chore \
  --limit 25

Get branch name for a story:

shortcut-api-read stories branch-name <story-id>

Returns a formatted git branch name like sc-123/feature-description

Create a story:

shortcut-api-write stories create "Story title" \
  --type feature|bug|chore \
  --description "Story description" \
  --team-id <team-id> \
  --owner-ids <user-id> <user-id> \
  --iteration-id <iteration-id> \
  --epic-id <epic-id> \
  --estimate 3

Create a story and checkout a branch:

shortcut-api-write stories create-and-checkout "Story title" \
  --type feature|bug|chore \
  --description "Story description" \
  --team-id <team-id> \
  --owner-ids <user-id> <user-id> \
  --iteration-id <iteration-id> \
  --epic-id <epic-id> \
  --estimate 3

Update a story:

shortcut-api-write stories update <story-id> \
  --name "New title" \
  --description "New description" \
  --type bug \
  --workflow-state-id <state-id> \
  --iteration-id <iteration-id> \
  --archived

Delete a story:

shortcut-api-write stories delete <story-id>

Add a comment to a story:

shortcut-api-write stories comment <story-id> "Comment text"

Epics

Epics are collections of related stories representing larger features or initiatives.

Get an epic:

shortcut-api-read epics get <epic-id>

List all epics:

shortcut-api-read epics list

Search epics:

shortcut-api-read epics search --query "search text" --state "in progress"

Create an epic:

shortcut-api-write epics create "Epic name" \
  --description "Epic description" \
  --state "to do" \
  --owner-ids <user-id>

Update an epic:

shortcut-api-write epics update <epic-id> \
  --name "New name" \
  --state "done" \
  --archived

Delete an epic:

shortcut-api-write epics delete <epic-id>

Iterations

Iterations (sprints) are time-boxed periods of development.

Get current active iteration:

shortcut-api-read iterations list --status started

Get a specific iteration:

shortcut-api-read iterations get <iteration-id>

List all iterations:

shortcut-api-read iterations list
shortcut-api-read iterations list --status started|unstarted|done
shortcut-api-read iterations list --with-stats

Create an iteration:

shortcut-api-write iterations create "Sprint 1" 2025-01-01 2025-01-14 \
  --description "Sprint description" \
  --team-ids <team-id>

Update an iteration:

shortcut-api-write iterations update <iteration-id> \
  --name "Sprint 2" \
  --start-date 2025-01-15 \
  --end-date 2025-01-28

Delete an iteration:

shortcut-api-write iterations delete <iteration-id>

Teams

Teams represent groups of people working together.

Get a team:

shortcut-api-read teams get <team-id>

List all teams:

shortcut-api-read teams list

Workflows

Workflows define the states that stories move through.

Get a workflow:

shortcut-api-read workflows get <workflow-id>

List all workflows:

shortcut-api-read workflows list

Users/Members

Manage workspace members and get current user information.

Get a member:

shortcut-api-read users get <member-id>

List all members:

shortcut-api-read users list

Get current user:

shortcut-api-read users current

Get current user's teams:

shortcut-api-read users current-teams

Objectives

Objectives represent high-level goals.

Get an objective:

shortcut-api-read objectives get <objective-id>

List all objectives:

shortcut-api-read objectives list

Create an objective:

shortcut-api-write objectives create "Objective name" \
  --description "Objective description"

Update an objective:

shortcut-api-write objectives update <objective-id> \
  --name "New name" \
  --state "done"

Delete an objective:

shortcut-api-write objectives delete <objective-id>

Documents

Create documentation in Shortcut.

Create a document:

shortcut-api-write documents create "Doc title" "<h1>HTML Content</h1>"

Common Workflows

Get Stories in Current Iteration

# Get current iteration
shortcut-api-read iterations list --status started
# Then search stories with the iteration ID and your user ID
shortcut-api-read stories search --iteration-id <id> --owner-ids <user-id>

Creating a Story with Full Context

When creating a story, gather the necessary IDs first:

1. Get current user: shortcut-api-read users current
2. List teams: shortcut-api-read teams list
3. Get current iteration: shortcut-api-read iterations list --status started
4. Create the story with gathered information

Story Creation from Title

For the common pattern of parsing a conventional commit-style title:

# Parse title like "feat(edge-gateway): add v2 rate limiting"
# Extract type (feat = feature, bug = bug, chore = chore)
# Get team ID for "Infra Team"
# Get current user or specified owner
# Get current started iteration
# Create story and get branch name

shortcut-api-write stories create "add v2 rate limiting" \
  --type feature \
  --team-id <infra-team-id> \
  --owner-ids <user-id> \
  --iteration-id <current-iteration-id>

# Then get the branch name
shortcut-api-read stories branch-name <new-story-id>