Show HN: Discord-CLI – a headless Discord CLI that prints JSON and exits

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)

• 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

pip install discordcli-agents
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"

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.

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
discord-cli guild info

discord-cli channel list

discord-cli channel create "announcements" --type text --topic "Server announcements"

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

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

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.

• 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 , andexport — the rest of the automation surface

• man discord-cli — the complete command reference, also readable in the repo atdocs/man/discord-cli.1

• Recipes

• AI agent integration

• Plugin guide

• Contributing guide

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