Superthread CLI

Project management CLI for the Superthread API.

Installation

brew install steveclarke/tap/superthread

Setup

suth setup

The interactive wizard will:

1. Prompt for an account name (e.g., "personal" or "work")
2. Prompt for your API key (from Superthread Settings > API)
3. Validate and auto-detect your workspace
4. Save configuration

After setup, try:

suth spaces list
suth boards list -s SPACE
suth cards assigned me

Global Options

-a, --account NAME    Use specific account for this command
-w, --workspace ID    Workspace ID (or use config/env var)
-y, --yes             Skip confirmation prompts (for scripts/agents)
-v, --verbose         Detailed logging
-q, --quiet           Minimal logging
--json                Output in JSON format (default is table)

Command Reference

Accounts

suth accounts list                            # List all configured accounts
suth accounts show                            # Show current account details
suth accounts use NAME                        # Switch to account
suth accounts add NAME                        # Add new account (interactive)
suth accounts remove NAME                     # Remove account

Workspaces

suth workspaces list                          # List available workspaces
suth workspaces use WORKSPACE                 # Set default workspace
suth workspaces current                       # Show current workspace

Current User & Members

suth me                                       # Get current user info
suth members list                             # List workspace members

Spaces

suth spaces list                              # List all spaces
suth spaces get SPACE [-o]                    # Get space details (--open for browser)
suth spaces create --title "Name"             # Create space
suth spaces update SPACE --title "New Name"   # Update space
suth spaces delete SPACE                      # Delete space
suth spaces add_member SPACE USER [--role ROLE]  # Add member
suth spaces remove_member SPACE USER          # Remove member

Boards

suth boards list -s SPACE                     # List boards in space
suth boards get BOARD [-o]                    # Get board details
suth boards lists BOARD                       # List columns on board
suth boards create -s SPACE --title "Name"    # Create board
suth boards update BOARD --title "New Name"   # Update board
suth boards duplicate BOARD                   # Duplicate board
suth boards delete BOARD                      # Delete board

# List (column) management
suth boards create-list -b BOARD --title "In Progress"
suth boards update-list LIST_ID --title "Done"
suth boards delete-list LIST_ID

Cards

suth cards list -b BOARD                      # List cards on a board
  # Options: --space, --list, --include-archived, --since DATE, --updated-since DATE
suth cards get CARD_ID [-o]                   # Get card details (--open for browser)
  # Options: --raw, --no-content
suth cards create --title "Task" -l LIST -b BOARD [options]
  # Options: --content HTML, --parent-card ID, --epic ID,
  #          --sprint SPRINT_ID, --project PROJECT_ID,
  #          --start-date TIMESTAMP, --due-date TIMESTAMP,
  #          --priority N, --owner USER
suth cards update CARD_ID --title "New title" --priority 1
suth cards delete CARD_ID                     # Delete card
suth cards duplicate CARD_ID                  # Duplicate card
suth cards assigned USER                      # Cards assigned to user
suth cards assigned me                        # Cards assigned to me
  # Options: --board, --space, --project, --include-archived,
  #          --since DATE, --updated-since DATE

# Members
suth cards assign CARD_ID USER                # Assign user
suth cards unassign CARD_ID USER              # Unassign user

# Relationships
suth cards link --card CARD --related OTHER --type blocks
suth cards unlink --card CARD --related OTHER

# Tags
suth cards tags                               # List available tags
suth cards tag CARD_ID tag1,tag2              # Add tags
suth cards untag CARD_ID tag1                 # Remove tag

Projects (Epics)

suth projects list                            # List roadmap projects
suth projects get PROJECT_ID [-o]             # Get project details
suth projects create --title "Q1" -l LIST [-b BOARD]
suth projects update PROJECT_ID --title "New"
suth projects delete PROJECT_ID
suth projects add_card PROJECT_ID CARD_ID     # Link card to project
suth projects remove_card PROJECT_ID CARD_ID  # Unlink card

