CLI 指令

涵蓋每個 discli 指令、子指令、參數與選項的完整參考。

全域選項

這些選項套用於所有指令，且必須在子指令前出現。

選項	環境變數	說明
`--token TEXT`	`DISCORD_BOT_TOKEN`	Discord 機器人權杖
`--json`		以 JSON 格式輸出
`--yes`, `-y`		略過破壞性操作的確認提示
`--profile CHOICE`	`DISCLI_PROFILE`	覆蓋權限設定檔（`full`、`chat`、`readonly`、`moderation`）

message

傳送、列出、編輯與刪除訊息。

message send

傳送訊息到一個頻道。

discli message send <channel> <text> [OPTIONS]

|-------------------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID | | TEXT | 是 | 訊息內容 | | --embed-title TEXT | 否 | 嵌入標題 | | --embed-desc TEXT | 否 | 嵌入描述 | | --embed-color HEX | 否 | 嵌入顏色（例如 5865F2） | | --embed-footer TEXT | 否 | 嵌入頁尾文字 | | --embed-image URL | 否 | 嵌入圖片網址 | | --embed-thumbnail URL | 否 | 嵌入縮圖網址 | | --embed-author TEXT | 否 | 嵌入作者名稱 | | --embed-field TEXT | 否 | 嵌入欄位（可重複，格式為 Name::Value::Inline） | | --file PATH | 否 | 附加檔案（可重複） |

message list

列出最近訊息。

discli message list <channel> [OPTIONS]

參數 / 選項	必填	預設	說明
`CHANNEL`	是		頻道名稱或 ID
`--limit N`	否	10	要抓取的訊息數
`--before DATE`	否		早於日期（YYYY-MM-DD 或 ISO）
`--after DATE`	否		晚於日期（YYYY-MM-DD 或 ISO）

message history

抓取頻道的歷史訊息。

discli message history <channel> [OPTIONS]

參數 / 選項	必填	預設	說明
`CHANNEL`	是		頻道名稱或 ID
`--days N`	否		抓取最近 N 天訊息
`--hours N`	否		抓取最近 N 小時訊息
`--limit N`	否	不限制	最大抓取訊息數

message get

依 ID 取得單則訊息。

discli message get <channel> <message_id>

|----------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID | | MESSAGE_ID | 是 | 訊息雪花 ID |

message edit

編輯一則訊息。

discli message edit <channel> <message_id> <new_text>

|----------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID | | MESSAGE_ID | 是 | 訊息雪花 ID | | NEW_TEXT | 是 | 取代後的內容 |

message delete

刪除一則訊息。需要確認。可加上 --yes 直接略過。

discli message delete <channel> <message_id>

|----------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID | | MESSAGE_ID | 是 | 訊息雪花 ID |

message bulk-delete

一次刪除多則訊息。需要確認。可加上 --yes 直接略過。

discli message bulk-delete <channel> <id1> <id2> ...

|----------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID | | ID1 ID2 ... | 是 | 要刪除的訊息 ID 清單 |

message reply

回覆指定訊息。

discli message reply <channel> <message_id> <text> [OPTIONS]

|-------------------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID | | MESSAGE_ID | 是 | 要回覆的訊息 | | TEXT | 是 | 回覆內容 | | --file PATH | 否 | 附加檔案（可重複） |

message search

依訊息內容搜尋。

discli message search <channel> <query> [OPTIONS]

參數 / 選項	必填	預設	說明
`CHANNEL`	是		頻道名稱或 ID
`QUERY`	是		搜尋字串（不分大小寫）
`--limit N`	否	100	要掃描的訊息數
`--author TEXT`	否		依作者名稱過濾
`--before DATE`	否		早於日期（YYYY-MM-DD 或 ISO）
`--after DATE`	否		晚於日期（YYYY-MM-DD 或 ISO）

dm

傳送與讀取私人訊息。

dm send

傳送私人訊息給使用者。

discli dm send <user> <text> [OPTIONS]

|-------------------|----------|-------------| | USER | 是 | 使用者 ID 或使用者名稱 | | TEXT | 是 | 訊息內容 | | --file PATH | 否 | 附加檔案（可重複） |

dm list

列出與指定使用者最近的私訊。

discli dm list <user> [OPTIONS]

參數 / 選項	必填	預設	說明
`USER`	是		使用者 ID 或使用者名稱
`--limit N`	否	10	要抓取的訊息數

reaction

加入、移除與列出回應。

reaction add

為訊息新增回應。

discli reaction add <channel> <message_id> <emoji>

