pp-slack

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Slack - Printing Press CLI

Prerequisites: Install the CLI

前置条件：安装CLI

This skill drives the

slack-pp-cli

binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

Install via the Printing Press installer:

bash

npx -y @mvanhorn/printing-press install slack --cli-only

Verify:
```
slack-pp-cli --version
```
Ensure
```
$GOPATH/bin
```
(or
```
$HOME/go/bin
```
) is on
```
$PATH
```
.

If the

npx

install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.23+):

bash

go install github.com/mvanhorn/printing-press-library/library/productivity/slack/cmd/slack-pp-cli@latest

--version

reports "command not found" after install, the install step did not put the binary on

$PATH

. Do not proceed with skill commands until verification succeeds.

本技能基于

slack-pp-cli

二进制文件运行。在调用本技能的任何命令之前，必须确认CLI已安装。如果未安装，请先执行以下步骤：

通过Printing Press安装器安装：

bash

npx -y @mvanhorn/printing-press install slack --cli-only

验证安装：执行
```
slack-pp-cli --version
```
确保
```
$GOPATH/bin
```
（或
```
$HOME/go/bin
```
）已添加到
```
$PATH
```
环境变量中。

如果

npx

安装失败（如无Node环境、离线等情况），可以改用Go直接安装（要求Go 1.23及以上版本）：

bash

go install github.com/mvanhorn/printing-press-library/library/productivity/slack/cmd/slack-pp-cli@latest

如果安装后执行

--version

提示“command not found”，说明安装步骤未将二进制文件添加到

$PATH

中。请在验证成功前不要执行技能命令。

When to Use This CLI

何时使用此CLI

Reach for this when the user wants:

send a Slack message to a channel or DM
search Slack across channels, DMs, and threads (live or synced)
list users, channels, usergroups, custom emoji, pinned items, or reminders
understand channel health (quiet channels, activity trends, response times, digest)
find stale or unanswered threads across the workspace
pull an activity summary for a user or channel
export channel history to JSONL for archival or migration
discover the funniest messages in public channels (local-sync-powered novelty query)

Skip it when the user wants to create Slack apps, workflows, or manage admin-only team settings beyond

team

access logs. Those surfaces are better served by the Slack web admin.

当用户需要以下操作时，可使用本工具：

向频道或私信发送Slack消息
跨频道、私信和线程搜索Slack内容（支持在线或本地同步数据）
列出用户、频道、用户组、自定义表情、置顶内容或提醒
了解频道健康状况（沉寂频道、活动趋势、响应时间、活动摘要）
在工作区中查找闲置或未回复的线程
拉取用户或频道的活动摘要
将频道历史导出为JSONL格式用于归档或迁移
发现公开频道中最有趣的消息（基于本地同步数据的趣味查询）

当用户需要创建Slack应用、工作流，或管理

team

访问日志之外的管理员专属团队设置时，请不要使用本工具。这些场景更适合通过Slack网页管理员界面操作。

Two Auth Surfaces

两种认证方式

Slack has two parallel token types and this CLI supports both:

Token	Scopes	When to use
`SLACK_BOT_TOKEN` (xoxb-)	workspace-scoped bot permissions	Default for post-message, read-channel, list-users, etc.
`SLACK_USER_TOKEN` (xoxp-)	user-scoped	DM history, search on behalf of a user, stars, reminders

Set whichever the workspace permits. If both are set, user-token wins for user-scoped endpoints and bot-token otherwise. Get a token at

https://api.slack.com/apps

-> your app -> OAuth & Permissions.

Slack支持两种并行的令牌类型，本CLI均兼容：

令牌类型	权限范围	使用场景
`SLACK_BOT_TOKEN` （xoxb-前缀）	工作区范围的机器人权限	默认用于发送消息、读取频道、列出用户等操作
`SLACK_USER_TOKEN` （xoxp-前缀）	用户范围的权限	查看私信历史、代表用户搜索、星标内容、提醒等操作

