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.
The Superthread CLI (st) is a command-line tool for interacting with the Superthread API. You can manage cards, boards, sprints, projects, pages, notes, and comments, all from your terminal.
Installation
macOS / Linux / WSL
curl -fsSL https://cli.superthread.com/install.sh | sh
st to ~/.local/bin. If the directory isn’t already in your PATH, the installer adds it to your shell profile automatically.
To install to a custom directory:
INSTALL_DIR=/usr/local/bin curl -fsSL https://cli.superthread.com/install.sh | sh
Windows PowerShell
irm https://cli.superthread.com/install.ps1 | iex
st.exe to %LOCALAPPDATA%\superthread and offers to add it to your PATH.
To install to a custom directory:
$env:INSTALL_DIR = "C:\your\path"; irm https://cli.superthread.com/install.ps1 | iex
Claude Code skill (recommended)
We’ve been extremely impressed by how well AI tools are able to use the Superthread CLI with a skill.
So we’ve bundled the CLI with an optional skill. 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. You can review the skill here.
Install the Superthread skill
This writes a skill file to ~/.claude/skills/superthread-cli/SKILL.md.
Getting started
# Log in via browser (OAuth2)
st auth login
# Check your auth status and workspace ID
st auth status
# Start using the CLI
st boards list -s "My Space"
st cards list --assignee me
st users me
Configuration
Configuration is resolved in this order (highest precedence first):
- CLI flags (
--token, --api-url, --output/-o)
- Environment variables (
ST_TOKEN, ST_API_URL, ST_OUTPUT_FORMAT)
- Config file
~/.config/superthread/config.yaml
The config file is created automatically after st auth login. Example:
token: <your-token>
refresh_token: <your-refresh-token>
workspace_id: <your-workspace-id>
api_url: https://api.superthread.com # optional
output_format: json # optional: json, text (default text)
Flag shorthands
| Long | Short | Meaning |
|---|
--space | -s | Space (name or ID) |
--board | -b | Board (name or ID) |
--list | -l | List (name or ID) |
--card | -c | Card ID |
--assignee | -a | Assignee (name, email, ID, or me) |
--tag | -t | Tag filter (comma-separated names or IDs) |
--user | -u | User (name, email, or ID) |
--output | -o | Output format (json, text) |
--archived | | Include archived items |
--yes | -y | Skip confirmation prompts |
Name-to-ID resolution
Most commands accept names or IDs for spaces, boards, and users:
st boards list -s Engineering # space by name
st boards list -s 123 # space by ID
st cards update 456 --assignee me # "me" resolves to your user ID
st spaces add-member MySpace -u "Jane Doe" # space and user by name
me as a shortcut for your own user ID with --assignee, --owner, or --user.
Use current with --sprint to target the active sprint in a space.
Use --output/-o to control the output format:
st boards list -o json
st cards get 456 -o json
output_format: json) or environment variable (ST_OUTPUT_FORMAT=json).
Content flags
All commands that accept --content also accept --description and --desc as aliases. Content supports GitHub Flavored Markdown.
Commands
| Command | Description |
|---|
st auth login | Log in via browser (OAuth2) |
st auth logout | Log out and remove stored credentials |
st auth status | Show current authentication status |
st boards | Create, get, list, update, delete, duplicate boards and lists (--default-lists, --status) |
st cards | Create, get, list, update, delete, archive, duplicate cards |
st cards tags | List, add, remove tags on cards |
st cards related | Add, remove related cards |
st checklists | Create, get, list, update, delete checklists and checklist items |
st projects | Create, get, list, update, delete, archive projects |
st projects health | Update, list, delete health status; configure staleness period |
st projects related | Add, remove related projects |
st projects tags | List, add, remove tags on projects |
st pages | Create, get, list, update, delete, archive, duplicate pages |
st notes | Create, get, list, delete notes |
st comments | List, create, get, edit, delete comments |
st comments reply | Reply to a comment |
st comments replies | List, edit, delete replies |
st comments react | Add a reaction to a comment |
st comments unreact | Remove a reaction from a comment |
st spaces | Create, get, list, update, delete spaces |
st spaces add-member | Add a member to a space |
st spaces remove-member | Remove a member from a space |
st sprints | Create, get, list, update sprints |
st sprints settings | Get and update sprint settings |
st users me | Show current user info |
st users list | List workspace members |
st search | Search across your workspace |
st completion | Set up shell completions |
st claude install | Install or update the Superthread skill for Claude Code |
st version | Print the CLI version |
st update | Update to the latest version |
st <command> --help for details on any command.
Delete commands prompt for confirmation before executing. Pass --yes or -y to skip the prompt.
Shell completion
Set up completions interactively:
This detects your shell and writes the completion script to the right place. Supported shells: bash, zsh, fish, PowerShell.
You can also generate raw scripts for manual setup:
source <(st completion generate zsh)
Examples
# List boards in a space
st boards list -s Engineering
# Create a board with default lists (Backlog, Todo, Doing, Done, Cancelled)
st boards create -s Engineering --title "Sprint Board" --default-lists
# Create a list with an explicit status type
st boards create-list -b "Sprint Board" --title "QA" --status doing
# List cards on a board, sprint, or by assignee
st cards list -b "Sprint Board"
st cards list --sprint current -s Engineering
st cards list --assignee me
st cards list --assignee me --status all # include done/cancelled
st cards list --assignee me --tag bug # filter by tag
# Find cards by content, priority, or due date (views-path filters)
st cards list --content "login bug" # title + description substring
st cards list --title "agentkit" --is-parent # title substring; parent cards only
st cards list --assignee me --priority 3,4 # my high/urgent cards
st cards list --creator me --has-tags # cards I created that have tags
st cards list --assignee me --due-before now+7d # my cards due within 7 days
st cards list --has-blockers --sort-by priority --sort-desc # blocked cards by priority
# Create a card
st cards create -l <list-id> --title "Fix login bug" -b "Sprint Board"
# Create a card in the current sprint
st cards create --title "Sprint task" --sprint current -s Engineering --assignee me
# Create a card in a project
st cards create -l <list-id> --title "Subtask" --project "Q1 Roadmap"
# Create a card with a parent
st cards create -l <list-id> --title "Subtask" --parent <parent-card-id>
# Create a card with children
st cards create -l <list-id> --title "Parent task" --child <child-id-1> --child <child-id-2>
# Create a card with tags
st cards create -l <list-id> --title "Bug fix" -b "Sprint Board" --tag bug
st cards create -l <list-id> --title "Feature" -b "Sprint Board" -t feature,frontend
# Update a card
st cards update 456 --title "New title" --priority 2 --due-date 2026-03-27
# Move a card to the current sprint
st cards update 456 --sprint current -s Engineering
# Add or remove a card from a project
st cards update 456 --project "Q1 Roadmap"
st cards update 456 --project none
# Set or remove a parent card
st cards update 456 --parent <parent-card-id>
st cards update 456 --parent none
# Add a child card
st cards update 456 --child <child-card-id>
# Add tags to a card
st cards update 456 --tag bug
st cards update 456 -t bug,feature
# Create a project (defaults to first list on the project board)
st projects create --title "Q2 Roadmap" --tag roadmap
# Create a project in a specific list by name
st projects create --title "Sprint goal" -l "In progress"
# Add tags to a project
st projects update <project-id> -t backend,infrastructure
# Replace a project's description (markdown)
st projects update <project-id> --content "## Q2 priorities"
# Update a project's health status
st projects health update <project-id> --status at-risk -m "Blocked on dependency"
# View health update history
st projects health list <project-id>
# Search
st search "auth bug" --types cards,pages -s Engineering
# Delete a card (skipping confirmation)
st cards delete 456 -y
