\r \r

discli — Discord Server Management CLI\r

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

Agent Defaults\r

\r

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

Install / Update\r

\r

npm install -g @ibbybuilds/discli         # Install\r
npm install -g @ibbybuilds/discli@latest   # Update to latest\r
```\r
\r
If discli is not installed, install it first before running any commands.\r
\r
**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.\r
\r
If you must use PowerShell, run this at session start:\r
```powershell\r
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8\r
```\r
And use single quotes for message content to avoid special character expansion.\r
First-time setup: [docs/BOT_SETUP.md](https://github.com/ibbybuilds/discli/blob/master/docs/BOT_SETUP.md)\r
\r
## Message Limits\r
\r
- Message content: 2,000 characters max\r
- Embed description: 4,096 characters max\r
- Embed total (all fields combined): 6,000 characters max\r
- Max 10 embeds per message\r
\r
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.\r
\r
## Quick Reference\r
\r
```bash\r
discli init --token \x3Ctoken>           # First-time setup\r
discli server list                    # List servers\r
discli server select \x3Cid>             # Set default server\r
discli server info                    # Server overview\r
discli server set --name "X"         # Change server name\r
discli server set --description "X"  # Set description\r
discli server set --verification medium  # Verification level\r
discli server set --notifications only_mentions  # Notification default\r
discli server icon ./logo.png            # Change server icon\r
\r
discli invite list                    # List all invites\r
discli invite create \x3Cchannel>        # Create invite\r
discli invite create \x3Cch> --max-age 3600 --max-uses 10  # With limits\r
discli invite delete \x3Ccode> --confirm # Delete invite\r
\r
discli channel list                   # List channels\r
discli channel create \x3Cname>          # Create channel (--type, --category, --topic)\r
discli channel delete \x3Cname>          # Delete channel (--confirm required)\r
discli channel rename \x3Cch> \x3Cname>     # Rename channel\r
discli channel topic \x3Cch> \x3Ctext>      # Set topic\r
discli channel move \x3Cch>              # Move to category (--category, --position)\r
discli channel clone \x3Cch>             # Clone channel with same settings\r
discli channel slowmode \x3Cch> \x3Csec>    # Set slowmode (0 to disable)\r
\r
discli role list                      # List roles\r
discli role create \x3Cname>             # Create role (--color, --mentionable)\r
discli role edit \x3Cname> --color "#hex" --name "New"  # Edit role\r
discli role delete \x3Cname>             # Delete role (--confirm required)\r
discli role assign \x3Crole> \x3Cuser>      # Give role to member\r
discli role remove \x3Crole> \x3Cuser>      # Remove role from member\r
\r
discli member list                    # List members\r
discli member info \x3Cuser>             # Member details\r
discli member kick \x3Cuser>             # Kick (--confirm, --reason)\r
discli member ban \x3Cuser>              # Ban (--confirm, --reason)\r
discli member nick \x3Cuser> \x3Cnick>      # Change nickname\r
\r
discli perm view \x3Cchannel>            # View channel permissions\r
discli perm set \x3Cch> \x3Crole>           # Set permissions (--allow, --deny)\r
discli perm lock \x3Cchannel>            # Make read-only for @everyone\r
discli perm unlock \x3Cchannel>          # Remove read-only\r
discli perm list                      # List available permission names\r
\r
discli msg send \x3Cchannel> "text"      # Send message\r
discli msg send \x3Cch> "text" --reply \x3Cid>  # Reply to message\r
discli msg send \x3Cch> "text" --file ./img.png  # Send with file attachment\r
discli msg send \x3Cch> --file ./a.png --file ./b.pdf  # Multiple files\r
discli msg embed \x3Cch> --title "X" --description "Y" --color "#hex"  # Rich embed\r
discli msg embed \x3Cch> --title "X" --image ./local.png  # Embed with local image\r
discli msg embed \x3Cch> --title "X" --field "Name|Value|inline"       # Embed with fields\r
discli msg search \x3Cch> "keyword"      # Search messages by keyword\r
discli msg read \x3Cchannel> -n 10       # Read last N messages\r
discli msg edit \x3Cch> \x3Cmsg-id> "new"   # Edit bot message\r
discli msg delete \x3Cch> \x3Cid> --confirm # Delete message\r
discli msg bulk-delete \x3Cch> -n 10 --confirm  # Delete multiple messages\r
discli msg react \x3Cch> \x3Cid> 👍         # Add reaction\r
discli msg unreact \x3Cch> \x3Cid> 👍       # Remove reaction\r
discli msg pin \x3Cch> \x3Cid>              # Pin message\r
discli msg unpin \x3Cch> \x3Cid>            # Unpin message\r
discli msg pins \x3Cchannel>             # List pinned messages\r
discli msg thread \x3Cch> "Name"         # Create thread\r
discli msg thread \x3Cch> "Name" --message \x3Cid>  # Thread from message\r
\r
discli emoji list                        # List custom emojis\r
discli emoji upload \x3Cname> ./img.png     # Upload custom emoji\r
discli emoji delete \x3Cname> --confirm     # Delete custom emoji\r
\r
discli audit log                         # View recent audit log\r
discli audit log -n 50                   # Last 50 entries\r
discli audit log --type member_kick      # Filter by action type\r
discli audit log --user \x3Cid>             # Filter by who performed action\r
discli audit types                       # List action type names\r
```\r
\r
## Global Flags\r
\r
- `--format \x3Cyaml|json|table|auto>` — output format (default: auto = yaml when piped, table in terminal)\r
- `--server \x3Cid>` — target a specific server instead of default\r
- `-n \x3Ccount>` — limit results on list commands\r
\r
## Exit Codes\r
\r
- `0` — success\r
- `1` — general error\r
- `2` — usage error\r
- `3` — not found\r
- `4` — permission denied\r
\r
## Bot Personality (SOUL.md)\r
\r
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).\r
\r
If no SOUL.md exists yet, ask your human how they want their bot to sound:\r
- What's the bot's name?\r
- What personality? (cheeky, professional, friendly, chaotic, minimal, etc.)\r
- How should it talk? (casual lowercase, formal, emoji-heavy, dry wit, etc.)\r
- Any specific traits or quirks?\r
\r
Then generate a SOUL.md and save it to `~/.discli/SOUL.md`. Use this structure:\r
- **Core Truths**: behavioral principles (how the bot acts)\r
- **Boundaries**: hard limits (what it won't do)\r
- **Vibe**: tone, humor style, emoji preferences, example responses\r
- **Identity**: name, what it is, who made it\r
\r
The bot should feel like a character, not a command runner.\r
\r
## Notes\r
\r
- Channel/role/member names are resolved case-insensitively.\r
- You can use IDs instead of names to avoid ambiguity.\r
- Rate limits: Discord allows ~5 requests/second. Channel renames have a 10-min cooldown per channel.\r
- Config stored in `~/.discli/` (token in `.env`, defaults in `config.json`).\r
- Bot personality stored in `~/.discli/SOUL.md` (optional, see above).\r