slack-cli

Slack CLI

使用 Slack CLI 创建、运行和管理 Slack 应用，包括直接调用 Web API 方法，以及在终端中搜索 Slack 开发者文档。

如需进行初始设置（创建沙盒、根据模板搭建项目），请改用 slack:create-slack-app skill。

---

第 1 步：检测 Slack CLI

在运行任何其他命令之前，先解析公开版 Slack CLI 的路径。我们将解析出的值称为 SLACK_CMD——请在下文各处替换为该值。请按 1a → 1b → 1c 的顺序尝试；不要跳过步骤。

1a. 标准安装路径（首选——无需验证）

官方安装脚本会将二进制文件放在固定的用户级路径中。如果文件存在，请直接使用：只有安装脚本会写入该路径。

• macOS / Linux：~/.slack/bin/slack
• Windows：%USERPROFILE%\AppData\Local\slack-cli\bin\slack.exe（或将 %USERPROFILE%\.slack-cli\bin\slack.exe 作为备用路径）

POSIX shell：

[ -x "$HOME/.slack/bin/slack" ] && echo "$HOME/.slack/bin/slack"

PowerShell：

$p = "$env:USERPROFILE\AppData\Local\slack-cli\bin\slack.exe"
if (Test-Path $p) { $p } elseif (Test-Path "$env:USERPROFILE\.slack-cli\bin\slack.exe") { "$env:USERPROFILE\.slack-cli\bin\slack.exe" }

如果返回了路径，将 SLACK_CMD 设置为该绝对路径，然后继续第 2 步。不要再运行 _fingerprint。

1b. PATH 中的 slack（使用指纹验证）

如果 1a 未找到任何内容，请尝试使用 PATH 中的 slack：

slack _fingerprint 2>/dev/null

如果输出为 d41d8cd98f00b204e9800998ecf8427e，则设置 SLACK_CMD=slack 并继续。

1c. 询问是否存在别名，或进行安装

如果 1b 失败或返回其他值，请使用 AskUserQuestion 询问开发者：

• “你系统上的 slack 命令似乎不是公开版 Slack CLI。你是否将它安装为其他名称或别名？”

• 选项：“是，别名为……”（让他们提供别名），“否，我需要安装”

• 如果他们提供了别名，请使用 <alias> _fingerprint 2>/dev/null 验证，并设置 SLACK_CMD=<alias>。

• 如果他们需要安装，请运行：

  curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash
  

  然后重新运行步骤 1a——安装脚本会将文件写入 ~/.slack/bin/slack。

**常见错误：**不要使用 which slack 查找二进制文件——which 会解析任何 shell 别名，从而违背步骤 1a 的目的。在 Windows 的 Git Bash 中，请使用 POSIX 探测形式，而不是 PowerShell。

---

第 2 步：通过帮助信息发现命令

**在当前会话中使用某个命令之前，务必先运行 SLACK_CMD <command> --help。**不要猜测标志参数——帮助输出才是准确信息来源。

• SLACK_CMD help — 列出所有可用的命令组
• SLACK_CMD <command> --help — 显示子命令、标志参数和用法示例

确定 --app 和 --team 的值

命令需要 --app 或 --team 时：

• App ID：在项目目录中运行 SLACK_CMD app list，查看已安装的应用及其 ID。
• Team ID：运行 SLACK_CMD auth list，查看已验证身份的工作区及其 team ID。

---

第 3 步：搜索文档（slack docs search）

直接在终端中搜索 Slack 开发者文档。

SLACK_CMD docs search "<query>" --output=text --limit=5

使用 --output=text 获取简洁、便于在终端中阅读的结果。在已经运行 CLI 命令时，可用此功能：

• 在实现 Slack 功能前进行查询
• 验证 API 行为或所需的 scope
• 查找 Block Kit 元素、事件类型或方法参数

---

第 4 步：调用 Web API 方法（slack api）

直接调用任意 Slack Web API 方法。运行 SLACK_CMD api --help 查看完整详情和示例。

参数以位置参数 key=value 的形式传递（而非 --key=value 标志）：

SLACK_CMD api chat.postMessage channel=C0123456789 text="Hello from the CLI"

重要区别：--team、--token、--json 和 --data 是元标志（以 -- 为前缀）。API 方法参数使用位置参数 key=value 语法，不带连字符。

**参考：**完整方法列表见 https://docs.slack.dev/reference/methods.md。

---

第 5 步：身份验证（slack auth）

何时运行此流程

Slack 身份验证是按团队进行的，而不是一个简单的全局开关。满足以下任一情况时，都应运行下方的无缝登录流程：

• 开发者尚未通过任何团队的身份验证。
• 开发者想要添加新团队 / 工作区 / 沙盒，即使 SLACK_CMD auth list 已显示其他团队也一样。
• 开发者要求登录、切换团队或重新进行身份验证。

SLACK_CMD auth list 显示其他团队并不意味着可以跳过登录——那些是不同的团队。询问开发者想要使用哪个团队，然后运行此流程。

下方流程适用于各种类型的工作区。/slackauthticket 可在开发者所属的任何工作区中使用，无论是开发者沙盒、Free Team 还是生产工作区，因此不需要针对沙盒的特殊登录方式。应优先选择哪个目标，由 slack:create-slack-app 技能决定（步骤 3：选择安装应用的位置）。

