Channels, roles, permissions, messages, embeds, files, emojis, invites, audit logs. Control your entire Discord server from the terminal.

No bot server needed. No dashboard clicking. Just commands.

Your AI agent (Claude Code, Cursor, Codex, Copilot and others) can use discord-cli to manage your Discord server. Create channels, assign roles, rename everything, in seconds.

Why discord-cli?

Setting up a Discord server manually is slow. Using bots for management is limited. MCP tools eat your token budget.

discord-cli gives you direct control over Discord through simple CLI commands:

discli channel create "💬・general" --category "Community"
discli role create "Moderator" --color "#ff5733"
discli perm lock "📜・rules"
discli channel rename "old-name" "🎯・new-name"

One command = one API call. No bot server. No token overhead.

🚀 Quick Start

# Install
npm install -g @rodrigopg/discord-cli

# Or run directly without installing
npx @rodrigopg/discord-cli --help

# Setup (paste your bot token)
discli init --token YOUR_BOT_TOKEN

# Start managing
discli channel list
discli server info

1. Go to Discord Developer Portal
2. Create a new application
3. Go to Bot > Reset Token > copy it
4. Enable Message Content Intent (required to read messages)
5. Go to Installation > set Guild Install scopes: bot, applications.commands with Administrator permission
6. Use the install link to add the bot to your server
7. Run discli init --token YOUR_TOKEN

Permissions tip: Administrator gives discord-cli full access, but you can select only the permissions you need (Manage Channels, Manage Roles, etc.).

⚠️ Safety

When using with AI agents: Always review commands before approving. Destructive commands like channel delete, member kick, and member ban require --confirm but your agent may add that flag automatically. Make sure your agent setup asks for your approval before running destructive actions.

📖 Commands

🖥️ Server

discli server list              # List servers the bot is in
discli server select <id>       # Set default server
discli server info              # Server overview
discli server set --name "X"    # Change server name
discli server set --description "X"              # Set description
discli server set --verification medium          # Set verification level
discli server set --notifications only_mentions  # Default notifications
discli server icon ./logo.png                    # Change server icon

🔗 Invites

discli invite list                          # List all invites
discli invite create <channel>              # Create invite (never expires)
discli invite create <ch> --max-age 3600    # Expire after 1 hour
discli invite create <ch> --max-uses 10     # Max 10 uses
discli invite delete <code> --confirm       # Delete invite
discli invite delete <code> --dry-run       # Preview without executing

💬 Channels

discli channel list                          # List all channels by category
discli channel create <name>                 # Create text channel
discli channel create <name> --type voice    # Create voice channel
discli channel create <name> --category Dev  # Create under a category
discli channel create "Dev" --type category  # Create a category
discli channel rename <channel> <new-name>   # Rename channel
discli channel topic <channel> "topic text"  # Set channel topic
discli channel move <channel> --category X   # Move to a category
discli channel clone <channel>               # Clone channel with same settings
discli channel clone <channel> --name "new"  # Clone with new name
discli channel slowmode <channel> 5          # Set slowmode (seconds, 0 to disable)
discli channel delete <channel> --confirm    # Delete (requires --confirm)

🎭 Roles

discli role list                                       # List all roles
discli role create <name>                              # Create role
discli role create <name> --color "#e74c3c" --hoist    # With color and hoist
discli role create <name> --permissions kick_members,ban_members  # With permissions
discli role edit <name> --color "#3498db"              # Change role color
discli role edit <name> --name "New Name" --hoist      # Rename and hoist
discli role assign <role> <user>                       # Give role to member
discli role remove <role> <user>                       # Remove role from member
discli role delete <name> --confirm                    # Delete (requires --confirm)

👥 Members

discli member list                                    # List members
discli member info <user>                             # Member details
discli member nick <user> <nick>                      # Change nickname
discli member kick <user> --confirm --reason "spam"   # Kick
discli member kick <user> --dry-run                   # Preview without executing
discli member ban <user> --confirm                    # Ban
discli member ban <user> --dry-run                    # Preview without executing

🔒 Permissions

discli perm view <channel>                             # View channel permissions
discli perm lock <channel>                             # Make read-only
discli perm unlock <channel>                           # Remove read-only
discli perm set <channel> <role> --deny send_messages  # Fine-grained control
discli perm list                                       # List permission names

✉️ Messages

discli msg send <channel> "Hello world"                           # Send message
discli msg send <channel> "reply" --reply <msg-id>                # Reply to message
discli msg send <channel> "check this" --file ./img.png           # Send with file
discli msg send <channel> --file ./a.png --file ./b.pdf           # Multiple files
discli msg embed <channel> --title "X" --description "Y" --color "#5865F2"  # Rich embed
discli msg embed <channel> --title "X" --field "Name|Value|inline"          # Embed with fields
discli msg embed <channel> --title "X" --image ./screenshot.png   # Embed with local image
discli msg search <channel> "keyword"                             # Search messages by keyword
discli msg read <channel> -n 10                                   # Read last N messages
discli msg edit <channel> <msg-id> "new text"                     # Edit bot message
discli msg delete <channel> <msg-id> --confirm                    # Delete message
discli msg bulk-delete <channel> -n 10 --confirm                  # Delete multiple messages
discli msg react <channel> <msg-id> 👍                            # Add reaction
discli msg unreact <channel> <msg-id> 👍                          # Remove reaction
discli msg pin <channel> <msg-id>                                 # Pin message
discli msg unpin <channel> <msg-id>                               # Unpin message
discli msg pins <channel>                                         # List pinned messages
discli msg thread <channel> "Thread Name"                         # Create thread
discli msg thread <channel> "Name" --message <msg-id>             # Thread from message

