slack-cli

Slack CLI

调用 slack-cli 二进制文件（通过 brew install paymog/tap/slack-cli 安装）。 权威来源是 paymog/slack-cli。它在行为上 封装了 korotovsky/slack-mcp-server 引擎，但默认输出 JSON（底层 MCP 服务会输出 CSV），因此可以直接将输出传入 jq。

输出

每条成功执行的命令默认都会输出有效 JSON。列表／表格命令 （channels、messages、users、saved items、user groups）会输出对象数组。 结构化变更会直接公开结果字段；conversations add 会返回 channel、可选的 thread_ts 和 ts。 旧版纯文本状态会包装为 {"message":"…"}。可直接将输出传入 jq：

slack-cli channels list | jq -r '.[].Name'
slack-cli conversations history '#general' --limit 1d | jq -r '.[].Text'
slack-cli users search alice | jq -r '.[].DMChannelID'
slack-cli conversations add C123 --thread-ts 123.456 -t "hello" | jq -r .ts

CSV 表格中的字段值均为字符串；进行数值比较时，请使用 jq 的 tonumber。 --raw 会原样输出底层 CSV／文本或旧版命令的人类可读输出。

身份验证（执行任何命令前均为必需）

通过环境变量提供且仅提供一组凭据（CLI 也会读取已存储的配置）：

export SLACK_MCP_XOXP_TOKEN=xoxp-...        # user OAuth — full features (recommended)
# or
export SLACK_MCP_XOXB_TOKEN=xoxb-...        # bot — context-search needs an action token
# or
export SLACK_MCP_XOXC_TOKEN=xoxc-...        # browser session token  + cookie below
export SLACK_MCP_XOXD_TOKEN=xoxd-...        # browser cookie d (stealth mode)

功能说明：

• 旧版搜索（conversations search、实时 users_search）和未读消息 使用 xoxp 或浏览器令牌（xoxc／xoxd）效果最佳。机器人可使用 conversations context-search、search:read.public 和操作令牌搜索公开频道。
• 已保存项目（saved …）仅需要浏览器令牌（xoxc／xoxd）。
• --govslack／SLACK_MCP_GOVSLACK=true 会将请求路由到 slack-gov.com。

已存储的配置（环境变量的替代方式）

slack-cli auth login [name]        # prompts for mode + token(s); validates before saving
slack-cli auth list                # * marks default
slack-cli auth default <name>
slack-cli --profile <name> <cmd>   # use a profile for one command
slack-cli auth status              # show resolved source + mode
slack-cli auth logout <name> [-f]

优先级：显式的 --xoxp/--xoxc/... 标志或 SLACK_MCP_* 环境变量 → --profile <name> → 默认配置。显式令牌与 --profile 同时使用会因存在歧义而被拒绝。 SLACK_CLI_PROFILE 可通过环境变量设置配置。

缓存（按名称查找前先执行此操作）

#channel-name／@username 查找和 channels list 需要预热缓存。 缓存存储在磁盘上，并由每次调用共享，因此只需刷新一次：

slack-cli cache refresh            # fetch users + channels, write cache to disk

读取命令会自动加载磁盘上的缓存（并在首次运行时获取缓存）。使用 --no-cache 可跳过缓存——此时只能解析原始 ID（C…、U…、D…），无法解析名称。

频道／ID

<channel> 可以是 ID（C123…）、名称（#general）或私信（@username）。

读取命令

# Channels (JSON array; fields: ID,Name,Topic,Purpose,MemberCount,Cursor)
slack-cli channels list [--types public_channel,private_channel,im,mpim] [--query foo] [--query-targets name,topic,purpose] [--sort popularity] [--limit 100] [--cursor C]
slack-cli channels me                      # channels you belong to

# Conversation history & threads
slack-cli conversations history <channel> [--limit 1d|1w|30d|<count>] [--cursor C] [--activity]
slack-cli conversations replies <channel> <thread_ts>   # whole thread by default; --limit 1d|<count> narrows it
# Pagination: read the Cursor field of the last element, then pass --limit='' --cursor <value>.
# A Cursor on a default replies call means the thread was cut short (size cap or timeout).
# Unlisted Slack apps: 1 req/min and 15 msgs/page on history/replies. The CLI waits
# Retry-After and shares the slot across processes. Set SLACK_MCP_UNLISTED_HISTORY=1
# to force that cap. Default --timeout is 2m. Do not hammer these in a loop.

