slack-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Slack CLI

Invoke the

slack-cli

binary (install via

brew install paymog/tap/slack-cli

). Source of truth is

paymog/slack-cli

. It wraps the

korotovsky/slack-mcp-server

engine for behavior, but prints JSON by default (the underlying MCP server emits CSV) so output pipes cleanly into

jq

调用

slack-cli

二进制文件（可通过

brew install paymog/tap/slack-cli

安装）。权威源码为

paymog/slack-cli

。它基于

korotovsky/slack-mcp-server

引擎实现功能，但默认输出JSON格式（底层MCP服务器输出CSV），因此输出可顺畅通过管道传递给

jq

。

Output

输出

Every command prints JSON by default. List/table commands (channels, messages, users, saved items, user groups) emit a JSON array of objects, so pipe straight into

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'

Field values are strings (CSV carries no types) — use jq's

tonumber

for numeric comparisons. Write/status commands print a short text or JSON line.

--raw

prints the underlying CSV/text verbatim.

所有命令默认输出JSON格式。列表/表格类命令（channels、messages、users、saved items、user groups）会输出对象组成的JSON数组，因此可直接通过管道传递给

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'

字段值均为字符串（CSV不携带类型信息）——如需数值比较，可使用jq的

tonumber

方法。写入/状态类命令会输出简短文本或单行JSON。

--raw

参数会直接输出底层CSV/文本内容。

Auth (required before any command)

身份验证（执行任何命令前必须完成）

Provide exactly one credential set via env (the CLI also reads stored profiles):

export SLACK_MCP_XOXP_TOKEN=xoxp-...        # user OAuth — full features (recommended)

通过环境变量提供一组凭证即可（CLI也支持读取已存储的配置文件）：

export SLACK_MCP_XOXP_TOKEN=xoxp-...        # 用户OAuth——功能完整（推荐使用）

or

或

export SLACK_MCP_XOXB_TOKEN=xoxb-... # bot token — invited channels only, no search

export SLACK_MCP_XOXB_TOKEN=xoxb-... # 机器人令牌——仅可访问受邀频道，无搜索权限

or

或

export SLACK_MCP_XOXC_TOKEN=xoxc-... # browser session token + cookie below export SLACK_MCP_XOXD_TOKEN=xoxd-... # browser cookie d (stealth mode)


Capability notes:
- **Search** (`conversations search`, `users_search` real-time) and **unreads**
  work best with `xoxp` or browser (`xoxc`/`xoxd`). **Bot tokens cannot search.**
- **Saved items** (`saved …`) require browser tokens (`xoxc`/`xoxd`) only.
- `--govslack` / `SLACK_MCP_GOVSLACK=true` routes to slack-gov.com.

export SLACK_MCP_XOXC_TOKEN=xoxc-... # 浏览器会话令牌 + 下方的Cookie export SLACK_MCP_XOXD_TOKEN=xoxd-... # 浏览器Cookie d（隐身模式）


功能说明：
- **搜索**（`conversations search`、实时`users_search`）和**未读消息**功能在使用`xoxp`或浏览器令牌（`xoxc`/`xoxd`）时效果最佳。**机器人令牌无法进行搜索**。
- **已保存项目**（`saved …`）仅支持浏览器令牌（`xoxc`/`xoxd`）。
- `--govslack` / `SLACK_MCP_GOVSLACK=true` 参数会将请求路由至slack-gov.com。

Stored profiles (alternative to env vars)

已存储配置文件（替代环境变量）

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]

Precedence: explicit

--xoxp/--xoxc/...

flags or

SLACK_MCP_*

env →

--profile <name>

→ default profile. Explicit tokens +

--profile

is rejected as ambiguous.

SLACK_CLI_PROFILE

sets the profile via env.

slack-cli auth login [name]        # 提示选择模式并输入令牌；验证通过后保存
slack-cli auth list                # * 标记默认配置文件
slack-cli auth default <name>
slack-cli --profile <name> <cmd>   # 为单次命令指定配置文件
slack-cli auth status              # 显示当前生效的凭证来源及模式
slack-cli auth logout <name> [-f]

优先级：显式

--xoxp/--xoxc/...

参数或

SLACK_MCP_*

环境变量 →

--profile <name>

参数 → 默认配置文件。同时指定显式令牌和

--profile

参数会被判定为冲突而拒绝执行。

SLACK_CLI_PROFILE

环境变量可用于设置默认配置文件。

Cache (do this first for name lookups)

缓存（名称查询前需先执行此操作）

#channel-name

@username

lookups and

channels list

need a warm cache. The cache is on disk and shared across every invocation, so refresh once:

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

Read commands auto-load the on-disk cache (and fetch on first run). Use

--no-cache

to skip it — then only raw IDs (

C…

U…

D…

) resolve, not names.

#channel-name

@username

名称查询及

channels list

命令需要预热缓存。缓存存储在磁盘上，所有调用共享，因此只需刷新一次：

slack-cli cache refresh            # 获取用户和频道数据，写入磁盘缓存

读取类命令会自动加载磁盘缓存（首次运行时会自动获取数据）。使用

--no-cache

参数可跳过缓存——此时仅能解析原始ID（

C…

、

U…

、

D…

），无法解析名称。

Channels / IDs

频道 / ID

<channel>