|----------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID | | MESSAGE_ID | 是 | 訊息雪花 ID | | EMOJI | 是 | Emoji 字元或自訂 emoji 字串 |

reaction remove

移除訊息中的回應。

discli reaction remove <channel> <message_id> <emoji>

|----------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID | | MESSAGE_ID | 是 | 訊息雪花 ID | | EMOJI | 是 | Emoji 字元或自訂 emoji 字串 |

reaction list

列出訊息上的回應。

discli reaction list <channel> <message_id>

|----------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID | | MESSAGE_ID | 是 | 訊息雪花 ID |

reaction users

列出使用特定 emoji 回應的使用者。

discli reaction users <channel> <message_id> <emoji> [OPTIONS]

參數 / 選項	必填	預設	說明
`CHANNEL`	是		頻道名稱或 ID
`MESSAGE_ID`	是		訊息雪花 ID
`EMOJI`	是		Emoji 字元或自訂 emoji 字串
`--limit N`	否	100	要列出的使用者上限

channel

列出、建立、刪除與檢視頻道。

channel list

列出伺服器中的頻道。

discli channel list [OPTIONS]

選項	必填	說明
`--server TEXT`	否	伺服器名稱或 ID （未提供時列出全部伺服器）

channel create

在伺服器中建立頻道。

discli channel create <server> <name> [OPTIONS]

參數 / 選項	必填	預設	說明
`SERVER`	是		伺服器名稱或 ID
`NAME`	是		頻道名稱
`--type CHOICE`	否	`text`	頻道型別：`text`、`voice`、`category`或`forum`
`--topic TEXT`	否		頻道主題

channel delete

刪除頻道。需要確認。可加上 --yes 直接略過。

discli channel delete <channel>

|----------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID |

channel info

顯示頻道詳細資料。

discli channel info <channel>

|----------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID |

channel edit

編輯頻道設定。

discli channel edit <channel> [OPTIONS]

|-------------------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID | | --name TEXT | 否 | 新頻道名稱 | | --topic TEXT | 否 | 新頻道主題 | | --slowmode N | 否 | 慢速模式秒數（0 表示停用） | | --nsfw / --no-nsfw | 否 | 切換 NSFW 設定 |

channel forum-post

在論壇頻道建立討論串。

discli channel forum-post <channel> <title> <content> [OPTIONS]

|-------------------|----------|-------------| | CHANNEL | 是 | 論壇頻道名稱或 ID | | TITLE | 是 | 貼文標題 | | CONTENT | 是 | 貼文內容 | | --file PATH | 否 | 附加檔案（可重複） |

channel set-permissions

設定頻道權限覆寫。

discli channel set-permissions <channel> <target> [OPTIONS]

|-------------------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID | | TARGET | 是 | 身分組或成員名稱/ID | | --allow TEXT | 否 | 可授權的權限（以半形逗號分隔） | | --deny TEXT | 否 | 要封鎖的權限（以半形逗號分隔） | | --target-type CHOICE | 否 | 目標型別：role 或 member（預設 role） |

thread

建立、列出並在討論串中發送訊息。

thread create

從一則訊息建立討論串。

discli thread create <channel> <message_id> <name>

|----------|----------|-------------| | CHANNEL | 是 | 來源頻道名稱或 ID | | MESSAGE_ID | 是 | 作為來源的訊息 ID | | NAME | 是 | 討論串名稱 |

thread list

列出頻道中的進行中討論串。

discli thread list <channel>

|----------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID |

thread send

向討論串發送訊息。

discli thread send <thread> <text> [OPTIONS]

|-------------------|----------|-------------| | THREAD | 是 | 討論串名稱或 ID | | TEXT | 是 | 訊息內容 | | --file PATH | 否 | 附加檔案（可重複） |

thread archive

封存討論串。

discli thread archive <thread>

|----------|----------|-------------| | THREAD | 是 | 討論串名稱或 ID |

thread unarchive

解除封存討論串。

discli thread unarchive <thread>

|----------|----------|-------------| | THREAD | 是 | 討論串名稱或 ID |

thread rename

重新命名討論串。

discli thread rename <thread> <new_name>

|----------|----------|-------------| | THREAD | 是 | 討論串名稱或 ID | | NEW_NAME | 是 | 新討論串名稱 |

thread add-member

新增成員到討論串。

discli thread add-member <thread> <member_id>

|----------|----------|-------------| | THREAD | 是 | 討論串名稱或 ID | | MEMBER_ID | 是 | 成員使用者 ID |

thread remove-member

將成員從討論串移除。

