pp-slack

Original：🇺🇸 English
Translated

Slack workspace CLI for the terminal. Send messages, search channels and DMs, list conversations, get user/bot/emoji info, analyze channel health, find stale threads, and sync the workspace locally for fast offline queries. Two auth surfaces coexist: SLACK_BOT_TOKEN (xoxb-, for workspace-wide read + post) and SLACK_USER_TOKEN (xoxp-, for user-scoped actions like DM history or search). Use when the user asks to send a Slack message, search Slack, check channel activity, summarize a digest, find who's on a team, find stale threads, analyze channel health, list users / emoji / reminders / pinned items, or wants offline-capable Slack queries.

4installs
Sourcemvanhorn/printing-press-library
Added on

NPX Install

npx skill4agent add mvanhorn/printing-press-library pp-slack

Tags

Translated version includes tags in frontmatter
slack-cliterminal-toolsslack-workspaceoffline-queriesslack-analytics

SKILL.md Content

View Translation Comparison →

Slack - Printing Press CLI

Prerequisites: Install the 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:
  1. Install via the Printing Press installer:
    bash
    npx -y @mvanhorn/printing-press install slack --cli-only
  2. Verify: 
    slack-pp-cli --version
  3. 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
If 
--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.

When to Use This 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.

Two Auth Surfaces

Slack has two parallel token types and this CLI supports both:
TokenScopesWhen to use
SLACK_BOT_TOKEN
(xoxb-)		workspace-scoped bot permissionsDefault for post-message, read-channel, list-users, etc.
SLACK_USER_TOKEN
(xoxp-)		user-scopedDM 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.

Argument Parsing

Parse 
$ARGUMENTS
:
  1. Empty, 
    help
    , or 
    --help
     -> show 
    slack-pp-cli --help
  2. Starts with 
    install
     -> ends with 
    mcp
    -> MCP installation; otherwise -> CLI installation
  3. Anything else -> Direct Use (map to the best command and run it)

MCP Server Installation

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.

Direct Use

  1. Check installed: 
    which slack-pp-cli
    . If missing, offer CLI installation.
  2. Discover commands: 
    slack-pp-cli --help
    ; drill into 
    slack-pp-cli <cmd> --help
    .
  3. Match the user query to the best command (see Notable Commands below).
  4. Execute with 
    --agent
    for structured output:
    bash
    slack-pp-cli <command> [args] --agent
  5. 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.

Notable Commands

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

Agent Mode

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

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.

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.

Exit Codes

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