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
More from steveclarke/dotfiles
md-to-pdf
Convert markdown files to PDF using Chrome. Use when user wants to render markdown to PDF, print a document, or create a shareable PDF from markdown. Triggers on "markdown to pdf", "render to pdf", "pdf from markdown", "print this markdown".
75feature-vision
Creates vision documents through focused discovery phases, building each section systematically. Produces a vision.md covering problem statement, proposed solution, user experience, and scope boundaries following the established feature development process.
46screenshots
Generate marketing screenshots of your app using Playwright. Use when the user wants to create screenshots for Product Hunt, social media, landing pages, or documentation.
46youtube
Download content from YouTube including transcripts, captions, subtitles, music, MP3s, and playlists. Use when the user provides a YouTube URL or asks to download, transcribe, or get content from YouTube videos or playlists.
46bash-script-writing
Write clean, modular, production-ready bash scripts with proper error handling and maintainable structure. Use when creating new shell scripts, refactoring existing bash code, or when user asks for bash/shell scripting help with terms like "write a script", "bash script", "shell script", or "automate with bash".
46feature-plan
Create implementation plan documents with development phases, sequencing, and actionable tasks. Works through 3 phases (structure, approach, generation) following established feature development process. Use when creating plan.md documents from technical specs. Triggers on "create implementation plan", "plan this feature", "sequence the development".
45