discli — Discord Server Management CLI

Control Discord servers from the terminal. Works for both humans and AI agents.

Agent Defaults

• Output is auto-detected: YAML when piped (agent), table in terminal (human).
• YAML is the preferred format for agents — 5x fewer tokens than JSON.
• Use -n to limit results and keep token usage low.
• Use --format yaml to force structured output, --format json if you need strict JSON.
• Use --dry-run on create/rename/permission commands to preview changes.
• Destructive commands (delete, kick, ban) require --confirm — they will NOT prompt.
• See SCHEMA.md for output shapes.

Install / Update

npm install -g @ibbybuilds/discli         # Install
npm install -g @ibbybuilds/discli@latest   # Update to latest

If discli is not installed, install it first before running any commands.

Windows: Prefer Git Bash over PowerShell. Git Bash handles UTF-8, quoting, and special characters correctly out of the box. PowerShell has encoding issues (garbled emojis), quoting issues (special chars like &, $, = break messages), and argument expansion problems with long text.

If you must use PowerShell, run this at session start:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

And use single quotes for message content to avoid special character expansion. First-time setup: docs/BOT_SETUP.md

Message Limits

• Message content: 2,000 characters max
• Embed description: 4,096 characters max
• Embed total (all fields combined): 6,000 characters max
• Max 10 embeds per message

If your message exceeds 2,000 characters, split it into multiple msg send calls. For longer content, use msg embed with --description (up to 4,096 chars). Never truncate silently.

Quick Reference

discli init --token <token>           # First-time setup
discli server list                    # List servers
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  # Verification level
discli server set --notifications only_mentions  # Notification default
discli server icon ./logo.png            # Change server icon

discli invite list                    # List all invites
discli invite create <channel>        # Create invite
discli invite create <ch> --max-age 3600 --max-uses 10  # With limits
discli invite delete <code> --confirm # Delete invite

discli channel list                   # List channels
discli channel create <name>          # Create channel (--type, --category, --topic)
discli channel delete <name>          # Delete channel (--confirm required)
discli channel rename <ch> <name>     # Rename channel
discli channel topic <ch> <text>      # Set topic
discli channel move <ch>              # Move to category (--category, --position)
discli channel clone <ch>             # Clone channel with same settings
discli channel slowmode <ch> <sec>    # Set slowmode (0 to disable)

discli role list                      # List roles
discli role create <name>             # Create role (--color, --mentionable)
discli role edit <name> --color "#hex" --name "New"  # Edit role
discli role delete <name>             # Delete role (--confirm required)
discli role assign <role> <user>      # Give role to member
discli role remove <role> <user>      # Remove role from member

discli member list                    # List members
discli member info <user>             # Member details
discli member kick <user>             # Kick (--confirm, --reason)
discli member ban <user>              # Ban (--confirm, --reason)
discli member nick <user> <nick>      # Change nickname

discli perm view <channel>            # View channel permissions
discli perm set <ch> <role>           # Set permissions (--allow, --deny)
discli perm lock <channel>            # Make read-only for @everyone
discli perm unlock <channel>          # Remove read-only
discli perm list                      # List available permission names

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

discli emoji list                        # List custom emojis
discli emoji upload <name> ./img.png     # Upload custom emoji
discli emoji delete <name> --confirm     # Delete custom emoji

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 performed action
discli audit types                       # List action type names

Global Flags

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

Exit Codes

• 0 — success
• 1 — general error
• 2 — usage error
• 3 — not found
• 4 — permission denied

Bot Personality (SOUL.md)

When sending messages, reacting, or interacting as the bot, check for a SOUL.md file at ~/.discli/SOUL.md. If it exists, read it first and stay in character for all bot interactions (messages, replies, reactions, embeds).

If no SOUL.md exists yet, ask your human how they want their bot to sound:

• What's the bot's name?
• What personality? (cheeky, professional, friendly, chaotic, minimal, etc.)
• How should it talk? (casual lowercase, formal, emoji-heavy, dry wit, etc.)
• Any specific traits or quirks?

Then generate a SOUL.md and save it to ~/.discli/SOUL.md. Use this structure:

• Core Truths: behavioral principles (how the bot acts)
• Boundaries: hard limits (what it won't do)
• Vibe: tone, humor style, emoji preferences, example responses
• Identity: name, what it is, who made it

The bot should feel like a character, not a command runner.

Notes

• Channel/role/member names are resolved case-insensitively.
• You can use IDs instead of names to avoid ambiguity.
• Rate limits: Discord allows ~5 requests/second. Channel renames have a 10-min cooldown per channel.
• Config stored in ~/.discli/ (token in .env, defaults in config.json).
• Bot personality stored in ~/.discli/SOUL.md (optional, see above).