Skip to main content
The Superthread CLI includes a built-in skill for Claude Code. When installed, it teaches Claude how to use st for project management tasks like creating cards, managing sprints, searching, and more.

​
Install the skill

st claude install
This writes a skill file to ~/.claude/skills/superthread-cli/SKILL.md. The skill is bundled inside the st binary. When you run st update, you’ll be prompted to update the skill automatically if it was previously installed. You can also re-run st claude install at any time to get the latest version.

​
Skill contents

Below is the full skill that gets installed. This is what Claude Code sees when it uses the Superthread CLI on your behalf.

​
Quick Start

st auth login                      # OAuth2 browser login
st auth status                     # Verify token + workspace

st boards list -s Engineering      # Boards in a space
st cards create -l LIST -b BOARD --title "Task"
st search "auth bug" --types cards

​
Essential Patterns

--output json / -o json  # Structured JSON output (for scripts/agents)
-y / --yes               # Skip confirmation prompts
-s SPACE                 # Scope to a space (name or numeric ID)
-b BOARD                 # Scope to a board (name or numeric ID)
me                       # Use as user reference: st projects update ID --owner me
Most commands accept names or IDs for spaces, boards, and users. Space/board/sprint/tag IDs are numeric; user IDs are 8-char alphanumeric starting with u (e.g. uRaEi3th). Any value not matching these patterns is resolved as a name via API lookup. All --content flags accept GitHub Flavored Markdown. --description and --desc are accepted as aliases for --content everywhere. The server converts it to HTML before storage. Use standard markdown: headings, bold, lists, task lists (- [ ]), code blocks, blockquotes, etc. Always use multi-line strings for content with structure — never use literal \n escape sequences. Important: Only set optional fields (priority, estimate, due date, tags) when the user explicitly asks or clearly implies a value. Do not assume defaults for these fields.

​
Common Workflows

​
View and manage cards

st cards list -b BOARD                        # List cards on a board
st cards list --sprint current -s SPACE       # List cards in active sprint
st cards list --assignee me                   # List my active cards (excludes done/cancelled)
st cards list --assignee me --status all      # List all my cards including done/cancelled
st cards list --assignee me --status done     # List only my completed cards
st cards list --assignee me --tag bug        # Filter by tag
st cards list --assignee me -t bug,feature   # Filter by multiple tags
st cards list --assignee me --sprint current -s SPACE  # My cards in current sprint
st cards get CARD_ID
st cards create --title "Fix login bug" -l LIST -b BOARD
st cards create --title "Sprint task" --sprint current -s Engineering --assignee me  # Create in active sprint
st cards create --title "Sprint task" --sprint 90 -s Engineering                   # Create in specific sprint
st cards create --title "Subtask" -l LIST --project "Q1 Roadmap"                   # Create in a project (epic)
st cards create --title "Subtask" -l LIST --parent PARENT_CARD_ID                  # Create with a parent card
st cards create --title "Parent" -l LIST --child CHILD_ID --child CHILD_ID2        # Create with child cards
st cards update CARD_ID --title "New title" --priority 2 --due-date 2026-03-27
st cards update CARD_ID --content "## New description\n\nReplaces existing content."
st cards update CARD_ID --project "Q1 Roadmap"                                     # Add card to a project (epic)
st cards update CARD_ID --project none                                             # Remove card from project
st cards update CARD_ID --parent PARENT_CARD_ID                                    # Set parent card
st cards update CARD_ID --parent none                                              # Remove from parent card
st cards update CARD_ID --child CHILD_CARD_ID                                      # Add a child card
st cards archive CARD_ID
st cards duplicate CARD_ID
st cards delete CARD_ID                       # Prompts for confirmation
st cards delete CARD_ID -y                    # Skip confirmation

​
Browse structure

st spaces list
st spaces get Engineering                     # By name
st boards list -s Engineering                 # Boards in a space
st sprints list -s Engineering
st users list
st users me

st search "auth bug"
st search "auth bug" --types cards,pages -s Engineering
st search "auth bug" --count 50 -a            # Include archived

​
Tags

st cards tags list -s SPACE
st cards tags add CARD_ID TAG...              # TAG: name or ID
st cards tags remove CARD_ID TAG

​
Checklists

st checklists list -c CARD_ID                  # List checklists on a card
st checklists create -c CARD_ID --title "QA"   # Create checklist
st checklists add-item CL_ID -c CARD_ID --title "Step 1"
st checklists check ITEM_ID -c CARD_ID --checklist CL_ID
st checklists uncheck ITEM_ID -c CARD_ID --checklist CL_ID

​
Comments

st comments list -c CARD_ID
st comments list --page PAGE_ID
st comments create --content "**Important:** check the logs" -c CARD_ID
st comments create --content "Note" --page PAGE_ID
st comments reply COMMENT_ID --content "Reply with **markdown**"
st comments react COMMENT_ID --unicode "👍"
st comments delete COMMENT_ID

​
Project Health

