dadamsuk/slipdock

Slipdock CLI

slipdock 命令与用户的 Slipdock 应用通信 —— 该应用托管在 app.slipdock.us，或者由用户自托管在其可访问的任何地址。每次写入都会实时显示在 Web UI 中。运行 slipdock --help 查看完整参考。

使用哪个服务器。 $SLIPDOCK_URL，否则是 ~/.config/slipdock/url（由 slipdock url <address> 写入，或由服务器自身的 /install.sh 写入），否则是本机的 tailnet 地址加上 :4000。如果其中没有一个指向用户所指的看板，请询问用户地址 —— 不要猜测。

如果你要从看板开始工作 —— 接取下一个任务、执行一个史诗、在执行工作期间保持卡片更新 —— 请先运行 slipdock guide（服务器为代理提供的说明：史诗和子卡片、如何选择下一个卡片、回写什么内容）并遵循它。此文件是命令参考；指南是工作流。

如果 Slipdock 的 MCP 工具已连接

当当前会话已有 Slipdock 工具（来自服务器 /mcp 的 list_boards、get_card、create_card、complete_card……）时，它们可以作为 CLI 的替代方案执行相同的工作：使用可用的任何一种。二者的约定是相同的 —— get_guide 返回 slipdock guide 打印的简短指南，以其其他部分的名称结尾；section: "automations"（或任何这些名称，或 "all"）给出其中一个。archive_card 将卡片归档，restore: true 将其恢复；archive_board 对看板执行相同操作。优先使用这些：delete_card（需要 confirm: true）、delete_list 和 delete_board（confirm 是看板的代码）无法撤销。create_list、create_tag 和 create_board 添加结构（标签必须先于 create_card/update_card 将其放置到卡片上）。list_cards 使用 full: true 时一次性读取每张卡片的全部内容（评论、检查清单、文档），无需每次调用 get_card。update_card 还能设置依赖关系并操作检查清单。list_pages 列出看板的 wiki（tree: true 可嵌套显示，效果与 page tree 相同），read_page 读取一个页面。page_info 回答 page links、page sections、page wanted 和 page resolve 的功能 —— 在编辑章节时先向其请求 sections，而不是猜测标题路径。page_history 对应 page history，page diff（rev、rev + against 用于比较两个版本，或 diff: true 用于最新保存版本），revert_page 对应 page revert：它需要页面当前的 content_hash 作为 base_hash。update_page 对应 page edit --title/--summary/--tag、page mv、page file、page rm/page restore（archived）和 page pin --card（pin_card/unpin_card）。 upload_file 对应 attach，适用于最大 10 MB 的文件（content_base64 或 text）。模型生成的 Base64 编码在超过约 1 KB 时容易出错 (#1040)，因此如果文件在 shell 中可用，请不要发送 Base64：使用 slipdock attach，或使用 upload_file 并带上 card/page 和 link: true (#1147)，这将返回一个一次性的 upload_url，有效期为 10 分钟，且无需令牌，用于 curl -F file=@FILE -F sha256=<hex> <upload_url>（还有 filename、replace、hide_on_card），从而避免将字节数据传递给模型。 download_file 使用 link: true 时是反向操作：curl -fsSo FILE <download_url>。已存在于用户同步 wiki 中的文件由服务器使用 wiki_file 复制（你的 wiki 中的路径或其 ID；无需内容）。content_base64 必须包含 sha256（即 base64 编码前字节的十六进制哈希），sha256_mismatch 拒绝意味着需要重新编码并重新发送。返回结果中的 sha256 是存储后字节的哈希，get_card/read_page 会为每个文件列出该哈希：将其与源文件的哈希对比以验证文件，无需下载。任何大于几 KB 的内容都将以大约 4 KB 的块发送 (#1016)，因为 Base64 越长越容易损坏：第一个块带上 append: true、card/page、filename 和该块的 sha256 会返回一个 upload_id；后续每个块发送 upload_id、append: true、offset（上一次回答的 received）和自己的 sha256，被拒绝的块会重新发送；然后发送 upload_id、finish: true 和整个文件的 sha256 以完成附件。在此之前，卡片上不会显示任何内容。重建已经存在于卡片上的文件时，发送 replace: true（在单次调用、第一个块或 finish 中）：一旦新文件存储完成，该文件名的旧版本将被移除，只保留一个当前副本。 delete_attachment（detach；attachment ID 和 confirm: true）直接移除一个附件，例如你错误上传的文件。download_file 通过其 ID 读取一个已附件的文件（get_card 和 read_page 会列出它们）。 list_automations 对应 automations/automation（加上 vocabulary: true 可获取 automation-help 和 automation-presets 提供的内容），manage_automation 对应 new-automation（action: create）、set-automation（update）和 delete-automation（delete，带 confirm: true）。 list_tools 对应 tools/tools show（每个 Tool 的种类和 installed.board，即你安装所创建的看板；带 file 时对应 tools file；skill 读取其 SKILL.md；link: true 给出一个一次性 download_url 用于文件、技能的 zip 或技能包， #1158；package: true 对应 tools download），install_tool 对应 tools install-board。任何工具未涵盖的操作（立即运行规则、回调和警报、冲刺、超过 10 MB 的文件、字段）仍使用 CLI 或 API。

如果 CLI 未在此处安装

以下所有内容都是 JSON API 的封装，API 是后备方案：它仅需 curl。不要告诉用户安装 CLI（它是一个 escript，需要 Erlang）—— 使用 API，并且仅在用户询问更方便的键入方式或 wiki 同步（仅 CLI 支持）时才提及 CLI。在 Windows 上，只需要在 PowerShell 中执行一行命令：从用户自己的服务器运行 irm "$B/cli/install.ps1" | iex，然后运行 slipdock auth。在其他平台上，需要从仓库的 cli/ 构建。

B="${SLIPDOCK_URL:-$(cat ~/.config/slipdock/url 2>/dev/null)}"
T="$(cat ~/.config/slipdock/token 2>/dev/null)"
H="Authorization: Bearer ${SLIPDOCK_TOKEN:-$T}"

curl -s "$B/api/guide"                 # 无需令牌；完整 API，每个调用都附有 curl 示例
curl -s -H "$H" "$B/api/me"            # 查询令牌对应的用户是谁

GET /api/guide 是完整的参考文档 —— 每个端点及其 curl 示例，以及在传递令牌时显示用户自己的看板和列表。请阅读它，而不是从此文件推断路径。

登录也不需要 CLI；同样使用设备授权流程，只需两个调用（指南中有详细说明）。请求一个代码，向用户显示 URL 和代码，轮询直到他们批准，然后将令牌写入 ~/.config/slipdock/token，权限设置为 600，以便下次会话可用：

curl -s -X POST "$B/api/auth/device" -H 'content-type: application/json' \
     -d '{"label":"claude on this machine","scope":"write"}'
# → user_code, verification_uri, device_code, interval
curl -s -X POST "$B/api/auth/device/token" -H 'content-type: application/json' \
     -d '{"device_code":"…"}'
# → 在批准前返回 400 authorization_pending，批准后返回 {"token":"…"}

要在没有任何这些技能的系统上安装它们： curl -fsSL "$B/install.sh" | sh（仅需 curl 和 tar）；在 Windows 上，在 PowerShell 中：irm "$B/install.ps1" | iex（安装到 %USERPROFILE%\.claude\skills，而不是 WSL 的家目录）。 对于无法运行此 CLI 的 ChatGPT，slipdock skills chatgpt 会将它们保存为 zip 文件以便上传，每个文件都将命令映射到 MCP 连接器的工具（$B/api/skills/<name>/chatgpt.zip）。

登录

API 需要一个令牌。如果某个命令失败并提示 not signed in，请运行 slipdock auth —— 它会打印一个短代码和一个 URL，用户在他们已登录的浏览器中批准即可，几秒钟后你将获得一个令牌。将代码和 URL 告诉用户；不要要求他们手动生成令牌，除非他们更愿意这样做（slipdock auth <token> 仍然接受手动令牌，SLIPDOCK_TOKEN 也仍然有效）。

slipdock whoami 显示当前用户。用户无法访问的看板不会被列出；forbidden 错误表示他们能看到某些内容但无法修改。有两种拒绝原因是指出 令牌 的问题，而不是用户的问题，这意味着你持有的令牌被故意限制了范围，而不是出了任何问题 —— 请这样说明，而不是重试：

• this API token is read-only —— 该令牌只被授予了读取权限。请请求一个读/写令牌。
• this API token's scope doesn't allow it —— 该令牌被限制在特定的看板上，或者它不是管理员令牌而你尝试管理服务器。

还有两种拒绝也是不可撤销的。报告它们并说明用户可以做什么：

• card_limit_reached（HTTP 402）—— 看板所有者的账户已用尽了允许的 项目 数量。一个项目是指一张卡片、一个 wiki 页面或一个上传的文件：三者都计入同一个数字，所以将其作为页面写回并不能绕过限制。更改标题也无济于事；它将以同样的方式永久失败。建议归档一些已完成的内容。slipdock whoami --json 和 slipdock guide 都会显示剩余配额，因此你可以在开始批量操作之前检查，而不是在途中才发现已达到上限。
• board_limit_reached（HTTP 402）—— 他们拥有的看板数量已达到此服务器允许的单人上限。子看板（子卡片）不计入此限制。建议归档一个看板，或联系管理员。
• storage_limit_reached（HTTP 402）—— 他们上传的文件已用尽分配的存储空间。只有删除附件才能释放空间；归档文件所在的卡片并不能释放。
• trial_expired（HTTP 402）—— 免费试用期已结束。任何看板上都无法添加新内容，无论多么微小。已有的所有内容仍然可读可编辑。你无法做什么：告诉用户需要订阅，然后停止操作。 上述四种情况影响的不仅仅是创建操作：从归档中恢复、move --board 到别人的看板上（该卡片及其所有子项会计入他们的配额）、导入，以及 welcome 操作。
• No account here uses that address… —— 此服务器不会为你要共享对象创建账户。需要管理员邀请他们。

在只有被共享者才能看到对方的服务器上，你期望找到却找不到的人很可能是因为尚未与他人共享任何内容。他们没有被删除，在共享某些内容之前，为其分配卡片将不会起作用。

一张卡片只能分配给能打开它的人。如果分配时出现 user … not found，无论该用户是否有账户，都意味着同样的问题 —— 先在浏览器中与他们共享看板（通过看板的“共享”设置），或者请用户本人操作。

工作流

1. 首先找到看板及其结构：slipdock boards，然后 slipdock board <board> 或 slipdock columns <board> 和 slipdock tags <board>。看板和列接受 ID 或大小写不敏感的名称，因此 slipdock board "product launch" 也能工作。 每个看板还有一个 代码 —— 其短名称：唯一、URL 安全、最多 10 个字符，取自看板名称并且可编辑（“QVM V1 Remediation” 的代码是 qvm-v1-rem）。它显示在 slipdock boards 的 CODE 列和 --json 输出的 code 字段中，并且 <board> 在任何地方都接受它：slipdock board qvm-v1-rem、slipdock add qvm-v1-rem "..."。相对于名称，请优先使用代码 —— 它明确无误且能在重命名后保持不变 —— 并且在向用户提及看板时使用代码。slipdock new-board <name> [--code C] 可以显式设置代码；如果省略，会根据名称生成一个。 看板还有一个 快捷键 —— 一个或两个字符，用于在 Web 应用中跳转到该看板（按 b，然后按快捷键）。它显示在 slipdock boards 的 KEY 列和 --json 输出的 shortcut 字段中，通过 new-board 或 set-board 的 --shortcut K 选项设置。它不能用作命令行中寻址看板的方式；代码才是。
2. 先读后写。 slipdock card <id> 显示所有内容：描述、标记、标签、检查清单项 ID、评论。
3. 当你需要解析输出时，使用 --json（获取 ID、过滤、计数）。纯文本输出用于向用户展示。
4. 优先使用 archive 而非 delete。 删除是永久性的。在删除用户未明确要求删除的内容之前，请先询问。 整个 看板 也可以归档（slipdock archive-board <board>），这与归档卡片不同，而且离你的职责更远：它会将看板从用户的索引、看板切换器和快速添加中移除。除非用户明确按名称请求该看板，否则切勿归档或重新排序看板。
5. 在操作进行时告知用户。 耗时较长的任务应在每个里程碑处使用 slipdock comment <id> ... —— 配合 slipdock edit <id> --percent N 更新进度 —— 而不是在最后才一次性汇报。一张正在进行的卡片如果没有比移动操作更新的评论，对于关注者来说会显得像被遗弃了。
6. 将 ID 报告给用户（#42），以便他们能在 UI 中找到卡片。 在评论或描述中的 @handle（某人邮箱中的 @ 之前的部分）会向该人发送邮件 —— 仅在卡片确实需要他们注意时使用，切勿用作签名。
7. “入门指南”看板是教程，不是工作任务。 服务器会为新账户创建一个看板：其卡片是给人看的说明（“将此卡片拖至‘完成’列”），因此永远不要操作、完成或整理它们。如果这里只有这一个看板，请说明情况并询问用户实际想要做什么。slipdock welcome 会为那些已归档但仍想重新体验教程的用户创建一个新的。

命令

读取：

slipdock guide                          # 服务器给代理的说明（GET /api/guide）
slipdock boards [--archived|--all] [--sort manual|name|active|newest|oldest|cards]
slipdock board <board>                  # 完整看板：每一列和每一张卡片
slipdock cards <board> [--column C] [--tag T] [--priority P] [--flag F] [--search Q] [--open|--done] [--archived]
                     [--due overdue|today|week|month|has|none] [--deps blocked|requests|blocks]
                     [--limit L]
slipdock column <board> <column>        # 某一列的所有卡片
slipdock card <id>                      # 单张卡片的完整详情
slipdock tags <board>                   # 看板上的所有标签
slipdock whoami [--json]                # 当前用户和账户详情
slipdock sprints <board>                # 冲刺及其进度
slipdock sprint <board> <sprint>
slipdock activity <board> [--limit L]   # 最近的活动日志
slipdock timeline <board>               # 甘特图概览
slipdock fields <board>                 # 自定义字段定义
slipdock search <board> <query>         # 全文搜索
slipdock filter <board> <filter>        # 应用保存的过滤器

写入：

slipdock add <board> "<card-title>" [--column C] [--desc "…"] [--priority P] [--tag T...]
                               [--flag urgent|important|question|review|blocked] [--assignee @user]
                               [--due YYYY-MM-DD] [--parent <id>] [--page]
slipdock edit <id> [--title "…"] [--desc "…"] [--priority P] [--tag T...] [--flag F] [--assignee @user]
                   [--due YYYY-MM-DD] [--percent N] [--column C] [--parent <id>]
slipdock move <id> <column|board>      # 移动到另一列或另一个看板
slipdock complete <id>                  # 标记为完成
slipdock reopen <id>                    # 重新打开已完成或已归档的卡片
slipdock flag <id> <flag|remove>        # 添加或移除标记
slipdock tag <id> <tag|remove>          # 添加或移除标签
slipdock assign <id> <@user|remove>     # 分配或取消分配用户
slipdock due <id> <date|remove>         # 设置或移除截止日期
slipdock percent <id> <0-100|remove>    # 设置进度百分比
slipdock comment <id> "<text>"          # 添加评论
slipdock checklist <id>                 # 查看检查清单
slipdock check <id> <item-id>           # 勾选检查项
slipdock uncheck <id> <item-id>         # 取消勾选检查项
slipdock archive <id>                   # 归档卡片
slipdock restore <id>                   # 恢复已归档的卡片
slipdock delete <id>                    # 永久删除（需要 --confirm 或交互确认）
slipdock link <id> <url>               # 添加链接
slipdock watchers <id> [add|remove] [@user...]  # 管理关注者
slipdock subscribe <id>                 # 订阅此卡片的通知

看板管理：

slipdock new-board <name> [--code C] [--shortcut K] [--desc "…"]
slipdock set-board <board> [--name N] [--code C] [--shortcut K] [--desc "…"]
slipdock archive-board <board>
slipdock delete-board <board> [--confirm CODE]
slipdock new-column <board> <name>
slipdock new-tag <board> <name> [--color HEX]
slipdock new-list <board> <name>      # 别名：new-column

Wiki 和文档：

slipdock pages <board> [--tree]        # 列出 wiki 页面
slipdock page <board> <path>           # 读取页面
slipdock page new <board> <path> [--title "…"] [--summary "…"] [--tag T...]
slipdock page edit <board> <path> [--section S] [--title "…"] [--summary "…"] [--tag T...]
slipdock page mv <board> <path> <new-path>
slipdock page rm <board> <path>        # 删除页面（可恢复）
slipdock page history <board> <path>
slipdock page diff <board> <path> [--rev R] [--against A]
slipdock page revert <board> <path> [--rev R]

文件和附件：

slipdock attach <id> <file>            # 附加文件
slipdock detach <id> <attachment-id>   # 移除附件
slipdock download <id> <attachment-id> # 下载附件

自动化和工具：

slipdock automations <board>           # 列出自动化规则
slipdock automation <board> <id>       # 查看单个自动化规则
slipdock new-automation <board> [--name N] [--trigger T] [--action A...]
slipdock set-automation <board> <id> [--name N] [--trigger T] [--action A...]
slipdock delete-automation <board> <id> [--confirm]
slipdock tools <board>                 # 列出已安装的工具（runner）
slipdock tools install <board> <tool>  # 安装工具
slipdock tools remove <board> <tool>   # 移除工具
slipdock tools show <tool>             # 显示工具详情
slipdock tools file <tool>             # 获取工具的文件
slipdock tools skill <tool>            # 获取工具的 SKILL.md
slipdock tools download <tool>         # 下载工具的 zip 文件
slipdock guide                         # 查看服务器指南

实用工具：

slipdock url <address>                 # 设置服务器地址
slipdock auth [<token>]                # 登录或手动设置令牌
slipdock whoami                        # 显示当前用户
slipdock welcome                       # 重新创建入门指南看板
slipdock skills chatgpt                # 导出技能为 ChatGPT zip 文件
slipdock --help                        # 完整帮助

获取帮助

• 在运行任何命令之前查看全面的帮助：slipdock --help
• 服务器指南始终是最新的：运行 slipdock guide 或直接访问 GET /api/guide
• 有关 Slipdock 应用本身的更多信息，请访问 app.slipdock.us