设置工作区允许的令牌类型即可。如果同时设置了两种令牌，用户令牌将优先用于用户范围的端点，机器人令牌则用于其他场景。可通过

https://api.slack.com/apps

-> 你的应用 -> OAuth & Permissions获取令牌。

Argument Parsing

参数解析

Parse

$ARGUMENTS

Empty,
help
, or
--help
-> show
```
slack-pp-cli --help
```
Starts with
install
-> ends with
```
mcp
```
-> MCP installation; otherwise -> CLI installation
Anything else -> Direct Use (map to the best command and run it)

解析

$ARGUMENTS

规则：

为空、
help
或
--help
-> 显示
```
slack-pp-cli --help
```
内容
以
install
开头 -> 若结尾为
```
mcp
```
-> 执行MCP安装；否则 -> 执行CLI安装
其他情况 -> 直接使用（匹配最佳命令并执行）

MCP Server Installation

MCP服务器安装

The CLI also ships an MCP server at

slack-pp-mcp

. Install and register:

bash

go install github.com/mvanhorn/printing-press-library/library/productivity/slack/cmd/slack-pp-mcp@latest
claude mcp add -e SLACK_BOT_TOKEN=xoxb-... slack-pp-mcp -- slack-pp-mcp

Ask the user for the actual token value before running.

该CLI还附带了一个MCP服务器

slack-pp-mcp

。安装并注册的步骤如下：

bash

go install github.com/mvanhorn/printing-press-library/library/productivity/slack/cmd/slack-pp-mcp@latest
claude mcp add -e SLACK_BOT_TOKEN=xoxb-... slack-pp-mcp -- slack-pp-mcp

执行前请向用户索要实际的令牌值。

Direct Use

直接使用

Check installed:
```
which slack-pp-cli
```
. If missing, offer CLI installation.

Discover commands:

slack-pp-cli --help

; drill into

slack-pp-cli <cmd> --help

Match the user query to the best command (see Notable Commands below).

Execute with

--agent

for structured output:

bash

slack-pp-cli <command> [args] --agent

The

--agent

flag sets

--json --compact --no-input --no-color --yes

Source routing (local vs live) is controlled by

--data-source

auto

(default) prefers local-synced data with live fallback;

live

always hits the API;

local

runs fully offline against the SQLite snapshot. Run

slack-pp-cli sync

first to populate the local store for analytics queries.

检查是否已安装：执行
```
which slack-pp-cli
```
。如果未安装，提供CLI安装选项。
查看命令列表：执行
```
slack-pp-cli --help
```
；如需深入了解，执行
```
slack-pp-cli <cmd> --help
```
。
将用户查询匹配到最佳命令（见下方常用命令）。
添加
```
--agent
```
参数执行以获取结构化输出：
bash
```
slack-pp-cli <command> [args] --agent
```

--agent

参数等价于设置

--json --compact --no-input --no-color --yes

。

数据源路由（本地 vs 在线）由

--data-source

控制：

auto

（默认）优先使用本地同步数据， fallback到在线API；

live

始终调用在线API；

local

完全基于SQLite快照离线运行。执行分析类查询前，请先运行

slack-pp-cli sync

以填充本地存储。

Notable Commands

常用命令

Command	What it does
`conversations`	List channels and DMs in the workspace
`users`	List all users in the workspace
`search <query>`	Full-text search across synced messages (or live API with `--data-source live` )
`digest`	Daily/weekly activity digest from locally synced data
`health`	Channel health report (activity, engagement, stagnation)
`quiet`	Find dead or low-activity channels
`response-times`	Average first-response time in threads
`threads-stale`	Unanswered or stale threads
`activity <user-or-channel>`	Activity summary across channels from local sync
`trends`	Week-over-week channel activity trends
`sync`	Populate the local SQLite store for offline analytics
`emoji` / `reminders` / `pins` / `stars`	Workspace directory queries
`team`	Access logs (requires admin token)