discli thread remove-member <thread> <member_id>

|----------|----------|-------------| | THREAD | 是 | 討論串名稱或 ID | | MEMBER_ID | 是 | 成員使用者 ID |

server

列出並檢視伺服器。

server list

列出機器人所在的伺服器。

discli server list

無參數或選項。

server info

顯示伺服器詳細資料。

discli server info <server>

|----------|----------|-------------| | SERVER | 是 | 伺服器名稱或 ID |

role

管理伺服器身分組。

role list

列出伺服器身分組。

discli role list <server>

|----------|----------|-------------| | SERVER | 是 | 伺服器名稱或 ID |

role create

建立身分組。

discli role create <server> <name> [OPTIONS]

|-------------------|----------|-------------| | SERVER | 是 | 伺服器名稱或 ID | | NAME | 是 | 身分組名稱 | | --color HEX | 否 | 色碼（例如 ff0000） | | --permissions INT | 否 | 權限位元值 |

role delete

刪除身分組。需要確認。可加上 --yes 直接略過。

discli role delete <server> <role>

|----------|----------|-------------| | SERVER | 是 | 伺服器名稱或 ID | | ROLE | 是 | 身分組名稱或 ID |

role assign

將身分組指派給成員。

discli role assign <server> <member> <role>

|----------|----------|-------------| | SERVER | 是 | 伺服器名稱或 ID | | MEMBER | 是 | 成員名稱或 ID | | ROLE | 是 | 身分組名稱或 ID |

role remove

移除成員的身分組。

discli role remove <server> <member> <role>

|----------|----------|-------------| | SERVER | 是 | 伺服器名稱或 ID | | MEMBER | 是 | 成員名稱或 ID | | ROLE | 是 | 身分組名稱或 ID |

role edit

編輯身分組設定。

discli role edit <server> <role> [OPTIONS]

|-------------------|----------|-------------| | SERVER | 是 | 伺服器名稱或 ID | | ROLE | 是 | 身分組名稱或 ID | | --name TEXT | 否 | 新身分組名稱 | | --color HEX | 否 | 色碼（例如 ff0000） | | --hoist / --no-hoist | 否 | 是否在側邊欄個別顯示身分組 | | --mentionable / --no-mentionable | 否 | 是否可被 @ 提及 |

member

列出、檢視、踢出、封鎖與解除封鎖成員。

member list

列出伺服器成員。

discli member list <server> [OPTIONS]

參數 / 選項	必填	預設	說明
`SERVER`	是		伺服器名稱或 ID
`--limit N`	否	50	要列出的成員上限

member info

顯示成員詳細資料。

discli member info <server> <member>

|----------|----------|-------------| | SERVER | 是 | 伺服器名稱或 ID | | MEMBER | 是 | 成員名稱或 ID |

member kick

從伺服器踢除成員。需要確認。可加上 --yes 直接略過。

discli member kick <server> <member> [OPTIONS]

|-------------------|----------|-------------| | SERVER | 是 | 伺服器名稱或 ID | | MEMBER | 是 | 成員名稱或 ID | | --reason TEXT | 否 | 踢出原因 | | --triggered-by TEXT | 否 | 觸發此操作的使用者 ID（供權限檢查） |

member ban

封鎖伺服器成員。需要確認。可加上 --yes 直接略過。

discli member ban <server> <member> [OPTIONS]

|-------------------|----------|-------------| | SERVER | 是 | 伺服器名稱或 ID | | MEMBER | 是 | 成員名稱或 ID | | --reason TEXT | 否 | 封鎖原因 | | --triggered-by TEXT | 否 | 觸發此操作的使用者 ID（供權限檢查） |

member unban

解除伺服器成員封鎖。需要確認。可加上 --yes 直接略過。

discli member unban <server> <member> [OPTIONS]

|-------------------|----------|-------------| | SERVER | 是 | 伺服器名稱或 ID | | MEMBER | 是 | 成員名稱或 ID（使用者名稱或使用者 ID） | | --triggered-by TEXT | 否 | 觸發此操作的使用者 ID（供權限檢查） |

member timeout

對成員進行超時，防止其發送訊息或加入語音。需要確認。可加上 --yes 直接略過。

discli member timeout <server> <member> <duration> [OPTIONS]

|-------------------|----------|-------------| | SERVER | 是 | 伺服器名稱或 ID | | MEMBER | 是 | 成員名稱或 ID | | DURATION | 是 | 超時秒數（0 表示取消超時） | | --reason TEXT | 否 | 超時原因 | | --triggered-by TEXT | 否 | 觸發此操作的使用者 ID（供權限檢查） |

