Configuration

discli uses a layered configuration system for authentication and a profile-based system for access control. This page covers how to set up your bot token, manage configuration, and use permission profiles.

Bot token

Your Discord bot token is the only required configuration. discli resolves the token using the following priority order:

This means a --token flag always wins, followed by the environment variable, followed by the saved config file. Use whichever method fits your workflow.

Option 1: Config file (recommended for local use)

Store the token persistently so you do not have to provide it every time:

discli config set token YOUR_BOT_TOKEN

Set token.

This writes to ~/.discli/config.json:

{
  "token": "YOUR_BOT_TOKEN"
}

chmod 600 ~/.discli/config.json

Option 2: Environment variable (recommended for CI/containers)

Set the DISCORD_BOT_TOKEN environment variable:

export DISCORD_BOT_TOKEN=your_token

$env:DISCORD_BOT_TOKEN = "your_token"

[System.Environment]::SetEnvironmentVariable("DISCORD_BOT_TOKEN", "your_token", "User")

docker run -e DISCORD_BOT_TOKEN=your_token my-agent

env:
  DISCORD_BOT_TOKEN: ${{ secrets.DISCORD_BOT_TOKEN }}

Option 3: Per-command flag

Pass the token directly for one-off commands:

discli --token YOUR_BOT_TOKEN server list

Viewing current configuration

Check what configuration is currently set:

discli config show

token: your-bot-token

The token value is truncated for security. For the full JSON representation:

discli --json config show

{
  "token": "your-bot-token-here"
}

Permission profiles

Permission profiles control which commands your bot (or agent) is allowed to run. This is especially useful when giving an AI agent access to discli — you can restrict it to a safe subset of operations.

Available profiles

Setting the active profile

There are three ways to set the permission profile, with the same priority pattern as tokens:

Persistently (saved to disk):

discli permission set chat

Permission profile set to: chat (Messages, reactions, threads, typing only)

This writes the active profile to ~/.discli/permissions.json.

Per-command (flag):

discli --profile readonly message list "#general"

The --profile flag overrides the saved profile for that single invocation.

Via environment variable:

export DISCLI_PROFILE=readonly

This takes priority over the saved profile but is overridden by the --profile flag.

Viewing the active profile

discli permission show

Active profile: chat
Description: Messages, reactions, threads, typing only
Allowed: message, reaction, thread, typing, dm, listen, serve, config, server
Denied: member kick, member ban, member unban, channel delete, role delete, role create, channel create

Listing all profiles

discli permission profiles

  full: Full access to all commands
  chat: Messages, reactions, threads, typing only
  readonly: Read-only: list, info, get, search, listen
  moderation: Full access including moderation

Destructive action safeguards

Certain commands are considered destructive and require confirmation before execution:

• member kick
• member ban
• member unban
• channel delete
• message delete
• role delete

When you run a destructive command, discli prompts for confirmation:

⚠ Destructive action: member kick (user: Alice). Continue? [y/N]

To skip the prompt (useful in scripts and automation), pass the --yes or -y flag:

discli --yes member kick "My Server" @spammer

Audit log

discli records every command execution to an audit log at ~/.discli/audit.log. This is useful for tracking what actions an agent has taken.

# View recent audit entries
discli audit show --limit 10

# JSON output
discli --json audit show --limit 5

# Clear the log
discli audit clear

Configuration file reference

~/.discli/config.json

{
  "token": "YOUR_BOT_TOKEN"
}

~/.discli/permissions.json

{
  "active_profile": "chat",
  "profiles": {}
}

The profiles key can hold custom profile definitions, though the four built-in profiles cover most use cases.

~/.discli/audit.log

A newline-delimited JSON file where each line is an audit entry:

{"timestamp": "2026-03-15T10:32:00+00:00", "command": "message send", "args": {"channel": "general", "content": "Hello"}, "result": "ok", "user": ""}

Next steps