检查现有身份验证（可选）

SLACK_CMD auth list

使用此命令向开发者显示已完成身份验证的团队，或确认登录成功。开发者要求登录新团队时，不能因为列表非空就认为“身份验证已完成”。

运行无缝登录流程

Agent 会端到端执行整个流程——无需单独打开终端窗口，也无需在浏览器中确认。

SLACK_CMD login --no-prompt 会让 CLI 输出一次性票据并立即退出，而不是等待标准输入。开发者发送 /slackauthticket 斜杠命令时，Slack 会在工作区模态框中显示挑战码——无需经过浏览器步骤。Agent 会将挑战码提交回 CLI 以完成登录。

1. 开始登录并获取票据

SLACK_CMD login --no-prompt

CLI 会输出 /slackauthticket <ticket> 斜杠命令，然后退出。记下票据——步骤 4 会用到。输出示例：

📋 Run the following slash command from any Slack channel in the workspace
   you'd like to authenticate

   /slackauthticket eyJ0eXAiOiJKV1QiLCJh…

? Slack will then show you a challenge code. Submit it via:
   slack login --ticket <ticket> --challenge <code>

2. 将斜杠命令交给开发者

显示完整的 /slackauthticket … 命令，并请开发者将其粘贴到想要进行身份验证的 Slack 工作区消息框中，然后发送。Slack 会返回一个包含短挑战码的模态框（例如 JDt1IK7X）。

3. 获取挑战码

使用 AskUserQuestion 询问开发者 Slack 模态框中显示的挑战码。等待对方回答——不要猜测或使用默认值。

4. 完成登录

SLACK_CMD login --ticket <ticket> --challenge <code>

成功后，CLI 会返回团队名称和 ID。使用 SLACK_CMD auth list 验证，并向开发者报告该团队。

故障排除：票据只能使用一次，且有时效限制。如果步骤 4 因票据无效或过期、或挑战码错误而失败，请从步骤 1 重新开始，使用新的 SLACK_CMD login --no-prompt——不要重试同一张票据。

在单条命令中使用 --team <team_id> 可指定目标工作区，而无需全局切换。

危险信号——停止

如果你发现自己在想以下任何一种说法，说明你即将退回到旧的错误流程：

找理由	实际情况
“auth list 已显示团队，所以不需要登录。”	身份验证是按团队进行的。开发者要添加一个_新_团队——请执行整个流程。
“slack login 需要在浏览器中确认，所以我无法代为操作。”	使用 --no-prompt 时并非如此。挑战码会显示在 Slack 模态框中，而不是浏览器中。两次 slack login 调用都由 Agent 自行执行。
“我应该让开发者在单独的终端中运行 slack login。”	绝对不要。步骤 5 从头到尾都应由 Agent 完成。

这些情况都意味着：自行运行 SLACK_CMD login --no-prompt，并按照上方编号的四个步骤操作。

---

步骤 6：在本地运行应用（slack run）

运行 SLACK_CMD run --help 查看所有可用标志。

确定应用或团队目标

在项目目录中运行 SLACK_CMD app list，检查已安装的应用：

• 如果存在应用：在运行命令中使用 --app=<app_id>。
• 如果没有列出应用：改用 --team=<team_id>（通过 SLACK_CMD auth list 获取团队 ID）。

在后台启动开发服务器

将此命令作为后台进程运行，以便开发者继续工作：

如果找到了应用 ID：

cd <project-dir> && SLACK_CMD run --org-workspace-grant=all --app=<app_id>

如果没有应用 — 使用团队 ID：

cd <project-dir> && SLACK_CMD run --org-workspace-grant=all --team=<team_id>

告知开发者应用正在后台运行。他们可以询问：

• “开发服务器的状态如何？”——查看运行状态
• “显示 slack run 的输出”——查看活动日志
• “停止开发服务器”——终止进程

---

第 7 步：管理清单

运行 SLACK_CMD manifest --help，查看子命令（validate、info）以及 --source local|remote 标志。

在部署前或应用配置似乎有问题时，运行 SLACK_CMD manifest validate。

---

第 8 步：其他命令

对于其他命令组（例如 trigger、datastore、env、collaborator、external-auth、deploy），运行 SLACK_CMD <command> --help，以查看子命令和标志。运行 SLACK_CMD help，查看所有可用的命令组。

---

注意事项

• SLACK_CMD 是占位符 — 请始终替换为第 1 步中确定的实际命令名称。
• 在构造当前会话中尚未使用过的命令之前，始终运行 --help。
• 交互式命令（例如，不带 --trigger-def 的 slack trigger create）无法在后台运行。请告知开发者在新终端窗口中运行这些命令。slack login 不属于此类 — 请按照第 5 步中的 --no-prompt / --ticket / --challenge 流程直接运行。
• slack run 在本地运行，用于开发。slack deploy 会部署到 Slack 托管的基础设施，除非 .slack/hooks.json 定义了 deploy hook，此时它会改为运行该 hook（参见 slack:deploy-slack-app 技能）。这是两种不同的操作，请勿混淆。