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-cli

Run it inside Claude Code after adding the marketplace with /plugin marketplace add triptechtravel/slackbuzz-cli.

Contents

Discovered from source

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

CommandTokenRationale
message send, edit, deleteUserPosts as the authenticated user
message listBotReads channel history
channel list, channel infoBotReads channel metadata
user list, user infoBotReads user profiles
react, react removeBotReactions via bot
notifyBotSystem/automated notifications
thread linkBotGenerates permalinks
activity, threadsUserSlack search API (user-only)
dm listUserSlack search API (user-only)
message search, file searchUserSlack search API (user-only)
later list, add, removeUserStars API (user-only)
status, status set, clearUserProfile 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

FlagDescription
--jsonOutput as JSON
--jq <expr>Filter JSON with jq expression
--template <tmpl>Format with Go template
--as-botPost 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:

  1. Exact (case-insensitive). @michelle → @michelle.
  2. Substring. @mich → @michelle, #stand → #stand-up. Multiple matches resolve to the shortest (most-specific).
  3. 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-bot only 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 @name to Slack's <@USERID> format before posting
  • First-name shorthand: @herman resolves to herman.gorbatovskii or Herman Gorbatovskii when 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 status to 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. Omit SLACKBUZZ_AGENT=1 to 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, and suggestion fields

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-gen regenerates the typed Slack client (174 methods).
  • make manifest-gen AST-walks pkg/cmd/ for slackapi.<Method>(...) calls and writes the corresponding scope union to pkg/cmd/app/manifest.go.
  • make verify-gen runs 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 helpers
  • internal/slackapi/files.go — the external upload flow (UploadFiles: every file uploaded, then shared in one files.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