Run any command with

--help

for full flag documentation.

命令	功能
`conversations`	列出工作区中的频道和私信
`users`	列出工作区中的所有用户
`search <query>`	对同步的消息进行全文搜索（添加 `--data-source live` 则使用在线API）
`digest`	基于本地同步数据生成每日/每周活动摘要
`health`	生成频道健康报告（活动量、参与度、沉寂情况）
`quiet`	查找沉寂或低活跃度的频道
`response-times`	统计线程中的平均首次响应时间
`threads-stale`	查找未回复或闲置的线程
`activity <user-or-channel>`	基于本地同步数据生成用户或频道的跨频道活动摘要
`trends`	生成频道活动的周环比趋势
`sync`	填充本地SQLite存储以支持离线分析
`emoji` / `reminders` / `pins` / `stars`	工作区目录查询
`team`	获取访问日志（需要管理员令牌）

执行任何命令时添加

--help

可查看完整的参数文档。

Agent Mode

Agent模式

Add

--agent

to any command. Expands to:

--json --compact --no-input --no-color --yes

Pipeable — JSON on stdout, errors on stderr
Filterable —
```
--select
```
keeps a subset of fields, with dotted-path support (see below)
Previewable —
```
--dry-run
```
shows the request without sending
Cacheable — GET responses cached for 5 minutes, bypass with
```
--no-cache
```
Non-interactive — never prompts, every input is a flag

在任何命令后添加

--agent

参数，等价于设置：

--json --compact --no-input --no-color --yes

。

可管道传输 — 标准输出为JSON格式，错误信息输出到标准错误流
可过滤 —
```
--select
```
参数保留指定字段子集，支持点路径（见下文）
可预览 —
```
--dry-run
```
参数显示请求内容但不实际发送
可缓存 — GET请求的响应会缓存5分钟，添加
```
--no-cache
```
可绕过缓存
非交互式 — 从不弹出提示，所有输入均通过参数传递

Filtering output

输出过滤

--select

accepts dotted paths to descend into nested responses; arrays traverse element-wise:

bash

slack-pp-cli <command> --agent --select id,name
slack-pp-cli <command> --agent --select items.id,items.owner.name

Use this to narrow huge payloads to the fields you actually need — critical for deeply nested API responses.

--select

参数接受点路径以遍历嵌套响应；数组会逐个元素遍历：

bash

slack-pp-cli <command> --agent --select id,name
slack-pp-cli <command> --agent --select items.id,items.owner.name

使用此参数可将庞大的响应 payload 缩小到实际需要的字段 — 这在处理深度嵌套的API响应时至关重要。

Response envelope

响应信封

Data-layer commands wrap output in

{"meta": {...}, "results": <data>}

. Parse

.results

for data and

.meta.source

to know whether it's

live

or local. The

N results (live)

summary is printed to stderr only when stdout is a TTY; piped/agent consumers see pure JSON on stdout.

数据层命令会将输出包裹在

{"meta": {...}, "results": <data>}

结构中。可解析

.results

获取数据，通过

.meta.source

判断数据来源是

live

（在线）还是本地。当标准输出为TTY时，

N results (live)

摘要会打印到标准错误流；管道或Agent消费者只会在标准输出看到纯JSON。

Exit Codes

退出码

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Resource not found (channel, user, message)
4	Authentication required (token missing or invalid)
5	API error (Slack upstream, including `not_in_channel` , `channel_not_found` )
7	Rate limited (Slack 429; CLI honors `Retry-After` )

代码	含义
0	执行成功
2	使用错误（参数不正确）
3	资源未找到（频道、用户、消息）
4	需要认证（令牌缺失或无效）
5	API错误（Slack上游错误，包括 `not_in_channel` 、 `channel_not_found` 等）
7	请求受限（Slack 429错误；CLI会遵循 `Retry-After` 头信息）