> ## Documentation Index > Fetch the complete documentation index at: https://superthread.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Claude skill > The built-in skill that teaches Claude how to use the Superthread CLI. The Superthread CLI includes a built-in skill for [Claude Code](https://claude.ai/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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} --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 ```bash theme={null} 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 list --project "Q1 Roadmap" # Cards in a specific project/epic 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 update CARD_ID --child none # Clear all children st cards update CARD_ID --assignee alice # Add Alice (idempotent if already assigned) st cards update CARD_ID --assignee none # Clear all assignees st cards update CARD_ID --tag bug # Add a tag st cards update CARD_ID --tag none # Clear all tags st cards list --has-blockers # Cards that are blocked st cards list --assignee me --has-blocking # My cards that are blocking others st cards list --relationship-types related,duplicates # Cards with related or duplicate relationships 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 ```bash theme={null} 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 ``` ### Search ```bash theme={null} st search "auth bug" st search "auth bug" --types cards,pages -s Engineering st search "auth bug" --count 50 -a # Include archived ``` ### Tags ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} st auth login # Browser OAuth2 st auth status # Show token + workspace info st auth logout # Remove stored credentials st whoami # Alias for `auth status` ``` ### Spaces ```bash theme={null} 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 ```bash theme={null} st boards list -s SPACE # Options: --archived st boards get BOARD # Options: --space/-s (required when BOARD is a name; numeric IDs skip the check) 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" # Options: --space/-s (required when BOARD is a name) st boards delete BOARD # Confirms # Options: --space/-s (required when BOARD is a name) st boards duplicate BOARD # Options: --space/-s (required when BOARD is a name) st boards create-list -b BOARD --title "Column" # Options: --color, --status, --space/-s (required when --board is a name) # --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 ``` Board name resolution scopes through the workspace's spaces, so a name lookup needs the parent space ID. The CLI returns a clear `validation failed: space_id` error if `--space` is missing on a name-based call. Numeric board IDs short-circuit and don't need `--space`. ### Cards ```bash theme={null} st cards list # Requires one of: --board/-b, --sprint, --assignee/-a, or a views-path filter # 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) # # Views-path filters (stand alone or compose with --assignee; don't combine with --board/--sprint): # --content TEXT substring match across task title + description # --title TEXT substring match against title only # --priority N[,N...] comma-separated priorities (0=none..4=urgent) # --creator REF filter by creator (name, email, ID, or 'me') # --project REF[,REF...] comma-separated project/epic names or IDs (alias: --epic) # --due-before DATE due date strictly before DATE; absolute or date-math (e.g. 'now+7d') # --due-after DATE due date strictly after DATE # --sort-by FIELD due_date | estimate | priority | status | time_created | time_updated # --sort-desc sort descending (default ascending) # --has-due-date tasks that do/don't have a due date (=false to invert) # --has-priority tasks that do/don't have a priority # --has-estimate tasks that do/don't have an estimate # --has-tags tasks that do/don't have tags # --has-assignees tasks that do/don't have assignees # --has-status tasks that do/don't have a status set (no status = backlog) # --has-parent-card equivalent to --is-child # --is-child subtasks only (=false for top-level only) # --is-parent tasks that have at least one subtask # Relationship filters: # --has-blockers tasks that ARE blocked. Use =false to invert. # --has-blocking tasks that ARE blocking others. Use =false to invert. # --has-relationship tasks with ANY relationship to another task. Use =false to invert. # --relationship-types OR list: blocks, blocked_by, related, duplicates. # Mutually exclusive: --has-blockers=true + --has-blocking=true (wire would OR # them, returning "blocked OR blocking" — use --relationship-types=blocked_by,blocks # if OR is what you want); --relationship-types with either semantic flag. 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, --tag/-t # 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; clearing children after create is done via `cards update --child none`) 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, --tag/-t # --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 # --board: name or ID. For names: scoped by --space if given, else lazy-fetches the card's current space. # --project/--epic: project name or ID; use 'none' to remove from project # --parent: parent card ID; use 'none' to remove from parent # --assignee/-a: comma-separated. Adds to existing assignees (idempotent on re-add); use 'none' to clear all. # --tag/-t: comma-separated. Adds to existing tags; use 'none' to clear all. # --child: comma-separated child card IDs. Adds to existing children; use 'none' to clear all. 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 ```bash theme={null} 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 ``` ### Cards — Related ```bash theme={null} 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 ```bash theme={null} 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) ```bash theme={null} st projects list st projects get PROJECT_ID # Options: --health (include health update history) st projects create --title "Q1 Roadmap" # Options: --list/-l (name or ID; defaults to first project list), --content, --owner, --assignee/-a, --priority, --due-date (YYYY-MM-DD) # Projects live on a dedicated roadmap board. --list refers to columns on that board (e.g. "Backlog", "Planned"). st projects create --title "Sprint goal" -l "In progress" # Create in a specific project list by name st projects update PROJECT_ID # Options: --title, --content, --list/-l (name or ID), --owner, --assignee/-a, --priority, --archived, --due-date (YYYY-MM-DD) # --content replaces existing content entirely # --assignee/-a: comma-separated. Adds to existing assignees (idempotent on re-add); use 'none' to clear all. st projects delete PROJECT_ID # Confirms st projects archive PROJECT_ID st projects related add PROJECT_ID RELATED_ID # --type/-t: related (default), blocks, blocked_by, duplicates 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 ```bash theme={null} st pages list -s SPACE # --space/-s required st pages get PAGE_ID st pages create -s SPACE # Options: --title, --content, --parent-page st pages update PAGE_ID # Options: --title, --content, --parent-page # --content replaces existing content entirely # --parent-page: page ID to nest this page under (reparent); use 'none' to move it to the top level st pages delete PAGE_ID # Confirms st pages archive PAGE_ID st pages duplicate PAGE_ID ``` ### Notes ```bash theme={null} st notes list st notes get NOTE_ID st notes create --title "Meeting Notes" st notes delete NOTE_ID # Confirms ``` ### Comments & Replies ```bash theme={null} 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 ```bash theme={null} 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 -s SPACE # --space/-s required # Options: --title, --state (planned|active|completed|cancelled), --start-date, --end-date # --start-date / --end-date: epoch seconds ``` ### Sprint Settings ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} st search QUERY # Options: --types (cards,pages,boards,...), --count N, --space/-s, --archived ``` ### Completion & Utility ```bash theme={null} st completion # Interactive guided setup st completion install # Detect shell and install completions st completion generate bash|zsh|fish|powershell # Print script to stdout st claude install # Install/update this skill at ~/.claude/skills/superthread-cli/SKILL.md # Options: -y to skip confirmation st version st update # Options: --force ``` ## Global Options | Flag | Short | Description | | ----------- | ----- | ------------------------- | | `--token` | | API token override | | `--api-url` | | API base URL override | | `--output` | `-o` | Output format: json, text | | `--yes` | `-y` | Skip confirmations | ## Flag Aliases | Long | Short | Description | | ------------ | ----- | ------------------------------------------------------ | | `--space` | `-s` | Space (name or numeric ID) | | `--board` | `-b` | Board (name or numeric ID) | | `--list` | `-l` | List (name or ID) | | `--card` | `-c` | Card ID | | `--assignee` | `-a` | Assignee — card commands (name, email, ID, or 'me') | | `--tag` | `-t` | Tag filter — cards list (comma-separated names or IDs) | | `--owner` | | Owner — projects/epics only (name, email, or user ID) | | `--user` | `-u` | User (name, email, or user ID) | | `--archived` | | Include 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.