slack-agent-cli

README

slk

Slack for Non-Humans™

Why "Non-Humans"?

Humans have eyes, we have jq.
Humans need emojis, we need thread_ts.
Humans want a UI, we just want a clean pipe.

This is not a CLI for you. This is a CLI for your digital entities.

---

[!WARNING] Human, this tool defaults to JSON output. If your biological eyes find this hard to parse, use the --human flag. We recommend upgrading your optic nerve or using jq.

Features

• Pipe-First Design - Output is always pure JSON (stdout) while logs go to stderr.
• Agent-Ready - Stateless authentication, perfect for LLMs, scripts, and cron jobs.
• Smart Caching - Resolves channel names (#general) to IDs (C123...) locally for speed.
• Image Uploads - Send local images into channels or threads with Slack's current external upload API.

Quick Start

For Digital Entities (Default)

# Get channel history as minified JSON
slk messages list --channel C12345

# Pipe directly into other tools
slk messages list --channel "#general" | jq '.[].text'

For Biological Entities

# Save your token to config
slk auth login --token xoxp-your-token --verify

# List channels in human-readable format
slk channels list --human

# List recent messages
slk messages list --channel "#general" --limit 10 --human

Installation

Homebrew (macOS/Linux)

brew install kehao95/slack-agent-cli/slk

Go Install

go install github.com/kehao95/slack-agent-cli@latest

Pre-built Binaries

Download from GitHub Releases

Authentication & Configuration

How It Works

This CLI uses User Tokens - It authenticates as you and acts on your behalf in Slack. This means:

• Acts as you: Messages, reactions, and actions appear as if you did them
• Uses your permissions: Can only access channels/DMs you have access to
• Simple & stateless: No OAuth flows, webhooks, or server infrastructure needed
• Token security: Keep your token safe - it has the same permissions you do

User Token (what this CLI uses):

• Format: xoxp-...
• Represents you (the user)
• Perfect for automation, scripts, and AI agents acting on your behalf

Bot Token (NOT used by this CLI):

• Format: xoxb-...
• Represents a bot user (separate identity)
• Requires more setup and different use cases

Quick Setup (1 minute)

1. Create Slack App: Go to https://api.slack.com/apps → "Create New App" → "From an app manifest"
2. Choose mode & use manifest:
   • Read-Only (recommended): slack-app-manifest-readonly.yaml
   • Full Access: slack-app-manifest-full.yaml
3. Install to workspace: Click "Install to Workspace" and authorize
4. Copy token: Copy the User OAuth Token (starts with xoxp-)
5. Configure:
   • Option A (Recommended): Run slk auth login --token xoxp-... --verify
   • Option B: Set export SLACK_USER_TOKEN='xoxp-...'
   • Option C: Use OAuth flow with slk auth oauth (see below)

See SLACK_SETUP.md for detailed setup instructions and mode comparison.

OAuth Flow (Alternative)

For automated token exchange, use the built-in OAuth server:

slk auth oauth --client-id $SLACK_CLIENT_ID --client-secret $SLACK_CLIENT_SECRET --save

This starts a local server on port 8089 with a /callback endpoint. Expose it publicly (via your preferred method) and add the callback URL to your Slack app's redirect URIs. With --save, the token is automatically saved to config after successful exchange.

Available Commands

slk
├── auth            # Authentication
│   ├── login       # Save token to config
│   ├── oauth       # Start OAuth callback server
│   ├── test        # Verify credentials work
│   └── whoami      # Show current user info
│
├── cache           # Cache management
│   ├── populate    # Fetch and cache channels/users
│   ├── status      # Show cache state
│   └── clear       # Clear cached data
│
├── channels        # Channel operations
│   ├── list        # List accessible channels
│   ├── join        # Join a channel
│   └── leave       # Leave a channel
│
├── messages        # Message operations
│   ├── list        # Fetch message history
│   ├── send        # Send a message
│   ├── edit        # Edit a message
│   ├── delete      # Delete a message
│   ├── search      # Search messages
│   └── next        # Wait for the next cached message event
│
├── events          # Event stream/cache operations
│   ├── stream      # Stream Socket Mode events as NDJSON
│   ├── list        # Query cached daemon events
│   ├── next        # Wait for the next matching cached event
│   ├── claim       # Claim one pending event for processing
│   └── ack         # Acknowledge processed cursor
│
├── daemon          # Local event cache daemon
│   ├── run         # Cache Socket Mode events into SQLite
│   └── status      # Inspect local event cache status
│
├── lists           # Slack List operations
│   ├── items       # Fetch items from a Slack List
│   └── item        # Fetch one item with list metadata
│
├── reactions       # Reaction operations
│   ├── add         # Add reaction to message
│   ├── remove      # Remove reaction
│   └── list        # List reactions on message
│
├── pins            # Pin operations
│   ├── add         # Pin a message
│   ├── remove      # Unpin a message
│   └── list        # List pinned messages
│
├── users           # User operations
│   ├── list        # List workspace members
│   ├── info        # Get user details
│   └── presence    # Check user presence
│
└── emoji           # Emoji operations
    └── list        # List custom emoji

Use Cases

The "Pipeline" Approach

# Summarize the last hour of #alerts using an LLM
slk messages list --channel "#alerts" --since 1h | llm "Summarize these alerts"

# Pull the latest helpdesk rows from a Slack List
slk lists items --list https://contentsquare.slack.com/lists/T027K0ZC9/F0BFMJY6ZTQ | jq '.items'

# Fetch the entire list across all pages
slk lists items --list F0BFMJY6ZTQ --all

# Inspect one record with schema-aware field output
slk lists item --list F0BFMJY6ZTQ --id Rec018B8RR603 --human

# Auto-reply to specific errors
slk messages search --query "error: deployment" | \
  jq -r '.matches[].ts' | \
  xargs -I {} slk messages send --channel "#ops" --thread {} --mrkdwn "Investigating..."

Agent Workflow Example

# 1. Check recent messages
slk messages list --channel "#support" --since 1h

# 2. Search for specific issues
slk messages search --query "error in:#support"

# 3. Send a response
slk messages send --channel "#support" --thread "$THREAD_TS" --mrkdwn "Here's the answer..."

# Send a screenshot with an optional caption
slk messages send --channel "#support" --image ./screenshot.png --mrkdwn "Latest screenshot"

# 4. Add acknowledgment reaction
slk reactions add --channel "#support" --ts "$MESSAGE_TS" --emoji "white_check_mark"

Event Stream Filtering

# Only wake downstream workers for message events from one channel
slk events stream --channel "#support" --exclude-self --event-type message

# Keep multiple event classes in one stream
slk events stream --channel "#support" --event-type message,reaction_added

# Also append each matching event to a local NDJSON file
slk events stream --channel "#support" --event-type message -f /tmp/support.events.ndjson

Daemon Event Loop Example

# Terminal/supervisor 1: cache visible Slack events for 24h by default
SLACK_CLI_ROLE=bot slk daemon run --channel "#_bot-testing"

# Agent loop (queue): claim top-level messages -> process -> ack
while true; do
  event=$(slk events claim --type message --message-kind root --channel "#_bot-testing" --lease 5m)
  cursor=$(echo "$event" | jq -r '.cursor')
  # ... process event ...
  slk events ack "$cursor"
done

# Thread replies can be claimed separately, which is useful for subagent handoff.
slk events claim --type message --message-kind reply --thread "$THREAD_TS" --lease 5m

# Only claim messages that explicitly mention the active Slack user.
slk events claim --type message --mentions-me --lease 5m

# If processing fails, do not ack; the lease expiry makes it claimable again.

# Avoid reacting to the bot's own messages
slk events claim --type message --exclude-self --lease 5m | jq -r '.cursor'

Configuration

Config File Location

~/.config/slack-cli/config.json

Or override with SLACK_CLI_CONFIG environment variable.

Environment Variables

Variable	Description
SLACK_CLI_ROLE	Active auth role: user or bot (default: user)
SLACK_USER_TOKEN	Override user token from config
SLACK_BOT_TOKEN	Override bot token from config
SLACK_APP_TOKEN	App-level token for Socket Mode events
SLACK_CLI_CONFIG	Custom config file path
SLACK_CLI_FORMAT	Default output format (json or human)

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error (missing config, invalid tokens)
3	Authentication error (invalid/expired tokens)
4	Rate limit exceeded
5	Network error
6	Permission denied (missing scopes)
7	Resource not found (channel, user, message)
124	Wait timeout, e.g. events next --timeout

License

MIT