poll

建立與管理投票。

poll create

在頻道建立投票。

discli poll create <channel> <question> <answers...> [OPTIONS]

參數 / 選項	必填	預設	說明
`CHANNEL`	是		頻道名稱或 ID
`QUESTION`	是		投票問題
`ANSWERS`	是		兩個以上投票選項（以空白分隔）
`--duration N`	否	24	投票持續時間（小時）
`--multiple`	否	false	允許多選
`--emoji`, `-e`	否		每個答案對應的 emoji（依序，可重複）

範例：

discli poll create #general "Favorite AI?" Claude Gemini ChatGPT
discli poll create #general "Best?" A B C -e a_emoji -e b_emoji -e c_emoji
discli poll create #general "Vote!" Yes No --multiple -e ok -e x

poll results

檢視投票結果。

discli poll results <channel> <message_id>

|----------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID | | MESSAGE_ID | 是 | 投票訊息雪花 ID |

poll end

提前結束投票。

discli poll end <channel> <message_id>

|----------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID | | MESSAGE_ID | 是 | 投票訊息雪花 ID |

typing

在頻道中顯示輸入指示。

discli typing <channel> [OPTIONS]

參數 / 選項	必填	預設	說明
`CHANNEL`	是		頻道名稱或 ID
`--duration N`	否	5	輸入指示持續秒數

listen

監聽 Discord 即時事件。將事件輸出到 stdout。按 Ctrl+C 停止。

discli listen [OPTIONS]

選項	必填	預設	說明
`--server TEXT`	否		依伺服器名稱或 ID 篩選
`--channel TEXT`	否		依頻道名稱或 ID 篩選
`--events TEXT`	否	all	以半形逗號分隔的事件類型： `messages`, `reactions`, `members`, `edits`, `deletes`, `voice`
`--ignore-bots` / `--include-bots`	否	`--ignore-bots`	忽略機器人訊息

serve

啟動持久化機器人程序並以 JSONL 進行雙向通訊。事件會輸出到 stdout，指令從 stdin 讀取。

discli serve [OPTIONS]

選項	必填	預設	說明
`--server TEXT`	否		依伺服器名稱或 ID 篩選事件
`--channel TEXT`	否		依頻道名稱或 ID 篩選事件
`--events TEXT`	否	all	以半形逗號分隔的事件類型： `messages`, `reactions`, `members`, `edits`, `deletes`, `voice`
`--include-self` / `--no-include-self`	否	`--include-self`	事件中包含機器人自己的訊息
`--slash-commands PATH`	否		JSON 檔案，定義要註冊的 slash 指令
`--status CHOICE`	否	`online`	機器人狀態：`online`、`idle`、`dnd`、`invisible`
`--activity TEXT`	否		活動類型：`playing`、`watching`、`listening`、`competing`
`--activity-text TEXT`	否		活動顯示文字

請參閱 Serve 動作與 Serve 事件以取得完整 JSONL 協定。

webhook

管理頻道 webhook。

webhook list

列出指定頻道的 webhook。

discli webhook list <channel>

|----------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID |

webhook create

為頻道建立 webhook。

discli webhook create <channel> <name>

|----------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID | | NAME | 是 | Webhook 名稱 |

webhook delete

刪除 webhook。需要確認。可加上 --yes 直接略過。

discli webhook delete <channel> <webhook_id>

|----------|----------|-------------| | CHANNEL | 是 | 頻道名稱或 ID | | WEBHOOK_ID | 是 | Webhook 雪花 ID |

event

管理伺服器排程活動。

event list

列出伺服器的排程活動。

discli event list <server>

|----------|----------|-------------| | SERVER | 是 | 伺服器名稱或 ID |

event create

建立排程活動。

discli event create <server> <name> <start_time> [OPTIONS]

|-------------------|----------|-------------| | SERVER | 是 | 伺服器名稱或 ID | | NAME | 是 | 排程活動名稱 | | START_TIME | 是 | 開始時間（ISO 8601 格式） | | --end-time TEXT | 否 | 結束時間（ISO 8601 格式） | | --location TEXT | 否 | 事件地點（外部活動） | | --channel TEXT | 否 | 活動所使用的語音/舞台頻道 | | --description TEXT | 否 | 活動描述 |

event delete

刪除排程活動。需要確認。可加上 --yes 直接略過。

discli event delete <server> <event_id>

|----------|----------|-------------| | SERVER | 是 | 伺服器名稱或 ID | | EVENT_ID | 是 | 活動雪花 ID |

