npm package: @rodrigopg/discord-cli
Description: Discord server management CLI for humans and AI agents. Manage channels, roles, members, messages and more from your terminal.
Author: rodrigopg
Latest version: 0.7.2

<p align="center">
  <img src="assets/banner.png" alt="discord-cli - Discord Server Management CLI" width="100%">
</p>

<p align="center">
  <strong>Discord server management CLI for AI agents and humans.</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@rodrigopg/discord-cli"><img src="https://img.shields.io/npm/dw/%40rodrigopg%2Fdiscord-cli?label=npm%20downloads&color=cb3837" alt="npm downloads"></a>
  <a href="https://github.com/rodrigopg/discli/releases/latest"><img src="https://img.shields.io/github/v/release/rodrigopg/discli?color=green" alt="release"></a>
  <a href="https://github.com/rodrigopg/discli/actions"><img src="https://img.shields.io/github/actions/workflow/status/rodrigopg/discli/ci.yml?label=build" alt="build"></a>
</p>

<br>

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.

<br>

## 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:

```bash
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.

<br>

## 🚀 Quick Start

```bash
# 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
```

<details>
<summary><strong>🔑 How to get a bot token</strong></summary>

<br>

1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
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.).

</details>

<br>

## ⚠️ 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.

<br>

## 📖 Commands

### 🖥️ Server

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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
```

<br>

## 🤖 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

```bash
# 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

```bash
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"
```

<br>

## 🏁 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) |

<br>

## ⚙️ How It Works

discord-cli is not a bot. It's a thin CLI wrapper around the [Discord REST API](https://discord.com/developers/docs/reference).

```
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.

<br>

## 🔐 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)
```

<br>

## 📊 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 |

<br>

## 🗺️ 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)

<br>

## 📄 License

MIT

<br>

<p align="center">
  Fork de <a href="https://github.com/ibbybuilds/discli">ibbybuilds/discli</a> com melhorias para agentes IA — por <a href="https://github.com/rodrigopg">@rodrigopg</a>
</p>