# Legacy search (needs xoxp or browser token; not bot)
slack-cli conversations search [query] \
  [--in-channel #general] [--in-dm @user] [--with @user] [--from @user] \
  [--before YYYY-MM-DD] [--after YYYY-MM-DD] [--on YYYY-MM-DD] [--during July] \
  [--threads-only] [--limit 20] [--cursor C]
# A full Slack message URL as the query returns just that message.

# Real-time Search (public channels by default; bots need an action token)
SLACK_MCP_ACTION_TOKEN_FILE=/run/slack/action-token slack-cli conversations context-search "aws contract" \
  [--channel-types public_channel] [--content-types messages] [--limit 20] \
  [--cursor C] [--sort score|timestamp] [--after YYYY-MM-DD] [--before YYYY-MM-DD] \
  [--include-context-messages]
# --action-token overrides the file; file contents are read fresh and trimmed.
# User tokens need RTS scopes but no action token. Limit is 1–20; dates are UTC.
# Treat action tokens as secrets; prefer the file over command-line arguments.
# Invalid/expired tokens or missing scopes: unavailable for this turn; do not retry.
# Cursor is on the last row. ContextMessages is JSON encoded inside the table field.
# Non-message content types (files,channels,users) are preserved in Data as JSON.

# Unreads, prioritized DMs > partner > internal (best with xoxp/browser)
slack-cli conversations unreads [--types all|dm|group_dm|partner|internal] [--mentions-only] [--max-channels 50] [--max-messages-per-channel 10] [--include-muted]

# Users (JSON array incl. DMChannelID for quick messaging)
slack-cli users search <query> [--limit 10]

# User groups
slack-cli usergroups list [--include-users] [--include-disabled]
slack-cli usergroups me <list|join|leave> [--usergroup-id S123]

# Saved items (browser tokens only)
slack-cli saved list [--filter saved|completed|archived] [--limit 50]

# Attachments (download a file by ID; always available, no env var needed).
slack-cli attachments get <file_id> [-o path]   # Fxxxxxxxxxx, max 5MB

写入／敏感命令（选择启用）

默认禁用——每条命令都需要在同一次调用中设置环境变量，以免 Agent 意外发布内容或执行变更。允许列表格式（C123,D456，或用 !C123 表示全部允许，但排除指定项）可限制可写入的频道。

SLACK_MCP_ADD_MESSAGE_TOOL=true  slack-cli conversations add <channel> -t "hello" [--thread-ts 123.456] [--content-type text/mrkdwn|text/markdown|text/plain]
SLACK_MCP_ADD_MESSAGE_TOOL=true  slack-cli conversations add <channel> --text-file /tmp/reply.txt --content-type text/mrkdwn
SLACK_MCP_ADD_MESSAGE_TOOL=true  slack-cli conversations add <channel> --blocks '<Block Kit JSON array>'
SLACK_MCP_ADD_MESSAGE_TOOL=true  slack-cli conversations edit <channel> <ts> --text-file /tmp/fix.txt --content-type text/mrkdwn   # replaces a message you posted; same flags as add, no --thread-ts
SLACK_MCP_MARK_TOOL=true         slack-cli conversations mark <channel> [--ts 123.456]
SLACK_MCP_REACTION_TOOL=true     slack-cli reactions add <channel> <timestamp> --emoji rocket
SLACK_MCP_REACTION_TOOL=true     slack-cli reactions remove <channel> <timestamp> --emoji rocket
slack-cli usergroups create --name "Eng" [--handle eng] [--description ...] [--channels C1,C2]
slack-cli usergroups update <usergroup_id> [--name ...] [--handle ...] [--channels ...]
slack-cli usergroups users-update <usergroup_id> --users U1,U2,U3
slack-cli saved update <item_id> <ts> [--mark completed] [--date-due <unix>]
slack-cli saved clear-completed

重要：多行／格式化消息

对话式回复的默认方式：使用原生 Slack 消息文本，并从文件读取。

使用文件写入工具将正文写入 UTF-8 文件，并使用实际换行符。然后只将文件路径传给 shell：

SLACK_MCP_ADD_MESSAGE_TOOL=C123 slack-cli conversations add C123 \
  --thread-ts 123.456 --text-file /tmp/reply.txt --content-type text/mrkdwn

• --text-file 会保留换行符、反引号、美元符号和字面量 \n 示例，且不会触发 shell 插值。它不能与 --text 一起使用。
• text/mrkdwn 会发布普通的 Slack 格式文本，不使用 Block Kit。使用 *bold*、_italic_、<https://example.com|label> 和反引号表示代码； 请使用项目符号，不要使用 Markdown 表格或 # 标题。
• 默认的 text/markdown 会将 GitHub 风格的 Markdown 转换为 Block Kit； 它不是原生 Slack 文本。text/plain 会禁用格式化。
• 仅在需要交互式或刻意构建的 UI 时使用 --blocks。仅包含换行符、 项目符号和代码时不需要使用 blocks。
• 对于简单的单行内容，可以使用内联 -t。不要在 shell 命令中嵌入多行正文： -t "first\nsecond" 会发送字面量 \n，而不是换行符。
• 答案应简洁；长答案请按段落拆分。原生文本可避免区块折叠，但 Slack 仍可能折叠较长的消息。

删除误发的消息

slack-cli 没有删除命令。请使用已解析的 xoxp 令牌调用 Slack 的 Web API：

TOKEN=$(slack-cli auth token | jq -r .SLACK_MCP_XOXP_TOKEN)
# chat.delete needs channel + message ts (e.g. 1783603079.714919 from replies)
curl -s -X POST https://slack.com/api/chat.delete \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"channel":"C061WRT6XM5","ts":"1783603079.714919"}'

仅当令牌有权删除相应消息时才有效（使用 xoxp 时可删除你自己的用户消息，使用 bot 令牌时可删除机器人消息）。

离开前先确认

发布多行内容后，请重新阅读消息串并检查以下问题：

• 项目符号被挤在同一行
• 标题／代码围栏后缺少换行
• 内容被截断或出现 Shell 错误片段（command not found、反引号被截掉）

如果出现上述任何问题，请修复源文件，通过 chat.delete 删除消息，然后使用 --text-file … --content-type text/mrkdwn 重新发布。

操作示例

# Triage unread DMs and mentions
slack-cli cache refresh
slack-cli conversations unreads --types dm
slack-cli conversations unreads --mentions-only

# Find a thread, then read its replies
slack-cli conversations search "deploy rollback" --in-channel #incidents --after 2024-06-01
slack-cli conversations replies C0123456789 1718000000.123456

# Who is someone, then DM them (needs SLACK_MCP_ADD_MESSAGE_TOOL)
slack-cli users search alice            # note DMChannelID, e.g. D0123
SLACK_MCP_ADD_MESSAGE_TOOL=D0123 slack-cli conversations add D0123 -t "ping"

# Last day of a channel as JSON, extract message text with jq
slack-cli conversations history #general --limit 1d | jq -r '.[].Text'

# Download an image (or any binary) attachment to a file. -o writes the decoded
# bytes and keeps stdout to a small metadata JSON — use it for images/binaries so
# a multi-MB base64 blob doesn't flood the terminal.
slack-cli attachments get F0123ABCD -o avatar.png
# Without -o the bytes come back inline, base64-encoded under .content — decode with:
slack-cli attachments get F0123ABCD | jq -r .content | base64 --decode > avatar.png

常见问题

• no Slack credentials — 设置 SLACK_MCP_XOXP_TOKEN（或 xoxb，或 xoxc+xoxd）， 或运行 slack-cli auth login。
• users cache is not ready / channels list 为空 / 找不到 #name — 先运行 slack-cli cache refresh，或使用 --no-cache 传入 ID。
• conversations_add_message tool is disabled / reactions / mark 已禁用 — 在同一条命令中设置对应的环境变量（SLACK_MCP_ADD_MESSAGE_TOOL、SLACK_MCP_REACTION_TOOL、 SLACK_MCP_MARK_TOOL）。（attachments get 无需设置环境变量。）
• 旧版搜索 / 已保存内容 / 未读内容没有结果或报错 — 机器人缺少旧版 搜索和边缘 API。使用 context-search 搭配操作令牌搜索机器人可访问的公开频道；旧版搜索／未读内容请使用 xoxp 或浏览器令牌。saved 需要浏览器令牌。
• 首次运行较慢 — 初次执行 cache refresh（或缓存为空时首次读取）会遍历整个工作区；后续调用会读取缓存文件。
• 多行消息显示混乱（出现字面量 \n／反引号被执行） — Shell 收到的是转义或插值后的内容。请使用文件工具将实际换行写入文件，然后使用 --text-file … --content-type text/mrkdwn。通过 chat.delete 删除错误消息，然后重新发布。
• 需要删除消息 — 没有对应的 CLI 子命令；请使用 slack-cli auth token 获取 xoxp 令牌，并调用 https://slack.com/api/chat.delete （参见上方操作示例）。