Token 解析

discli 需要 Discord 機器人 token 才能進行 API 驗證。Token 會依照三層優先順序解析，提供不同環境下的彈性。

解析順序

flowchart TD
    A[啟動 discli] --> B{有提供 --token 旗標？}
    B -- 是 --> C[使用旗標值]
    B -- 否 --> D{已設定 DISCORD_BOT_TOKEN？}
    D -- 是 --> E[使用環境變數值]
    D -- 否 --> F{~/.discli/config.json\n有 token？}
    F -- 是 --> G[使用設定檔值]
    F -- 否 --> H[錯誤：未提供 token]

    style C fill:#059669,color:#fff
    style E fill:#059669,color:#fff
    style G fill:#059669,color:#fff
    style H fill:#dc2626,color:#fff

優先順序

第一個有非空值的來源會被採用。若三個來源皆未提供 token，discli 會直接結束並輸出錯誤：

錯誤：未提供 token。請使用 --token、設定 DISCORD_BOT_TOKEN，或執行：discli config set token YOUR_TOKEN

運作原理

Token 解析在 cli.py 與 client.py 中分兩階段完成：

第一階段（CLI 進入）(cli.py)： Click 的 @click.option("--token", envvar="DISCORD_BOT_TOKEN") 同時處理前兩層。若有傳入 --token，Click 使用該值；若未傳入，則改取 DISCORD_BOT_TOKEN。若都未設定，值為 None，discli 會改由設定檔載入。

# cli.py — main group
@click.option("--token", envvar="DISCORD_BOT_TOKEN", default=None)
def main(ctx, token, ...):
    if token is None:
        config = load_config()
        token = config.get("token")
    ctx.obj["token"] = token

第二階段（Client）(client.py)： 在執行 Discord 行為前，resolve_token() 會確認 token 已存在。若 ctx.obj["token"] 仍為 None，就拋出錯誤。

def resolve_token(token: str | None, config: dict) -> str:
    if token:
        return token
    config_token = config.get("token")
    if config_token:
        return config_token
    raise click.ClickException("未提供 token。")

設定檔格式

設定檔位於 ~/.discli/config.json：

{
  "token": "Bot_YOUR_TOKEN_HERE"
}

透過 config 指令管理：

# 設定 token
discli config set token YOUR_BOT_TOKEN

# 查看目前設定
discli config show

檔案由 discli config set 自動建立；若 ~/.discli/ 目錄不存在也會一併建立。

為何使用此順序

這個三層順序是為了對應不同使用情境設計：

discli config set token YOUR_BOT_TOKEN
# 接著所有指令都可直接使用，不需額外旗標
discli message send "#general" "Hello"

# GitHub Actions 範例
env:
  DISCORD_BOT_TOKEN: ${{ secrets.DISCORD_BOT_TOKEN }}
steps:
  - run: discli message send "#deploys" "Build ${{ github.sha }} deployed"

# Docker 範例
docker run -e DISCORD_BOT_TOKEN=... discli message send "#alerts" "Container started"

# 使用 staging 機器人測試
discli --token Bot_STAGING_TOKEN message send "#test" "Staging check"

# 預設設定檔的 token 不受影響
discli message send "#general" "Still uses config token"

Token 保護

discli 對 token 採用以下保護措施：

疑難排解

後續步驟