Discord automation with discord_cli.py
A bundled Python script that wraps the Discord REST API v10. Zero external dependencies — uses only Python stdlib (urllib, json, argparse).
Invoke as: python3 <path-to-skill>/scripts/discord_cli.py <command> <subcommand> [args]
Setup
1. Create a Discord bot
- Go to Discord Developer Portal → New Application
- Click Bot on the sidebar → click Reset Token → copy the token
- Critical: Scroll down to Privileged Gateway Intents and enable Message Content Intent — without this, message content will be empty in API responses
- Optionally enable Server Members Intent (needed for
user list)
2. Add the bot to your server
- Click OAuth2 on the sidebar → scroll to OAuth2 URL Generator
- Check scopes:
bot+applications.commands - Under Bot Permissions, check: View Channels, Send Messages, Read Message History, Add Reactions, Attach Files
- Copy the generated URL → open in browser → select your server → Authorize
Shortcut if you know the client ID:
https://discord.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&scope=bot+applications.commands&permissions=274877975552
3. Set your bot token
bashexport DISCORD_BOT_TOKEN="your_token_here"
4. Verify
bashpython3 <path-to-skill>/scripts/discord_cli.py auth test
Expected output:
json{"ok": true, "user": "your-bot-name", "id": "...", "discriminator": "..."}
Commands
Auth
bashpython3 <path-to-skill>/scripts/discord_cli.py auth test
Servers
bashpython3 <path-to-skill>/scripts/discord_cli.py server list python3 <path-to-skill>/scripts/discord_cli.py server info <server-id>
Channels
bashpython3 <path-to-skill>/scripts/discord_cli.py channel list <server-id>
Returns text, announcement, and forum channels sorted by category and position. Each channel has id, name, type, category, and topic.
Messages
bash# List recent messages (default 25, chronological order) python3 <path-to-skill>/scripts/discord_cli.py message list <channel-id> python3 <path-to-skill>/scripts/discord_cli.py message list <channel-id> --limit 50 # Get a single message python3 <path-to-skill>/scripts/discord_cli.py message get <channel-id> <message-id> # Send a message python3 <path-to-skill>/scripts/discord_cli.py message send <channel-id> "Hello from the agent!" # Edit a message (bot can only edit its own messages) python3 <path-to-skill>/scripts/discord_cli.py message edit <channel-id> <message-id> "Updated text" # Delete a message python3 <path-to-skill>/scripts/discord_cli.py message delete <channel-id> <message-id> # Search messages in a server python3 <path-to-skill>/scripts/discord_cli.py message search <server-id> "query" python3 <path-to-skill>/scripts/discord_cli.py message search <server-id> "query" --channel-id <id> --author-id <id> --limit 10
Reactions
bashpython3 <path-to-skill>/scripts/discord_cli.py reaction add <channel-id> <message-id> 👍 python3 <path-to-skill>/scripts/discord_cli.py reaction remove <channel-id> <message-id> 👍 python3 <path-to-skill>/scripts/discord_cli.py reaction list <channel-id> <message-id>
Threads
bash# Create a new thread in a channel python3 <path-to-skill>/scripts/discord_cli.py thread create <channel-id> "Discussion Topic" # Create a thread from a specific message python3 <path-to-skill>/scripts/discord_cli.py thread create <channel-id> "Bug Triage" --message-id <id>
Pins
bashpython3 <path-to-skill>/scripts/discord_cli.py pin list <channel-id> python3 <path-to-skill>/scripts/discord_cli.py pin add <channel-id> <message-id> python3 <path-to-skill>/scripts/discord_cli.py pin remove <channel-id> <message-id>
Users
bashpython3 <path-to-skill>/scripts/discord_cli.py user list <server-id> python3 <path-to-skill>/scripts/discord_cli.py user list <server-id> --limit 200 python3 <path-to-skill>/scripts/discord_cli.py user info <user-id>
Mention users in messages as <@USER_ID>.
Output format
All commands output JSON to stdout. Errors go to stderr with an error field and HTTP status code.
Message objects include: id, author, author_id, content, timestamp, plus optional thread_id, attachments (with filename and url), and reactions (with emoji and count). Null and empty fields are pruned.
Troubleshooting
Message content is empty
Message Content Intent is not enabled. Go to Developer Portal → Bot → Privileged Gateway Intents → toggle on Message Content Intent.
user list returns empty or partial results
Server Members Intent is not enabled. Toggle it on in the same intents section.
403 / missing access errors
The bot doesn't have permission for that channel. Check bot role permissions in Discord server settings, or re-authorize with the correct permissions.
Token errors
If the bot token was rotated, update DISCORD_BOT_TOKEN with the new value.
Notes
- Discord uses Snowflake IDs (large numbers like
1161736244074659893) for all identifiers. You cannot use channel names directly — usechannel list <server-id>to find IDs first. - The bot can only access servers it has been invited to and channels it has permissions for.
- Bot token auth uses the official Discord API — no user token extraction, no ToS risk.
- Messages are returned in chronological order (oldest first).