st projects health update PROJECT_ID --status at-risk -m "Blocked on dependency"
st projects health list PROJECT_ID                     # View health update history
st projects health delete COMMENT_ID                   # Revert to previous status
st projects health set-period PROJECT_ID --days 14     # Configure staleness period ('none' to disable)
st projects get PROJECT_ID --health                    # Project details with inline health history
Health statuses: on-track, at-risk, off-track, not-expected

​
Full Command Reference

​
Auth

st auth login                                 # Browser OAuth2
st auth status                                # Show token + workspace info

​
Spaces

st spaces list
st spaces get SPACE
st spaces create --title "Name"
  # Options: --description, --private
st spaces update SPACE --title "New"
  # Options: --description
st spaces delete SPACE                        # Confirms
st spaces add-member SPACE -u USER            # User: name, email, or ID
st spaces remove-member SPACE -u USER

​
Boards

st boards list -s SPACE
  # Options: --archived
st boards get BOARD
st boards create -s SPACE --title "Name"
  # Options: --default-lists
  # --default-lists creates standard lists: Backlog, Todo, Doing, Done, Cancelled
st boards create -s SPACE --title "Sprint Board" --default-lists
st boards update BOARD --title "New"
st boards delete BOARD                        # Confirms
st boards duplicate BOARD
st boards create-list -b BOARD --title "Column"
  # Options: --color, --status
  # --status sets the list status type (backlog, todo, doing, done, canceled)
  # Status is auto-inferred from common titles (e.g. "To Do" → committed, "Done" → completed)
st boards create-list -b BOARD --title "QA" --status doing
st boards update-list LIST_ID --title "New"
  # Options: --color

​
Cards

st cards list
  # Requires one of: --board/-b, --sprint, or --assignee/-a
  # Options: --space/-s (required with --sprint), --status, --tag/-t, --archived
  # --assignee/-a supports 'me', user name, email, or ID
  # --sprint supports 'current' or sprint name/ID
  # --status: comma-separated statuses or 'all'
  #   Canonical: backlog, committed, started, completed, cancelled
  #   Aliases:   backlog, todo,      doing,   done,      canceled
  #              (also: in-progress, in_progress, active, finished,
  #               closed, deployed, production, live, shipped, complete)
  # When --assignee is used, defaults to backlog+committed+started (hides done/cancelled)
  # --tag/-t: comma-separated tag names or IDs (cards matching any listed tag)
st cards get CARD_ID
st cards create --title "Task" -l LIST -b BOARD
  # Options: --content, --priority (0-4), --estimate, --due-date (YYYY-MM-DD), --sprint, --space/-s, --assignee/-a, --project/--epic, --parent, --child
  # When --sprint is set, --list is optional (defaults to sprint's Todo list)
  # --space/-s always required with --sprint
  # --project/--epic: project name or ID to add the card to
  # --parent: parent card ID
  # --child: child card ID (repeatable; to remove a child, use --parent none on the child card)
st cards update CARD_ID
  # Options: --title, --content, --list/-l, --board/-b, --sprint, --space/-s, --assignee/-a, --priority, --estimate, --due-date (YYYY-MM-DD), --project/--epic, --parent, --child
  # --list/-l: list name or ID; --sprint/-s not needed when moving within the card's current sprint/board
  # --content replaces existing content entirely
  # --sprint: name, ID, or 'current'; --space/-s always required with --sprint
  # --project/--epic: project name or ID; use 'none' to remove from project
  # --parent: parent card ID; use 'none' to remove from parent
  # --child: child card ID (repeatable)
st cards delete CARD_ID                       # Confirms
st cards archive CARD_ID
st cards duplicate CARD_ID
Priority levels: 0=None, 1=Low, 2=Medium, 3=High, 4=Urgent

​
Cards — Tags

st cards tags list
  # Options: --space/-s
st cards tags add CARD_ID TAG [TAG...]         # TAG: name or ID
st cards tags remove CARD_ID TAG

st cards related add CARD_ID RELATED_CARD_ID          # --type/-t: related (default), blocks, blocked_by, duplicates
st cards related remove CARD_ID RELATED_CARD_ID

​
Checklists

st checklists list -c CARD_ID                  # List checklists on a card
st checklists get CHECKLIST_ID -c CARD_ID      # Get checklist with items
st checklists create -c CARD_ID --title "QA Steps"
  # Options: --content
st checklists update CHECKLIST_ID -c CARD_ID
  # Options: --title, --content
st checklists delete CHECKLIST_ID -c CARD_ID   # Confirms
st checklists add-item CHECKLIST_ID -c CARD_ID --title "Step 1"
  # Options: --content, --checked
st checklists update-item ITEM_ID -c CARD_ID --checklist CHECKLIST_ID
  # Options: --title, --content, --checked
st checklists delete-item ITEM_ID -c CARD_ID --checklist CHECKLIST_ID  # Confirms
st checklists check ITEM_ID -c CARD_ID --checklist CHECKLIST_ID
st checklists uncheck ITEM_ID -c CARD_ID --checklist CHECKLIST_ID

