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

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.

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)
# or
export SLACK_MCP_XOXB_TOKEN=xoxb-...        # bot token — invited channels only, no search
# 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.

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.

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.

Channels / IDs

<channel>

accepts an ID (

C123…

), a name (

#general

), or a DM (

@username

Read commands

# 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>
# Pagination: read the Cursor field of the last element, then pass --limit='' --cursor <value>.

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

# 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

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

Recipes

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

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.

slack-cli

NPX Install

Tags

SKILL.md Content