steveclarke/superthread

Superthread CLI

Project management CLI for the Superthread API.

Quick Start

brew install steveclarke/tap/superthread
suth setup                        # Interactive wizard — API key, workspace
suth cards assigned me             # See your cards
suth search query "term"           # Search everything

Essential Patterns

--json              # Structured output (for scripts/agents)
-y / --yes          # Skip confirmations
-s SPACE            # Resolve ambiguous names (boards, lists, sprints)
me                  # Current user in any user argument (assigned, assign, --owner, --user, etc.)

Most commands accept names or IDs for spaces, boards, lists, sprints, users, and tags.

Mentions

Use {{@Name}} to mention workspace members in comments, replies, checklist items, and card/page content. The name is matched case-insensitively against workspace member display names.

# Mention in a comment
suth comments create -c CARD --content "{{@Stacey}} Ready for review."

# Mention in a reply
suth replies create --comment COMMENT --content "{{@Steve Clarke}} can you take a look?"

# Multiple mentions
suth comments create -c CARD --content "{{@Stacey}} and {{@Steve Clarke}} — thoughts?"

Do NOT use raw HTML mention tags (e.g., <user-mention> or <mention-user>). These will not trigger notifications. Always use the {{@Name}} template syntax.

To include literal {{@Name}} text without triggering a mention, escape it: \{{@Name}}.

Common Workflows

View and manage cards

suth cards list -b BOARD                         # Cards on a board
suth cards search "login timeout"                # Find cards by keyword
suth cards assigned me                           # My cards
suth cards get CARD                              # Card details
suth cards create --title "Task" -l LIST -b BOARD
suth cards update CARD --list "Done"             # Move card (auto-resolves list name)
suth cards assign CARD user1,user2               # Assign users

Browse structure

suth spaces list                                 # All spaces
suth boards list -s SPACE                        # Boards in a space
suth lists list -b BOARD                         # Columns on a board
suth projects list                               # Roadmap projects

Search

suth cards search "login timeout"                # Find cards (rich output)
suth cards search "bug" --status open,started    # Filter by status
suth cards search "auth" -s SPACE --limit 50     # Filter by space, custom limit
suth search query "term"                         # Search all entity types
suth search query "bug" --types card,page        # Filter by type
suth search query "auth" --status open -s SPACE  # Filter by status and space

---

Full Command Reference

Details below. Options shown as # Options: are optional unless marked required.

Accounts

suth accounts list
suth accounts show
suth accounts use NAME
suth accounts add NAME                           # Interactive
suth accounts add NAME --with-token              # Non-interactive: reads API key from stdin
  # Options: --workspace-name "X"
suth accounts remove NAME

Non-interactive setup for agents:

echo "$SUPERTHREAD_API_KEY" | suth accounts add myaccount --with-token

Workspaces

suth workspaces list
suth workspaces use WORKSPACE
suth workspaces current

Current User & Members

suth me
suth members list

Spaces

suth spaces list
suth spaces get SPACE
suth spaces create --title "Name"
  # Options: --description, --icon NAME, --icon-color "#HEX"
suth spaces update SPACE --title "New Name"
  # Options: --description, --icon NAME, --icon-color "#HEX"
suth spaces delete SPACE
suth spaces add_member SPACE USERS [--role ROLE]   # IDs, names, emails, or 'me'
suth spaces remove_member SPACE USERS

Boards

suth boards list -s SPACE
  # Options: --bookmarked, --include-archived
suth boards get BOARD
  # Options: -s SPACE
suth boards create -s SPACE --title "Name"
  # Options: --description, --layout (board|list|timeline|calendar),
  #          --icon NAME, --color COLOR
suth boards update BOARD --title "New Name"
  # Options: -s SPACE, --description, --layout, --icon, --color, --archived
suth boards duplicate BOARD -s SPACE
  # Options: --title, --copy-cards, --create-missing-tags
suth boards delete BOARD
  # Options: -s SPACE

Lists

Board column management:

suth lists list -b BOARD
  # Options: -s SPACE
suth lists create --title "In Progress" -b BOARD
  # Options: -s SPACE, --description, --icon NAME, --color COLOR
suth lists update LIST --title "Done"
  # Options: --description, --icon NAME, --color COLOR
suth lists delete LIST

Cards

# Listing
suth cards list -b BOARD
suth cards list --sprint SPRINT -s SPACE
  # Options: --list, --include-archived, --since DATE, --updated-since DATE, -s SPACE
suth cards assigned USER                           # USER = ID, name, email, or 'me'
suth cards assigned me
  # Options: --board, --space, --project, --include-archived,
  #          --since DATE, --updated-since DATE