​
Projects (Epics)

st projects list
st projects get PROJECT_ID
  # Options: --health (include health update history)
st projects create --title "Q1 Roadmap" -l LIST
  # Options: --content, --owner, --assignee/-a, --priority, --due-date (YYYY-MM-DD)
st projects update PROJECT_ID
  # Options: --title, --list/-l, --owner, --assignee/-a, --priority, --archived, --due-date (YYYY-MM-DD)
st projects delete PROJECT_ID                 # Confirms
st projects archive PROJECT_ID
st projects related add PROJECT_ID RELATED_ID
st projects related remove PROJECT_ID RELATED_ID
st projects tags list
st projects tags add PROJECT_ID TAG [TAG...]   # TAG: name or ID
st projects tags remove PROJECT_ID TAG
st projects health update PROJECT_ID --status STATUS -m "Message"
  # --status: on-track, at-risk, off-track, not-expected
  # -m/--message: required explanation for the status change (markdown)
st projects health list PROJECT_ID             # List health update history
st projects health delete COMMENT_ID           # Delete a health update (reverts status); confirms
st projects health set-period PROJECT_ID --days N
  # Days between expected check-ins; project is marked stale if no update within this window
  # Use 'none' to disable staleness tracking
st projects get includes health status info. Use --health to also show the health update history inline. st projects list includes a HEALTH column showing each project’s current health status.

​
Pages

st pages list
  # Options: --space/-s
st pages get PAGE_ID
st pages create -s SPACE
  # Options: --title, --content, --parent-page
st pages update PAGE_ID
  # Options: --title, --content
  # --content replaces existing content entirely
st pages delete PAGE_ID                       # Confirms
st pages archive PAGE_ID
st pages duplicate PAGE_ID

​
Notes

st notes list
st notes get NOTE_ID
st notes create --title "Meeting Notes"
st notes delete NOTE_ID                       # Confirms

​
Comments & Replies

st comments list -c CARD_ID                    # List comments on a card
st comments list --page PAGE_ID                # List comments on a page
  # Options: --filter (resolved, open, orphaned)
st comments get COMMENT_ID
st comments create --content "Text" -c CARD_ID
st comments create --content "Text" --page PAGE_ID
st comments edit COMMENT_ID --content "Updated"
st comments delete COMMENT_ID                 # Confirms
st comments reply COMMENT_ID --content "Reply text"
st comments react COMMENT_ID --unicode "👍"
st comments unreact COMMENT_ID --reaction REACTION_ID

st comments replies list COMMENT_ID
st comments replies edit COMMENT_ID REPLY_ID --content "Updated"
st comments replies delete COMMENT_ID REPLY_ID   # Confirms

​
Sprints

st sprints list -s SPACE                      # --space/-s required
  # Options: --archived
st sprints get SPRINT_ID -s SPACE              # --space/-s required
st sprints create -s SPACE
  # Options: --title
st sprints update SPRINT_ID
  # Options: --title, --state (canceled|completed), --start-date, --end-date

​
Sprint Settings

st sprints settings get -s SPACE
st sprints settings update -s SPACE --enabled --length 14 --cooldown 0 --start-day 1
  # All flags required. --length: 7-56 days (multiples of 7)
  # --cooldown: 0,7,14,21,28 days. --start-day: 0=Sun..6=Sat

​
Users

st users me
st users list
st users update-me
  # Options: --first-name, --last-name, --display-name
st users update-member USER --role ROLE       # --role required
st users delete-member USER                   # Confirms

​
Search

st search QUERY
  # Options: --types (cards,pages,boards,...), --count N, --space/-s, --archived

​
Completion & Utility

st completion                                  # Interactive guided setup
st completion generate bash|zsh|fish|powershell  # Print script to stdout
st version
st update                                     # Options: --force

​
Global Options

FlagShortDescription
--tokenAPI token override
--api-urlAPI base URL override
--output-oOutput format: json, text
--yes-ySkip confirmations

​
Flag Aliases

LongShortDescription
--space-sSpace (name or numeric ID)
--board-bBoard (name or numeric ID)
--list-lList (name or ID)
--card-cCard ID
--assignee-aAssignee — card commands (name, email, ID, or ‘me’)
--tag-tTag filter — cards list (comma-separated names or IDs)
--ownerOwner — projects/epics only (name, email, or user ID)
--user-uUser (name, email, or user ID)
--archivedInclude archived items

​
Configuration

Precedence (highest first):
  1. CLI flags (--token, --api-url, --output/-o)
  2. Environment variables (ST_TOKEN, ST_API_URL, ST_OUTPUT_FORMAT)
  3. Config file ~/.config/superthread/config.yaml (created by st auth login)

​
Delete Confirmation

All delete commands prompt before executing. Use --yes/-y to skip (useful for scripts). Confirmed deletes: spaces, boards, cards, projects, pages, notes, comments, replies, team members.