Discli

<p align="center"> <img src="assets/banner.png" alt="discli - 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/@ibbybuilds/discli"><img src="https://img.shields.io/npm/dw/%40ibbybuilds/discli?label=npm%20downloads&color=cb3837" alt="npm downloads"></a> <a href="https://github.com/ibbybuilds/discli/releases/latest"><img src="https://img.shields.io/github/v/release/ibbybuilds/discli?color=green" alt="release"></a> <a href="https://github.com/ibbybuilds/discli/actions"><img src="https://img.shields.io/github/actions/workflow/status/ibbybuilds/discli/ci.yml?label=build" alt="build"></a> <a href="https://twitter.com/ibbyybuilds"><img src="https://img.shields.io/badge/follow-%40ibbyybuilds-1DA1F2?logo=x&logoColor=white" alt="follow on X"></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 (AIOS Companion, OpenClaw, Claude Code, Cursor, Codex) can use discli to manage your Discord server. Create channels, assign roles, rename everything, in seconds.

<p align="center"> <img src="assets/demo.webp" alt="discli demo - AI agent setting up a Discord server" width="100%"> </p> <br>

Why discli?

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

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

<br>

🚀 Quick Start

# Install
npm install -g @ibbybuilds/discli

# Or run directly without installing
npx @ibbybuilds/discli --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>

Full step-by-step guide: docs/BOT_SETUP.md

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 discli full access, but you don't have to. You can select only the permissions you need (Manage Channels, Manage Roles, etc.). Some features won't work without specific permissions, but you stay in control of what the bot can do.

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

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

💬 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 ban <user> --confirm                  # Ban

🔒 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

<br>

🤖 For AI Agents

discli is designed for AI agents like AIOS Companion, OpenClaw, Claude Code, Cursor, Codex, and others.

How agents use it

1. 📦 Install discli 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 | 5x fewer tokens than JSON when piped | | 🔢 -n flag | Limit results to save tokens | | 👀 --dry-run | Preview changes before applying | | ✋ --confirm required | Destructive commands never auto-execute | | 🔄 Structured exit codes | 0 success, 1 error, 2 usage, 3 not found, 4 forbidden | | 📐 SCHEMA.md | Documents output shapes for predictable parsing | | ⚡ No MCP overhead | Zero token cost at session start |

Install the CLI

# Install globally
npm install -g @ibbybuilds/discli

# Or run directly (no install needed)
npx @ibbybuilds/discli channel list

Install the skill

# Option 1: via npx skills (if you have skills.sh)
npx skills add ibbybuilds/discli

# Option 2: copy from GitHub (works everywhe