discord

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

1. Go to Discord Developer Portal → New Application
2. Click Bot on the sidebar → click Reset Token → copy the token
3. Critical: Scroll down to Privileged Gateway Intents and enable Message Content Intent — without this, message content will be empty in API responses
4. Optionally enable Server Members Intent (needed for user list)

2. Add the bot to your server

1. Click OAuth2 on the sidebar → scroll to OAuth2 URL Generator
2. Check scopes: bot + applications.commands
3. Under Bot Permissions, check: View Channels, Send Messages, Read Message History, Add Reactions, Attach Files
4. 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

export DISCORD_BOT_TOKEN="your_token_here"

4. Verify

python3 <path-to-skill>/scripts/discord_cli.py auth test

Expected output:

{"ok": true, "user": "your-bot-name", "id": "...", "discriminator": "..."}

Commands

Auth

python3 <path-to-skill>/scripts/discord_cli.py auth test

Servers

python3 <path-to-skill>/scripts/discord_cli.py server list
python3 <path-to-skill>/scripts/discord_cli.py server info <server-id>

Channels

python3 <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

# 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

python3 <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

# 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

python3 <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

python3 <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 — use channel 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).