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

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

Essential Patterns

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

Browse structure

Agents

--mode picks how results are matched: bm25 (the default) for exact words, names and IDs; semantic for concepts and questions, matching by meaning; hybrid when unsure, which combines both. Semantic and hybrid results carry a score (0-100, how closely the result matches the meaning of the query). A workspace that can’t serve a mode rejects it; switch to bm25 rather than retrying.

Tags

Tag management defaults to workspace tags. Use --space/-s to manage tags belonging to that space; names resolve within that scope. Creation requires --name and --color; updates require at least one of them. Colors use #RRGGBB hex format.

Checklists

Comments

Project Health

Health statuses: on-track, at-risk, off-track, not-expected

Full Command Reference

Auth

Spaces

Boards

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

Priority levels: 0=None, 1=Low, 2=Medium, 3=High, 4=Urgent

Cards β€” Tags

Customers

Customers are the people and companies asking for cards and projects. A customer request records one ask against one card or project. Customers, tiers and statuses resolve by name or ID. Use upsert rather than create when a customer may already exist (matched by ID, then external ID, then domain). Common patterns:
Full command list:
Colors for tiers and statuses: fog, slate, grey, charcoal, black, red, orange, yellow, green, ocean, blue, purple, pink. Omitting --customer on requests add records the request against the Unknown customer. st cards get lists a card’s requesting customers; st cards list shows a CUSTOMERS column when any card in the result has one.

Checklists

Projects (Epics)

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

Notes

Note IDs are UUIDs. Template IDs are exact saved IDs from the list or subject context, not titles or URLs. Read a template before editing its full ordered sections. Only the template owner can update or delete it; shared or built-in templates you do not own are read-only. Changes affect future enhancements, and existing enhanced notes change only when explicitly re-enhanced. Instructions alone revise existing saved enhanced HTML. --enhanced-note selects a saved entry; otherwise the entry matching last_note_template_id is used. A missing or empty enhanced entry fails. An explicit --template regenerates from original user notes and the transcript, with optional extra instructions. Neither mode changes the original notes, transcript, or saved template. Read st notes get NOTE_ID --output json before enhancement and use its whole-note revision as --expected-revision. If the revision or operation UUID is omitted, the adapter supplies the current revision or a new UUID. A concurrent edit still prevents the final save. Another operation running on the same note, a stale revision, or an operation UUID reused with different input fails; read the latest note before retrying a conflict. Status is idle, running, completed, or failed. Running content is an unsaved preview. Only completed with ai_note confirms a durable save. If still running, use st notes enhancement with the returned operation UUID, including after disconnecting. Failures return errors and leave the last saved content intact; never claim preview content was saved. Reuse --operation only for identical retry input, and use a new UUID for a new request. Only the note owner can start or observe an enhancement. A custom agent’s note read grant allows reading the note, but does not allow editing it or observing enhancement operations.

Comments & Replies

Sprints

The sidebar is your own, per workspace; there is no way to read or change anyone else’s. Changes show live in open browser tabs. Custom agents cannot use sidebar or favourites.

Favourites

IDs are exact IDs, not names.

Sprint Settings

Users

Agents

Built-in agents (Superthread Agent, Superthread Forms Agent) can be read but not changed β€” they act with the access of whoever invokes them.

Agents β€” Triggers

Search

Completion & Utility

Global Options

Flag Aliases

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, tags, customer requests. st customers merge confirms too, since it cannot be undone.