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

# CLI reference

> Install and use the Superthread CLI to manage your workspace from the terminal.

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

```bash theme={null}
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:

```bash theme={null}
INSTALL_DIR=/usr/local/bin curl -fsSL https://cli.superthread.com/install.sh | sh
```

### Windows PowerShell

```powershell theme={null}
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:

```powershell theme={null}
$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](/cli/skill).

Install the Superthread skill

```bash theme={null}
st claude install
```

This writes a skill file to `~/.claude/skills/superthread-cli/SKILL.md`.

## Getting started

```bash theme={null}
# 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):

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`

The config file is created automatically after `st auth login`. Example:

```yaml theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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 whoami` is an alias)                                  |
| `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:

```bash theme={null}
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:

```bash theme={null}
source <(st completion generate zsh)
```

## Examples

```bash theme={null}
# 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
st cards list --project "Q1 Roadmap"             # cards in a specific project/epic
st cards list --project "Q1 Roadmap" --has-assignees=false  # unassigned cards in a project

# 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 page nested under a parent
st pages create -s Engineering --title "Design notes" --parent-page <parent-page-id>

# Reparent a page (move it under a different parent, or to the top level)
st pages update <page-id> --parent-page <parent-page-id>
st pages update <page-id> --parent-page none

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