discli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

discli — Discord Server Management CLI

discli — Discord 服务器管理 CLI

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

从终端控制 Discord 服务器，同时支持普通用户和 AI Agent 使用。

Agent Defaults

Agent 默认配置

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.

输出格式自动检测：管道传输（供 Agent 使用）时输出 YAML，终端运行（供人类使用）时输出表格。
YAML 是 Agent 优先使用的格式，Token 消耗量比 JSON 低 5 倍。
使用
```
-n
```
参数限制结果数量，降低 Token 消耗。
使用
```
--format yaml
```
强制输出结构化内容，需要严格 JSON 格式时使用
```
--format json
```
。
执行创建/重命名/权限相关命令时使用
```
--dry-run
```
可预览变更效果。
破坏性命令（删除、踢出、封禁）需要添加
```
--confirm
```
参数，不会二次提示确认。
输出结构可查看 SCHEMA.md 文件。

Install / Update

安装 / 更新

bash

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:

powershell

[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

bash

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

如果尚未安装 discli，请先完成安装再运行任何命令。

Windows 用户：优先使用 Git Bash 而非 PowerShell。Git Bash 默认可正确处理 UTF-8 编码、引号和特殊字符。PowerShell 存在编码问题（表情符号乱码）、引号问题（

、

等特殊字符会导致消息异常），以及长文本的参数展开问题。

如果必须使用 PowerShell，请在会话启动时运行以下命令：

powershell

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

同时消息内容请使用单引号包裹，避免特殊字符被展开。首次配置：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.

消息内容上限：2,000 字符
嵌入内容描述上限：4,096 字符
嵌入内容总长度（所有字段合计）上限：6,000 字符
单条消息最多包含 10 个嵌入内容

如果消息超过 2,000 字符，请拆分为多次

msg send

调用发送。更长内容可使用带 --description 参数的

msg embed

命令（最高支持 4,096 字符），禁止静默截断内容。

Quick Reference

快速参考

bash

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

bash

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

```
--format <yaml|json|table|auto>
```
— 输出格式（默认：auto = 管道传输时为 yaml，终端运行时为 table）
```
--server <id>
```
— 指定目标服务器，不使用默认服务器
```
-n <count>
```
— 限制列表命令返回的结果数量

Exit Codes

退出码

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

```
0
```
— 执行成功
```
1
```
— 通用错误
```
2
```
— 使用方式错误
```
3
```
— 资源未找到
```
4
```
— 权限不足

Bot Personality (SOUL.md)

机器人个性设置（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.

当作为机器人发送消息、添加反应或进行交互时，先检查

~/.discli/SOUL.md

路径下是否存在

SOUL.md

文件。如果存在，请先读取该文件，所有机器人交互（消息、回复、反应、嵌入内容）都要符合设定的人设。

如果还没有 SOUL.md 文件，可询问使用者希望机器人的风格：

机器人的名称是什么？
想要什么性格？（调皮搞怪、专业严谨、友好亲切、跳脱 chaotic、极简风等）
说话风格是怎样的？（随意小写、正式规范、大量用表情、冷幽默等）
有没有特定的特征或小习惯？

然后生成 SOUL.md 并保存到

~/.discli/SOUL.md

，使用以下结构：

核心原则：行为准则（机器人的行事方式）
边界：硬性限制（机器人不会做的事）
风格：语气、幽默风格、表情偏好、回复示例
身份：名称、定位、开发者

机器人应该像一个真实的角色，而不是冷冰冰的命令执行器。

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

频道/角色/成员名称不区分大小写解析。
可使用 ID 代替名称避免歧义。
速率限制：Discord 允许约 5 次请求/秒。频道重命名操作每个频道有 10 分钟冷却时间。
配置存储在
```
~/.discli/
```
目录下（token 存放在
```
.env
```
，默认配置存放在
```
config.json
```
）。
机器人个性配置存储在
```
~/.discli/SOUL.md
```
（可选，见上文说明）。