Token Resolution

discli needs a Discord bot token to authenticate with the Discord API. The token is resolved through a four-level priority chain, giving you flexibility across different environments.

Resolution chain

flowchart TD
    A[discli invoked] --> B{--token flag\nprovided?}
    B -- Yes --> C[Use flag value]
    B -- No --> D{DISCORD_BOT_TOKEN\nenv var set?}
    D -- Yes --> E[Use env var value]
    D -- No --> F{~/.discli/config.json\nhas token?}
    F -- Yes --> G[Use config value]
    F -- No --> H{DISCORD_TOKEN\nenv var set?}
    H -- Yes --> I[Use fallback env var value]
    H -- No --> J[Error: No token\nprovided]

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

Priority order

The first source that provides a non-empty value wins. If none of the sources has a token, discli exits with an error:

Error: No token provided. Use --token, set DISCORD_BOT_TOKEN (or DISCORD_TOKEN), or run: discli config set token YOUR_TOKEN

How it works

Token resolution happens in two stages within cli.py and client.py:

Stage 1 — CLI entry (cli.py): Click’s @click.option("--token", envvar="DISCORD_BOT_TOKEN") handles the first two levels. If --token is passed, Click uses that value. If not, Click checks the DISCORD_BOT_TOKEN environment variable. If neither is set, the token is None and discli falls back to loading from the config file, and finally to DISCORD_TOKEN.

# 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")
        if not token:
            token = os.environ.get("DISCORD_TOKEN")
    ctx.obj["token"] = token

Stage 2 — Client (client.py): Before running the Discord action, resolve_token() verifies that a token was found following the same priority chain. If no token was configured, it raises an error.

def resolve_token(token: str | None, config: dict) -> str:
    if token:
        return token
    config_token = config.get("token")
    if config_token:
        return config_token
    env_token = os.environ.get("DISCORD_TOKEN")
    if env_token:
        return env_token
    raise click.ClickException("No token provided. ...")

Config file format

The config file is stored at ~/.discli/config.json:

{
  "token": "Bot_YOUR_TOKEN_HERE"
}

Manage it with the config command:

# Set your token
discli config set token YOUR_BOT_TOKEN

# View current config
discli config show

The file is created automatically by discli config set. The ~/.discli/ directory is also created if it does not exist.

Why this order

The four-level priority is designed for different usage patterns:

discli config set token YOUR_BOT_TOKEN
# Now every command works without extra flags
discli message send "#general" "Hello"

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

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

# Test with a staging bot
discli --token Bot_STAGING_TOKEN message send "#test" "Staging check"

# Your default config token is unaffected
discli message send "#general" "Still uses config token"

Token security

discli takes several measures to protect your token:

Troubleshooting

Next steps