discord-cli

discord-cli is a headless, scriptable Discord CLI for automation and AI-agent workflows. It connects with a Discord bot token, runs a single command, and exits; command output is JSON by default so you can pipe it into jq, save it in CI logs, or call it from shell scripts and local agents.

Current release: 1.4.0 (PyPI)

Why discord-cli?

• Script Discord operations from shell, cron, GitHub Actions, or an AI agent
• Keep the bot token and workflow logic outside a long-running service process
• Use JSON output for automation and jq for filtering without custom glue code

Install

Command-line tool

pip install discordcli-agents
# or
npx discordcli-agents

The installed command is discord-cli.

A man page ships with the package, so after a pip or pipx install you can read the full reference offline:

man discord-cli

If your shell cannot find it (some virtualenv layouts are not on the default MANPATH), point man at the file directly:

man "$(python -c 'import sysconfig; print(sysconfig.get_path("data"))')/share/man/man1/discord-cli.1"

Agent skill

Install the repository's discord-cli-server-management skill with the open skills CLI:

npx skills add 1solomonwakhungu/discord-cli --skill discord-cli-server-management

The skill is listed on skills.sh and works with Codex, Claude Code, Cursor, GitHub Copilot, and other agents supported by the skills CLI.

Quick setup

1. Create a bot at the Discord Developer Portal
2. Add it to your server with the permissions you need
3. Export a token:

export DISCORD_BOT_TOKEN="your-bot-token-here"

Or create a .env file in the same directory:

echo 'DISCORD_BOT_TOKEN=your-bot-token-here' > .env

Quick start

# Server info
discord-cli guild info

# List channels
discord-cli channel list

# Create a channel
discord-cli channel create "announcements" --type text --topic "Server announcements"

# Send a message
discord-cli message send 123456789012345678 --content "Hello from the CLI!"

# Export channel history
discord-cli export channel 123456789012345678 --limit 500 --format json > history.json

Recipes

Use the ready-to-copy examples in docs/recipes.md for:

• GitHub Actions notifications
• Scheduled maintenance and status checks
• Server/channel export and backup
• Bulk role and permission changes
• Claude/Codex and generic terminal-agent workflows

Need a deeper AI-agent workflow guide? See docs/ai-agents.md.

Command groups

• channel — channel management and inspection
• message — send, edit, react, purge, and fetch messages
• guild — guild profile, emojis, stickers, bans, and prune flows
• member — list, info, kick, ban, timeout, nickname, and role checks
• role — create, edit, assign, remove, and inspect roles
• permissions — per-channel permission overwrites
• webhook, threads, invite, category, search, and export — the rest of the automation surface

Documentation

• man discord-cli — the complete command reference, also readable in the repo at docs/man/discord-cli.1
• Recipes
• AI agent integration
• Plugin guide
• Contributing guide

License

This project is licensed under the MIT License. See LICENSE for details.