superthread

Superthread CLI

用于 Superthread API 的项目管理 CLI。

快速入门

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

基本模式

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

大多数命令都接受空间、看板、列表、冲刺、用户和标签的名称或 ID。

提及

使用 {{@Name}} 在评论、回复、检查清单项以及卡片／页面内容中提及工作区成员。系统会将名称与工作区成员的显示名称进行不区分大小写的匹配。

# 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?"

请勿使用原始 HTML 提及标签（例如 <user-mention> 或 <mention-user>）。这些标签不会触发通知。请始终使用 {{@Name}} 模板语法。

若要包含不会触发提及的字面文本 {{@Name}}，请对其进行转义：\{{@Name}}。

常见工作流

查看和管理卡片

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

浏览结构

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

搜索

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

---

完整命令参考

详情如下。以 # Options: 标示的选项均为可选项，除非标明为必填项。

账户

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

供 Agent 使用的非交互式设置：

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

工作区

suth workspaces list
suth workspaces use WORKSPACE
suth workspaces current

当前用户和成员

suth me
suth members list

空间

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

看板

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

列表

看板列管理：

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

卡片

# 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

项目（史诗）

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

页面

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

评论和回复

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

检查清单

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

标签

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

备注

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

冲刺

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

搜索

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)

活动

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

配置和补全

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

全局选项

-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)

选项别名

长选项	短选项	说明
--space	-s	空间（ID 或名称）
--board	-b	看板（ID 或名称）
--list	-l	列表（ID 或名称）
--card	-c	卡片 ID
--related	-r	关联卡片 ID
--owner	-o	负责人（用户 ID、名称、邮箱或 'me'）
--yes	-y	跳过确认

优先级：1=紧急，2=高，3=中，4=低