CLI reference

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

This detects your OS and architecture, downloads the latest binary, verifies its checksum, and installs 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

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

st claude install

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

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

Output format

Use --output/-o to control the output format:

st boards list -o json
st cards get 456 -o json

You can also set a default via config file (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

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

st completion

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

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

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

# 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

​Installation

​macOS / Linux / WSL

​Windows PowerShell

​Claude Code skill (recommended)

​Getting started

​Configuration

​Flag shorthands

​Name-to-ID resolution

​Output format

​Content flags

​Commands

​Shell completion

​Examples