config

管理 discli 設定。設定儲存在 ~/.discli/config.json。

config set

設定一項值。

discli config set <key> <value>

|----------|----------|-------------| | KEY | 是 | 設定鍵（例如 token） | | VALUE | 是 | 設定值 |

config show

顯示目前設定。純文字輸出時 token 值會被截斷。

discli config show

permission

管理指令存取控制的權限設定檔。

permission show

顯示目前權限設定檔，含允許與拒絕的指令模式。

discli permission show

permission set

設定目前權限設定檔。

discli permission set <profile>

|----------|----------|-------------| | PROFILE | 是 | full、chat、readonly、moderation 其中之一 |

permission profiles

列出全部可用的權限設定檔。

discli permission profiles

參閱權限設定檔了解各設定檔內容。

audit

檢視稽核記錄。破壞性操作會記錄到 ~/.discli/audit.log。

audit show

顯示最近的稽核紀錄。

discli audit show [OPTIONS]

選項	必填	預設	說明
`--limit N`	否	20	要顯示的項目數

audit clear

清除稽核記錄。

discli audit clear

doctor

診斷本機安裝：token、語音相依元件、STT/TTS 金鑰、ffmpeg。未安裝的可選相依會以 [--] 呈現，不會直接失敗；僅使用文字功能的使用者可看到更乾淨的雙欄報告。若無錯誤則結束代碼為 0，否則為 1。請參閱語音指南查看輸出範例。

discli doctor [--json]

選項	必填	預設	說明
`--json`	否	false	輸出機器可讀格式

voice

加入語音頻道、使用 STT 轉寫語音、以 TTS 發言並播放音訊。語音子命令需要安裝 voice 額外套件，請執行 pip install 'discord-cli-agent[voice]'（或 uv sync --extra voice）。唯讀查詢（voice status、voice where、voice members）不需安裝 voice 相依。

參閱語音指南取得完整流程。

voice join

加入伺服器語音頻道。進行連線、確認與斷線，為一次性操作。

discli voice join CHANNEL [OPTIONS]

選項	必填	預設	說明
`CHANNEL`	是		語音頻道名稱或 ID
`--server`	否		指定為單一伺服器範圍

voice leave

離開目前語音頻道。

discli voice leave [--server NAME_OR_ID]

voice speak

透過 TTS 合成文字並在目前語音頻道播放。

discli voice speak TEXT [OPTIONS]

選項	必填	預設	說明
`TEXT`	是		要朗讀的文字
`--server`	否		指定為單一伺服器範圍
`--voice`	否	`default`	TTS 聲音名稱（依提供者而定）
`--speed`	否	`1.0`	語速倍率

voice play

透過 ffmpeg 在目前語音頻道播放音訊檔案或網址。

discli voice play SOURCE [OPTIONS]

選項	必填	預設	說明
`SOURCE`	是		檔案路徑或 HTTP(S) 網址
`--server`	否		指定為單一伺服器範圍
`--volume`	否	`1.0`	播放音量（0.0 – 2.0）

voice stop / pause / resume

控制目前播放。這些指令都不需頻道參數，會操作該伺服器目前作用中的連線（或自動偵測唯一連線）。

discli voice stop   [--server NAME_OR_ID]
discli voice pause  [--server NAME_OR_ID]
discli voice resume [--server NAME_OR_ID]

voice listen

監聽目前語音頻道並逐位元輸出每位發言者的最終轉寫結果。

discli voice listen [OPTIONS]

選項	必填	預設	說明
`--server`	否		指定為單一伺服器範圍
`--duration`	否	`0`	在 N 秒後停止（`0` = 直到 Ctrl+C）
`--continuous`	否	false	每次轉寫後維持連線

voice capture

除錯輔助：將每位發言者的 48kHz 立體聲 PCM 寫入 WAV 檔，繞過 STT。在監聽無結果時，確認機器人確實有接收到音訊。

discli voice capture [OPTIONS]

選項	必填	預設	說明
`--server`	否		指定為單一伺服器範圍
`--duration`	否	`10`	擷取秒數
`--output-dir`	否	`~/.discli/debug-capture`	WAV 檔寫入路徑

voice status

列出目前啟用的語音連線。唯讀模式，不需要 voice 額外安裝。

discli voice status

voice where

查詢使用者目前所在的語音頻道。僅可讀。

discli voice where USER [--server NAME_OR_ID]

voice members

列出語音頻道中的成員。僅可讀。

discli voice members CHANNEL [--server NAME_OR_ID]

Last updated: August 2, 2026

7 min read

Edit this page