accepts an ID (

C123…

), a name (

#general

), or a DM (

@username

<channel>

参数支持ID（

C123…

）、名称（

#general

）或私信（

@username

）。

Read commands

读取类命令

undefined

undefined

Channels (JSON array; fields: ID,Name,Topic,Purpose,MemberCount,Cursor)

频道（JSON数组；字段：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>

Pagination: read the Cursor field of the last element, then pass --limit='' --cursor <value>.

分页：读取最后一条数据的Cursor字段值，然后传递--limit='' --cursor <value>参数。

Search (needs xoxp or browser token; not bot)

搜索（需要xoxp或浏览器令牌；机器人令牌不支持）

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.

将完整的Slack消息URL作为查询参数，会仅返回该条消息。

Unreads, prioritized DMs > partner > internal (best with xoxp/browser)

未读消息，优先级：私信 > 合作方频道 > 内部频道（使用xoxp/浏览器令牌效果最佳）

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)

用户（JSON数组，包含用于快速发消息的DMChannelID字段）

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

附件（通过ID下载文件；始终可用，无需设置环境变量）。

slack-cli attachments get <file_id> [-o path] # Fxxxxxxxxxx, max 5MB

undefined

slack-cli attachments get <file_id> [-o path] # 文件ID格式为Fxxxxxxxxxx，最大支持5MB

undefined

Write / sensitive commands (opt-in)

写入/敏感操作命令（需手动启用）

Disabled by default — each needs an env var set in the same invocation, so an agent never posts or mutates by accident. The allowlist forms (

C123,D456

, or

!C123

for all-except) restrict which channels are writable.

SLACK_MCP_ADD_MESSAGE_TOOL=true  slack-cli conversations add <channel> -t "hello" [--thread-ts 123.456] [--content-type text/markdown|text/plain]
SLACK_MCP_ADD_MESSAGE_TOOL=true  slack-cli conversations add <channel> --blocks '<Block Kit JSON array>'
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

默认禁用——每个命令需要在同一调用中设置对应的环境变量，避免Agent意外发送消息或修改数据。允许列表格式为

C123,D456

（指定可操作频道）或

!C123

（排除指定频道，其余均可操作），用于限制可写入的频道。

SLACK_MCP_ADD_MESSAGE_TOOL=true  slack-cli conversations add <channel> -t "hello" [--thread-ts 123.456] [--content-type text/markdown|text/plain]
SLACK_MCP_ADD_MESSAGE_TOOL=true  slack-cli conversations add <channel> --blocks '<Block Kit JSON array>'
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

Recipes

使用示例

undefined

undefined

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_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"

slack-cli users search alice # 记录DMChannelID，例如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

获取频道最近一天的消息JSON，用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

下载图片（或任何二进制）附件到文件。-o参数会写入解码后的字节数据，并将标准输出保留为小型元数据JSON——下载图片/二进制文件时建议使用该参数，避免多MB的base64数据填满终端。

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:

不使用-o参数时，字节数据会以base64编码的形式包含在.content字段中——可通过以下命令解码：

slack-cli attachments get F0123ABCD | jq -r .content | base64 --decode > avatar.png

undefined

slack-cli attachments get F0123ABCD | jq -r .content | base64 --decode > avatar.png

undefined

Common issues

常见问题

no Slack credentials
— set

SLACK_MCP_XOXP_TOKEN

(or xoxb, or xoxc+xoxd) or run

slack-cli auth login

users cache is not ready
/ empty
channels list
/
#name not found
— run

slack-cli cache refresh

first, or pass IDs with

--no-cache

conversations_add_message tool is disabled
/ reactions / mark disabled — set the matching env var (

SLACK_MCP_ADD_MESSAGE_TOOL

SLACK_MCP_REACTION_TOOL

SLACK_MCP_MARK_TOOL

) in the same command. (

attachments get

needs no env var.)

search / saved / unreads return nothing or error — bot tokens (
```
xoxb
```
) can't search and lack edge APIs; use
```
xoxp
```
or browser tokens.
```
saved
```
needs browser tokens.
slow first run — the initial
```
cache refresh
```
(or first read with no cache) crawls the whole workspace; subsequent calls read the cached file.

no Slack credentials
—— 设置

SLACK_MCP_XOXP_TOKEN

（或xoxb、xoxc+xoxd），或运行

slack-cli auth login

。

users cache is not ready
/
channels list
为空 /
#name not found
—— 先运行

slack-cli cache refresh

，或使用

--no-cache

参数并传递ID。

conversations_add_message tool is disabled
/ 表情反应/标记功能禁用 —— 在同一命令中设置对应的环境变量（
```
SLACK_MCP_ADD_MESSAGE_TOOL
```
、
```
SLACK_MCP_REACTION_TOOL
```
、
```
SLACK_MCP_MARK_TOOL
```
）。（
```
attachments get
```
无需设置环境变量。）
搜索/已保存项目/未读消息无返回或报错 —— 机器人令牌（
```
xoxb
```
）无法搜索且缺少边缘API权限；请使用
```
xoxp
```
或浏览器令牌。
```
saved
```
功能仅支持浏览器令牌。
首次运行缓慢 —— 初始的
```
cache refresh
```
（或无缓存时的首次读取）会遍历整个工作区；后续调用会读取缓存文件。