
slackbuzz-cli
SlackBuzz CLI integration — send messages, DMs, search, reactions, and status from Claude Code
- version
- 1.0.0
- GitHub stars
- 7
Install
/plugin install slackbuzz-cli@slackbuzz-cliRun it inside Claude Code after adding the marketplace with /plugin marketplace add triptechtravel/slackbuzz-cli.
Contents
Discovered from sourceSkills 1
SlackBuzz CLI (slackbuzz)
Use the slackbuzz CLI instead of raw Slack API calls. It handles authentication (bot + user tokens), user/channel resolution, DM channel opening, and cross-tool integrations automatically.
When to Use
- User asks to send a Slack message or DM
- User wants to check Slack activity, inbox, or threads
- User needs to search Slack messages or files
- User wants to react to messages, set status, or manage saved items
- User mentions Slack channels, users, or message timestamps
Authentication
slackbuzz app create # Create a Slack app, then click Allow in the browser — tokens stored automatically
slackbuzz app create --web # Same, without an App Configuration Token (needs the user's own terminal)
slackbuzz app update # Push the latest scope set to an existing app + re-auth
slackbuzz auth login # Log in with bot and/or user token (manual paste)
slackbuzz auth status # Check auth status and capabilities
Agent shells usually have no TTY, so token prompts fail. Have the user copy
the token and run slackbuzz app create --clipboard (or auth login --clipboard) — or ask them to run the interactive command in their own
terminal. Never ask the user to paste a token into the chat.
app update flow — use when slackbuzz gains new scope requirements
(e.g. a future command needs a scope the existing manifest doesn't grant).
Pushes the canonical manifest to your existing app via apps.manifest.update,
then reinstalls via the browser OAuth flow (click Allow; new tokens are
stored automatically — falls back to pasting them). The manifest is auto-derived from method
usage (make manifest-gen runs in CI), so the scope list never drifts from
what commands actually need.
Two token types are required. The CLI automatically selects the right token for each command — you do not need to specify which to use.
- Bot token (
xoxb-): Used automatically for reading channels, listing users, reactions, and system notifications - User token (
xoxp-): Used automatically for sending messages (as the user), search, DMs, saved items, status, and profile
Messages always post as the authenticated user by default. Only use --as-bot if you specifically want a message to come from the bot app rather than the user.
Messaging
Send Messages
# Send to a channel (shortcut — same as 'message send')
slackbuzz send '#general' "Hello team!"
# Send to a channel (full form)
slackbuzz message send '#general' "Hello team!"
# Send a DM (auto-opens DM channel)
slackbuzz send @alice "Hey, quick question"
slackbuzz send U02P3QC5H24 "Direct message by user ID"
# Send as bot (default uses user token if available)
slackbuzz send '#general' "Bot message" --as-bot
DM auto-detection: If the target looks like a user (@name, U... ID, or bare name), the CLI automatically opens a DM conversation via conversations.open.
Read Messages
# Channel history
slackbuzz message list #general
slackbuzz message list #general --limit 50
# Thread replies
slackbuzz message list #general --thread 1706000000.000000
# DM history
slackbuzz message list @alice
Edit & Delete
slackbuzz message edit #general 1706000000.000000 "Updated text"
slackbuzz message delete #general 1706000000.000000 --confirm # --confirm is required when not interactive
A message the bot posted (e.g. a self-DM, which goes through the bot) is
deleted with --as-bot, targeting yourself: slackbuzz message delete @me <ts> --confirm --as-bot
(me/@me is always the signed-in user).
Images and files
Attach files to a message with --file (repeatable). The text and every file
arrive as one message, the way the Slack client posts them. Don't post the
text and then upload images as thread replies.
# A post with screenshots under it
slackbuzz send '#released' "*Website release*\n- Deals show on place pages" \
--file deal.png --file closure.png --file tip.png
# Files alone (or with a caption): also one message
slackbuzz file upload a.png b.png '#design' --comment "Before and after"
--comment and the message text go through the same Markdown→mrkdwn and
@mention handling as send (--raw turns conversion off). With --file the
text is optional. --file can't be combined with --blocks (Slack posts a
file's message as plain mrkdwn). send --file --json returns
{"channel", "timestamp", "files": [{"id", "name", …}]}: the timestamp to
edit, delete or reply to, and file IDs.
Deleting a message leaves its files in Slack; remove them too:
slackbuzz message delete '#released' 1706000000.000000 --confirm
slackbuzz file delete F0CK25W3ABH F0CKKDV2K8R --confirm
Screenshots for a channel read best at phone width (about 390px wide).
Search
# Search messages (requires user token)
slackbuzz message search "deploy production"
# Search files
slackbuzz file search "architecture diagram"
Inbox & Activity
# Mentions (default)
slackbuzz activity
# DMs
slackbuzz activity --dms
# Threads you're in
slackbuzz activity --threads
slackbuzz threads # Shortcut
# Everything combined
slackbuzz activity --all --since 1d
# Filter by channel or sender
slackbuzz activity --channel #engineering --from @alice
# DM conversations list
slackbuzz dm list
Activity detects ClickUp task IDs and GitHub PR/issue URLs in messages and shows actionable hints.
Reactions
# Add reaction
slackbuzz react #general 1706000000.000000 :eyes:
slackbuzz react #general 1706000000.000000 thumbsup
# Remove reaction
slackbuzz react remove #general 1706000000.000000 :eyes:
Status
# View current status
slackbuzz status
# Set status with emoji and optional expiration
slackbuzz status set "In a meeting" :calendar:
slackbuzz status set "Reviewing PRs" :eyes: --until 2h
# Clear status
slackbuzz status clear
Saved Items
# List saved messages
slackbuzz later list
# Save/unsave a message
slackbuzz later add #general 1706000000.000000
slackbuzz later remove #general 1706000000.000000
Notifications
# Release announcement
slackbuzz notify #releases --release v1.0.0
# Task status update
slackbuzz notify #updates --task CU-abc123 --status "deployed"
# Custom message
slackbuzz notify #general --message "Maintenance window starting"
Thread Linking
# Link a Slack thread to a ClickUp task
slackbuzz thread link #general 1706000000.000000 --task CU-abc123
Channels & Users
# List channels
slackbuzz channel list
# Channel info
slackbuzz channel info #general
# List users
slackbuzz user list
# User profile
slackbuzz user info @alice
Token Defaults
The CLI automatically selects the correct token for each command. You do not need to think about bot vs user mode — just run the command.
| Command | Token | Rationale |
|---|---|---|
message send, edit, delete | User | Posts as the authenticated user |
message list | Bot | Reads channel history |
channel list, channel info | Bot | Reads channel metadata |
user list, user info | Bot | Reads user profiles |
react, react remove | Bot | Reactions via bot |
notify | Bot | System/automated notifications |
thread link | Bot | Generates permalinks |
activity, threads | User | Slack search API (user-only) |
dm list | User | Slack search API (user-only) |
message search, file search | User | Slack search API (user-only) |
later list, add, remove | User | Stars API (user-only) |
status, status set, clear | User | Profile API (user-only) |
Override: Pass --as-bot on message send, edit, or delete to post as the bot app instead of the user. Only do this when explicitly requested.
Missing permissions: If a command fails due to a missing token or scope, the error message will indicate what's needed. Run slackbuzz auth status to check available capabilities.
Common Flags
| Flag | Description |
|---|---|
--json | Output as JSON |
--jq <expr> | Filter JSON with jq expression |
--template <tmpl> | Format with Go template |
--as-bot | Post as the bot app instead of the user (send/edit/delete only) |
--since <duration> | Time filter (2h, 1d, 7d, 2w, or YYYY-MM-DD) |
--limit <n> | Max results |
@Mentioning Users in Messages
@name mentions in message bodies are resolved automatically. The CLI looks up usernames and display names (case-insensitive) and converts them to Slack's <@USERID> format before posting. Resolved mentions are confirmed on stderr.
# Mentions are resolved automatically — these will ping the users
slackbuzz message send '#channel' '@michelle @herman please review this'
# → stderr: Mentioning @michelle
# → stderr: Mentioning @herman
# Also works in notify --message
slackbuzz notify #general --message '@alice maintenance window starting'
First-name resolution
When a user's Slack username is dotted (herman.gorbatovskii) or their display name has multiple words (Herman Gorbatovskii), the CLI also indexes the first name as a shorthand. Writing @herman will resolve to that user as long as the first name is unambiguous (only one user has that first name). If multiple users share a first name, use the full username or display name instead.
# These all resolve to the same user:
slackbuzz message send '#dev' '@herman.gorbatovskii check this' # full username
slackbuzz message send '#dev' '@herman gorbatovskii check this' # full display name
slackbuzz message send '#dev' '@herman, check this' # first-name shorthand
Unrecognized names are left as-is (no error). Use slackbuzz user list to discover available usernames if a mention isn't resolving.
Shell Escaping
The CLI automatically strips common shell escape artifacts from message text before sending. For example, zsh history expansion can turn exclamation marks into backslash-escaped versions when passed through double-quoted strings. The CLI detects and cleans these so the message arrives correctly in Slack.
Fuzzy resolution
Channel and user names match in three tiers:
- Exact (case-insensitive).
@michelle→ @michelle. - Substring.
@mich→ @michelle,#stand→ #stand-up. Multiple matches resolve to the shortest (most-specific). - Fuzzy (edit distance, channel-only — never used for users to
avoid mis-DMing the wrong person).
#stnd-p→ #stand-up.
Failing exact match shows "Did you mean: …?" suggestions in the error.
Recent context
slackbuzz dm with no subcommand shows the most recently active DM
targets (newest first) and the commands to read/send them. Each
message list, message send, notify invocation records its target
into ~/.config/slack/recent.json so future no-arg defaults flow.
Key Behaviors
- Automatic token selection: The CLI picks the right token (bot or user) for each command. No need to specify — just run the command. Use
--as-botonly when explicitly asked to post as the bot. - Self-DM via bot: When sending a DM to yourself, the CLI automatically switches to the bot token so you receive a notification. The bot opens its own DM channel with you.
- DM auto-detection:
@user,U...IDs, and bare names auto-resolve to DM channels (for the channel/target argument) - @mentions in message body: Auto-resolved from
@nameto Slack's<@USERID>format before posting - First-name shorthand:
@hermanresolves toherman.gorbatovskiiorHerman Gorbatovskiiwhen unambiguous - Shell unescape: Common shell artifacts (backslash-escaped punctuation) are cleaned before sending
- Case-insensitive resolution: User lookup matches display names and usernames regardless of case
- Permission feedback: Missing tokens or scopes produce clear error messages. Use
slackbuzz auth statusto check capabilities. - Deeplinks: In a terminal, timestamps and "Open in Slack" are clickable links. Piped or captured output (scripts, agents) is plain text, so there is nothing to strip
- DM channel IDs:
message list D…reads a DM by its ID (through the user token)
Formatting
Messages auto-convert standard Markdown to Slack mrkdwn:
**bold**→*bold*# Header→*Header*(bold on its own line)[text](url)→<url|text>
# Auto-conversion happens by default
slackbuzz send '#releases' "## 🚀 v5.4.0\n- **New feature**: offline images"
# Use --blocks for Block Kit rendering (richer formatting, auto-splits long messages)
slackbuzz send '#releases' --blocks "## Release Notes\n- *Feature*: offline images"
# Use --raw to disable auto-conversion
slackbuzz send '#dev' --raw "**this stays as double asterisks**"
Formatting hints are shown on stderr when Markdown syntax is detected and converted.
Agent Mode
When calling slackbuzz from an AI agent or automation, set SLACKBUZZ_AGENT=1 to enable agent-friendly defaults:
SLACKBUZZ_AGENT=1 slackbuzz send '#stand-up' "Daily update from CI"
Agent mode changes:
- Bot token for sending: Uses the bot token by default to avoid user-token scope gaps (e.g. missing
channels:read). Messages will appear from the bot app. OmitSLACKBUZZ_AGENT=1to post as yourself. - No interactive prompts: Errors immediately if message text is missing instead of waiting for stdin
- Structured errors: Outputs JSON error objects to stderr with
error,type, andsuggestionfields
You can also run slackbuzz doctor to check that both tokens are valid and have the required scopes.
Diagnostics
# Check token health and scope coverage
slackbuzz doctor
# Check auth status
slackbuzz auth status
When commands fail with missing_scope
slackbuzz surfaces Slack's missing-scope responses with the specific scopes needed and a one-line fix:
Error: chat.postMessage: missing_scope (needed scopes: chat:write)
Run slackbuzz app update to push the latest scope manifest to your existing
Slack app and re-auth. The manifest is auto-derived from the methods slackbuzz
calls, so the scope list is always exactly right — app update is the
canonical fix for any missing_scope error.
Internal architecture (for context)
The CLI is generated from Slack's published OpenAPI 2.0 spec (committed to
api/specs/slack_web.json):
make api-genregenerates the typed Slack client (174 methods).make manifest-genAST-walkspkg/cmd/forslackapi.<Method>(...)calls and writes the corresponding scope union topkg/cmd/app/manifest.go.make verify-genruns both and fails CI if generated artifacts have drifted — guarantees the manifest never lies about what the CLI actually needs.
Most surface area is generated; the hand-written pieces are:
internal/slackapi/client.go— transport (Do, error envelope, sentinel errors)internal/slackapi/blocks.go— Block Kit composition helpersinternal/slackapi/files.go— the external upload flow (UploadFiles: every file uploaded, then shared in onefiles.completeUploadExternal, so they post as one message)cmd/gen-api/patches.go— narrow spec-quirk fixups (inline-vs-ref drift, nullable tuples)
See Architecture for the complete design.
Sponsors
Details
- Marketplace
- triptechtravel/slackbuzz-cli
- Category
- Productivity