# Search
suth cards search TERM
  # Options: -s SPACE, --status STATUS, --field title|content,
  #          --include-archived, --limit N (default: 30, 0 = unlimited)

# CRUD
suth cards get CARD
  # Options: --raw, --no-content
suth cards create --title "Task" -l LIST -b BOARD
  # Options: --content HTML, --project ID, --parent-card ID, --epic ID,
  #          --sprint SPRINT, -s SPACE, --start-date TIMESTAMP,
  #          --due-date TIMESTAMP, --priority N, --owner/-o USER (or 'me')
suth cards update CARD
  # Options: --title, --content HTML, --list LIST, --board BOARD, --sprint SPRINT,
  #          -s SPACE, --position N, --priority N, --epic ID, --archived/--no-archived
  # Note: list names auto-resolve. Moving to sprint requires --sprint and -s.
  # Note: --content uses a separate PUT endpoint from other fields.
suth cards delete CARD
suth cards duplicate CARD --project ID -b BOARD -l LIST
  # Required: --project, --board/-b, --list/-l
  # Options: --title, --space/-s

# Members (USERS = IDs, names, emails, or 'me'; comma-separated)
suth cards assign CARD USERS
suth cards assign CARD me                          # Assign yourself
suth cards unassign CARD USERS

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

# Tags
suth cards tag CARD tag1,tag2
suth cards untag CARD tag1

Projects (Epics)

suth projects list
suth projects get PROJECT
suth projects create --title "Q1" -l LIST [-b BOARD]
  # Options: --content, --start-date TIMESTAMP, --due-date TIMESTAMP,
  #          --priority N, --owner/-o USER (or 'me'), -s SPACE
suth projects update PROJECT --title "New"
  # Options: --list/-l, --board/-b, --space/-s, --owner/-o USER (or 'me'),
  #          --start-date, --due-date, --priority, --archived
suth projects delete PROJECT
suth projects add_card PROJECT CARD
suth projects remove_card PROJECT CARD

Pages

suth pages list [-s SPACE]
  # Options: --include-archived, --updated-recently
suth pages get PAGE
suth pages create -s SPACE [--title "Doc"]
  # Options: --content, --parent-page ID, --is-public
suth pages update PAGE --title "New title"
  # Options: --content HTML, --is-public, --parent-page ID, --archived
suth pages duplicate PAGE -s SPACE
  # Options: --title, --parent-page ID
suth pages archive PAGE
suth pages delete PAGE

Comments & Replies

suth comments list -c CARD
suth comments get COMMENT
suth comments create --content "Note" -c CARD
  # Options: --page/-p PAGE (for page comments instead of card)
suth comments update COMMENT --content "Updated"
  # Options: --status (resolved|open|orphaned)
suth comments delete COMMENT

suth replies list --comment COMMENT
suth replies get REPLY --comment COMMENT
suth replies create --comment COMMENT --content "Reply text"
suth replies update REPLY --comment COMMENT --content "Updated"
  # Options: --status (resolved|open|orphaned)
suth replies delete REPLY --comment COMMENT

Checklists

suth checklists list -c CARD
suth checklists get CHECKLIST -c CARD
suth checklists create --title "Tasks" -c CARD
suth checklists update CHECKLIST --title "New Title" -c CARD
suth checklists delete CHECKLIST -c CARD

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

Tags

suth tags list
  # Options: --space/-s SPACE, --all (include unused tags)
suth tags create --name "urgent" --color "#ff0000"
  # Options: --space/-s SPACE
suth tags update TAG --name "critical"
  # Options: --color
suth tags delete TAG

Notes

suth notes list
suth notes get NOTE
suth notes create --title "Meeting" [--transcript "..."]
  # Options: --user-notes, --is-public
suth notes delete NOTE

Sprints

suth sprints list -s SPACE
suth sprints get SPRINT -s SPACE

Search

suth search query TERM
  # Options: --types card,page,..., --status open,started, --field title|content,
  #          -s SPACE, --include-archived, --grouped, --limit N (default: 30, 0 = unlimited)

Activity

suth activity                     # Recent activity (default: today)
  # Runs `show` subcommand by default
  # Options: --since DATE, --user USER (or 'me'), --board/-b BOARD, --space/-s SPACE

Config & Completion

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

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

Global Options

-a, --account NAME    Use specific account
-w, --workspace ID    Workspace (ID or name)
-y, --yes             Skip confirmations
-v, --verbose         Detailed logging
-q, --quiet           Minimal logging
--json                JSON output
--limit N             Max items (default: 50)

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, email, or 'me') | | --yes | -y | Skip confirmations |

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