slack-agent-cli: Instructions file for Codex

Slack Agent CLI — AI Agent Guide

This file helps AI agents (Claude, Cursor, GPT, Gemini, OpenClaw) install, authenticate, and use slack-agent-cli to manage Slack workspaces via terminal commands or MCP tools.

Quick Start

# Install (requires Node 18+ and Python 3.10+)
npm install -g slack-agent-cli

# Authenticate (non-interactive — best for agents)
export SLACK_BOT_TOKEN="xoxb-your-bot-token"
export SLACK_USER_TOKEN="xoxp-your-user-token"   # optional; required for search

# Verify
slack --version
slack channels list --pretty

Alternative (Python-only, from source):

git clone https://github.com/bcharleson/slack-agent-cli.git
cd slack-agent-cli
python3 -m venv venv && source venv/bin/activate
pip install -e .
slack channels list

Authentication

Two tokens, resolved in this order:

1. --bot-token / --user-token flags (per-command override)
2. SLACK_BOT_TOKEN / SLACK_USER_TOKEN environment variables (recommended for agents)
3. .env file in the working directory (via python-dotenv)

Token	Prefix	Used for
Bot token	xoxb-	Channels, messages, DMs, reactions, most user lookups
User token	xoxp-	Search (search.* commands/tools) — bot token cannot search

Create tokens at Slack API Apps → your app → OAuth & Permissions → Install to workspace.

Minimum bot scopes: channels:read, channels:write, channels:history, groups:read, groups:write, groups:history, chat:write, im:read, im:write, im:history, mpim:read, mpim:write, mpim:history, users:read, users:read.email, reactions:read, reactions:write.

For search, add user scope: search:read.

Output Format

All commands return JSON — stdout on success, stderr on error:

# Default: compact JSON (agent-optimized)
slack channels list
# → {"channels":[{"id":"C0123","name":"general",...}],"total":42}

# Pretty-printed
slack channels list --pretty
# or
slack --output pretty channels list

# Exit code only (automation)
slack --quiet channels list