Pages

suth pages list [-s SPACE]                    # List pages
suth pages get PAGE_ID [-o]                   # Get page details
suth pages create -s SPACE [--title "Doc"]    # Create page
suth pages update PAGE_ID --title "New title" # Update page
suth pages duplicate PAGE_ID -s SPACE         # Duplicate page
suth pages archive PAGE_ID                    # Archive page
suth pages delete PAGE_ID                     # Delete page

Comments

suth comments get COMMENT_ID [-o]             # Get comment (opens parent card)
suth comments create --card CARD --content "Note"
suth comments update COMMENT_ID --content "Updated"
suth comments delete COMMENT_ID

Replies

suth replies list COMMENT_ID                  # List replies to a comment
suth replies get REPLY_ID                     # Get reply details
suth replies create COMMENT_ID --content "Reply text"
suth replies update REPLY_ID --content "Updated"
suth replies delete REPLY_ID

Checklists

Checklists are a separate subcommand, not under cards:

suth checklists list -c CARD_ID              # List checklists on a card
suth checklists get CHECKLIST -c CARD_ID     # Get checklist details
suth checklists create --title "Tasks" -c CARD_ID
suth checklists update CHECKLIST --title "New Title" -c CARD_ID
suth checklists delete CHECKLIST -c CARD_ID

# Items
suth checklists add-item CHECKLIST --title "Do thing" -c CARD_ID [--checked]
suth checklists update-item ITEM_ID --checklist CL -c CARD_ID --title "New"
suth checklists remove-item ITEM_ID --checklist CL -c CARD_ID
suth checklists check ITEM_ID --checklist CL -c CARD_ID
suth checklists uncheck ITEM_ID --checklist CL -c CARD_ID

Lists

Board list (column) management as a separate subcommand:

suth lists list -b BOARD                     # List columns on board
suth lists get LIST_ID                       # Get list details
suth lists create --title "In Progress" -b BOARD
suth lists update LIST_ID --title "Done"
suth lists delete LIST_ID

Notes

suth notes list                               # List notes
suth notes get NOTE_ID [-o]                   # Get note details
suth notes create --title "Meeting" [--transcript "..."]
suth notes delete NOTE_ID

Sprints

suth sprints list -s SPACE                    # List sprints in space
suth sprints get SPRINT_ID -s SPACE           # Get sprint details

Search

suth search query "term"                      # Search workspace
suth search query "bug" --types card,page     # Filter by type
suth search query "auth" -s SPACE [--grouped] # Filter by space

Tags

suth tags create --name "urgent" --color "#ff0000"
suth tags update TAG --name "critical"
suth tags delete TAG

Config

suth config init                              # Create default config file
suth config show                              # Show current configuration
suth config set KEY VALUE                     # Set a config value
suth config path                              # Show config file path

Activity

suth activity                                 # Show recent activity across workspace

Discovery

suth tree                                     # Print tree of all available commands

Shell Completion

suth completion bash                          # Generate bash completion script
suth completion zsh                           # Generate zsh completion script
suth completion fish                          # Generate fish completion script

Option Aliases

Long	Short	Description
--space	-s	Space (ID or name)
--board	-b	Board (ID or name)
--list	-l	List (ID or name)
--card	-c	Card ID
--related	-r	Related card ID
--owner	-o	Owner (user ID, name, or email)
--open	-o	Open in browser (on get commands)
--yes	-y	Skip confirmation prompts

Tips

• Most commands accept names or IDs for spaces, boards, lists, users, and tags
• Use -s SPACE to help resolve ambiguous board/list names
• Use --json for scripted output: suth cards assigned me --json
• Use me as a user reference: suth cards assigned me
• Use -o to open any resource in your browser: suth cards get CARD -o
• Use -y to skip confirmation prompts (for scripts/agents)
• Priority levels: 1=Urgent, 2=High, 3=Medium, 4=Low