😎 Emojis

discli emoji list                        # List custom emojis
discli emoji upload <name> ./emoji.png   # Upload custom emoji (png, jpg, gif, max 256KB)
discli emoji delete <name> --confirm     # Delete custom emoji

📋 Audit Log

discli audit log                         # View recent audit log
discli audit log -n 50                   # Last 50 entries
discli audit log --type member_kick      # Filter by action type
discli audit log --user <id>             # Filter by who did it
discli audit types                       # List all action type names

🤖 For AI Agents

discord-cli is designed for AI agents like Claude Code, Cursor, Codex, Copilot, and others.

How agents use it

1. 📦 Install discord-cli globally or use npx
2. 📄 Agent reads the skill file and learns all available commands
3. ⚡ Agent runs commands and manages your server through the terminal

Agent-friendly features

| Feature | Details | |---------|---------| | 📊 YAML output by default | Fewer tokens than JSON when piped | | 🔢 -n flag | Limit results to save tokens | | 👀 --dry-run | Preview changes before applying (kick, ban, invite delete) | | ✋ --confirm required | Destructive commands never auto-execute | | 🔄 Structured exit codes | 0 success, 1 error, 2 usage, 3 not found, 4 forbidden | | 🧱 JSON errors on stderr | --format json emits {"error":true,"message":"..."} — machine-parseable | | 🔁 Auto retry on rate limit | 429 responses wait Retry-After and retry automatically | | 🔒 Token file chmod 600 | Bot token stored with restricted permissions |

Install the CLI

# Install globally
npm install -g @rodrigopg/discord-cli

# Or run directly (no install needed)
npx @rodrigopg/discord-cli channel list

Install the Claude Code skill

mkdir -p ~/.claude/skills/discli
curl -o ~/.claude/skills/discli/SKILL.md \
  https://raw.githubusercontent.com/rodrigopg/discli/master/skills/SKILL.md

This installs the skill that teaches Claude Code all available commands, flags, and gotchas.

Example: agent sets up an entire server

You: "Set up my Discord like a dev community with channels for
      general chat, code help, AI tools, and read-only announcements"

Agent runs:
  discli channel create "Community" --type category
  discli channel create "💬・general" --category Community
  discli channel create "💻・code-help" --category Community
  discli channel create "🤖・ai-tools" --category Community
  discli channel create "📢・announcements" --category Info
  discli perm lock "📢・announcements"

🏁 Global Flags

| Flag | Description | |------|-------------| | --format <yaml\|json\|table\|auto> | Output format. Default: auto (YAML when piped, table in terminal) | | --server <id> | Target a specific server instead of default | | -n <count> | Limit results on list commands | | --dry-run | Preview changes without applying | | --confirm | Required for destructive actions (delete, kick, ban) |

⚙️ How It Works

discord-cli is not a bot. It's a thin CLI wrapper around the Discord REST API.

discli channel create "test"
    ↓
POST https://discord.com/api/v10/guilds/{id}/channels
Authorization: Bot {your_token}
Body: {"name": "test", "type": 0}
    ↓
Channel created. Done.

No WebSocket connection. No bot process. No server hosting. Your bot can be offline and commands still work.

🔐 Bring Your Own Bot

discord-cli uses your bot token. You create the bot, you control the permissions, you own the data. Nothing is sent anywhere.

~/.discli/
├── config.json    # default server
└── .env           # your bot token (chmod 600 — never leaves your machine)

📊 Comparison

| | discord-cli | Discord MCP | Manual UI | |---|---|---|---| | Purpose | Server management | Server management | Everything | | Used by | Agents + humans | Agents only | Humans only | | Token cost | Zero upfront | 20-40k on load | N/A | | Create channels | ✅ | ✅ | ✅ | | Manage roles | ✅ | ✅ | ✅ | | Set permissions | ✅ | ✅ | ✅ | | Read messages | ✅ | ✅ | ✅ | | Send embeds | ✅ | ✅ | ✅ | | File uploads | ✅ | ✅ | ✅ | | Custom emojis | ✅ | ❌ | ✅ | | Bulk delete | ✅ | ❌ | ✅ | | JSON errors | ✅ | ❌ | N/A | | Auto retry 429 | ✅ | ❌ | N/A | | Self-hosted | ✅ | ✅ | N/A |

🗺️ Roadmap

• [x] Channel management (create, delete, rename, topic, move, clone, slowmode)
• [x] Role management (create, edit, delete, assign, permissions)
• [x] Member management (list, kick, ban, nick) with --dry-run
• [x] Permission management (view, set, lock, unlock)
• [x] Message management (send, embed, read, edit, pin, react, thread, search, bulk-delete)
• [x] File uploads (images, videos, documents, up to 25MB)
• [x] Emoji management (list, upload, delete)
• [x] Audit log
• [x] Invite management with --dry-run
• [x] Server settings and icon
• [x] JSON-structured errors for AI agents
• [x] Auto retry on rate limit (429)
• [ ] Webhook management
• [ ] Scheduled events
• [ ] Automod rules
• [ ] Server templates (export/import structure)

📄 License

MIT