Readable layout
---
name: slack-cli
description: Invoke the `slack-cli` binary to read and act on a Slack workspace from the command line — list channels, read/search conversation history and threads, fetch unread messages, search users, manage user groups, post messages, add reactions, mark channels read, and manage saved items. Use whenever a task needs Slack data or actions, such as "what are the unread messages in #incidents", "search Slack for the deploy thread", "who is @alice", "post a message to #general", "list channels matching X", "react with :rocket: to that message", "what did the team say about Y", or "show replies in this thread". slack-cli is the no-daemon CLI alternative to the slack-mcp-server; it reads a shared on-disk cache so it is cheap to call repeatedly. Output is JSON by default, so results pipe cleanly into `jq`.
---
# Slack CLI
Invoke the `slack-cli` binary (install via `brew install paymog/tap/slack-cli`).
Source of truth is [`paymog/slack-cli`](https://github.com/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`.
## Output
Every successful command prints **valid JSON by default**. List/table commands
(channels, messages, users, saved items, user groups) emit arrays of objects.
Structured mutations expose their result fields directly; `conversations add`
returns `channel`, optional `thread_ts`, and `ts`. Legacy plain-text statuses are
wrapped as `{"message":"…"}`. Pipe directly into `jq`:
```sh
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
```
Field values from CSV-backed tables are strings; use jq's `tonumber` for numeric
comparisons. `--raw` prints the underlying CSV/text or legacy human-readable
command output verbatim.
## Auth (required before any command)
Provide exactly one credential set via env (the CLI also reads stored profiles):
```sh
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)
```
Capability notes:
- **Legacy search** (`conversations search`, `users_search` real-time) and **unreads**
work best with `xoxp` or browser (`xoxc`/`xoxd`). Bots can search public channels
with **`conversations context-search`**, `search:read.public`, and an action token.
- **Saved items** (`saved …`) require browser tokens (`xoxc`/`xoxd`) only.
- `--govslack` / `SLACK_MCP_GOVSLACK=true` routes to slack-gov.com.
### Stored profiles (alternative to env vars)
```sh
slack-cli auth login [name] # prompts for mode + token(s); validates before saving
slack-cli auth list # * marks default
slack-cli auth default
slack-cli --profile # use a profile for one command
slack-cli auth status # show resolved source + mode
slack-cli auth logout [-f]
```
Precedence: explicit `--xoxp/--xoxc/...` flags or `SLACK_MCP_*` env → `--profile `
→ default profile. Explicit tokens + `--profile` is rejected as ambiguous.
`SLACK_CLI_PROFILE` sets the profile via env.
## 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:
```sh
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.
## Channels / IDs
`` accepts an ID (`C123…`), a name (`#general`), or a DM (`@username`).
## Read commands
```sh
# 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 [--limit 1d|1w|30d|] [--cursor C] [--activity]
slack-cli conversations replies # whole thread by default; --limit 1d| narrows it
# Pagination: read the Cursor field of the last element, then pass --limit='' --cursor .
# 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 [--limit 10]
# User groups
slack-cli usergroups list [--include-users] [--include-disabled]
slack-cli usergroups me [--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 [-o path] # Fxxxxxxxxxx, max 5MB
```
## 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.
```sh
SLACK_MCP_ADD_MESSAGE_TOOL=true slack-cli conversations add -t "hello" [--thread-ts 123.456] [--content-type text/mrkdwn|text/markdown|text/plain]
SLACK_MCP_ADD_MESSAGE_TOOL=true slack-cli conversations add --text-file /tmp/reply.txt --content-type text/mrkdwn
SLACK_MCP_ADD_MESSAGE_TOOL=true slack-cli conversations add --blocks ''
SLACK_MCP_ADD_MESSAGE_TOOL=true slack-cli conversations edit --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 [--ts 123.456]
SLACK_MCP_REACTION_TOOL=true slack-cli reactions add --emoji rocket
SLACK_MCP_REACTION_TOOL=true slack-cli reactions remove --emoji rocket
slack-cli usergroups create --name "Eng" [--handle eng] [--description ...] [--channels C1,C2]
slack-cli usergroups update [--name ...] [--handle ...] [--channels ...]
slack-cli usergroups users-update --users U1,U2,U3
slack-cli saved update [--mark completed] [--date-due ]
slack-cli saved clear-completed
```
## Critical: multi-line / formatted posts
**Default for conversational replies: native Slack message text, read from a file.**
Write the body to a UTF-8 file with your file-writing tool, using actual line
breaks. Then pass only its path to the shell:
```sh
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` preserves newlines, backticks, dollar signs, and literal `\n`
examples without shell interpolation. It cannot be combined with `--text`.
- `text/mrkdwn` posts ordinary Slack-formatted text without Block Kit. Use
`*bold*`, `_italic_`, ``, and backticks for code;
use bullets rather than Markdown tables or `#` headings.
- The default `text/markdown` converts GitHub-style Markdown into Block Kit;
it is not native Slack text. `text/plain` disables formatting.
- Reserve `--blocks` for interactive or deliberately structured UI. Newlines,
bullets, and code alone do not require blocks.
- Inline `-t` is fine for simple one-liners. Do not embed multiline bodies in
shell commands: `-t "first\nsecond"` sends literal `\n`, not a line break.
- Keep answers concise; split long answers at paragraph boundaries. Native
text avoids section-block collapse, but Slack can still collapse long messages.
### Delete a botched post
`slack-cli` has **no delete command**. Use Slack's Web API with the resolved xoxp token:
```sh
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"}'
```
Only works for messages your token is allowed to delete (your own user messages with `xoxp`, or bot messages with the bot token).
### Verify before walking away
After posting multi-line content, re-read the thread and check for:
- bullets stuck on one line
- missing newlines after headers/code fences
- truncated or shell-error fragments (`command not found`, half-eaten backticks)
If any of those appear, fix the source file, delete via `chat.delete`, and
repost with `--text-file … --content-type text/mrkdwn`.
## Recipes
```sh
# 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
```
## 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.)
- **legacy search / saved / unreads return nothing or error** — bots lack legacy
search and edge APIs. Use `context-search` for bot public-channel search with an
action token; use `xoxp` or browser tokens for legacy search/unreads. `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.
- **multi-line post looks mangled (literal `\n` / backticks executed)** —
the shell received escaped or interpolated content. Write actual newlines to
a file with your file tool, then use `--text-file … --content-type text/mrkdwn`.
Delete the bad message with `chat.delete`, then repost.
- **need to delete a message** — no CLI subcommand; call `https://slack.com/api/chat.delete`
with the xoxp token from `slack-cli auth token` (see recipe above).
