Config Schema Reference
A detailed reference for all configuration keys in BotBox.
Global Config ($HOME/.config/botbox/config.json)
| Key | Type | Description |
|---|---|---|
cli.version | string | BotBox CLI version (auto-managed) |
cli.check_updates | boolean | Enable/disable update notifications |
cli.auto_update | boolean | Enable/disable automatic updates |
user.default_user | string | Default username |
user.github_username | string | GitHub username |
display.scroll_enabled | boolean | Enable/disable scrolling in UI |
display.color_scheme | string | UI color scheme (default, dark, ubuntu) |
defaults.command_prefix | string | Default bot command prefix |
defaults.python_version | string | Default Python version |
defaults.auto_git_init | boolean | Auto-initialize git repositories |
dev.editor | string | Preferred code editor |
Local Project Config (botbox.conf)
| Key | Type | Description |
|---|---|---|
botbox.version | string | Project config version |
bot.name | string | Bot’s name |
bot.description | string | Description |
bot.command_prefix | string | Command prefix |
bot.author | string | Author name |
cogs | array | List of cog objects (see below) |
Cog Object:
| Key | Type | Description |
|---|---|---|
name | string | Cog class name |
file | string | Python file name (without .py) |
env | string | Environment (development, production) |
slash_commands | array | List of slash command objects |
prefix_commands | array | List of prefix command objects |
Command Object:
| Key | Type | Description |
|---|---|---|
Name | string | Command name |
Type | string | slash, prefix, or modal |
Scope | string | guild or global |
Description | string | Command description. For a modal this also becomes the modal title, truncated to 45 characters |
Args | array | List of argument objects. Must be empty for a modal command |
Fields | array | List of field objects. Modal commands only, 1 to 5 entries |
ReturnType | string | Return type (str, int, None, etc.). Always None for a modal |
📝 NOTE
Modal commands are app commands, so they are stored in the
slash_commands array alongside regular slash commands rather than in a list of their own.Argument Object:
| Key | Type | Description |
|---|---|---|
Name | string | Argument name |
Type | string | Argument type (str, int, etc.) |
Description | string | Argument description |
Field Object (modal commands, 2.7.0+):
| Key | Type | Description |
|---|---|---|
Name | string | Python attribute name. No spaces or dashes, unique within the command |
Label | string | Label shown in Discord, at most 45 characters |
Style | string | short or paragraph |
Required | boolean | Whether Discord requires a value |
Placeholder | string | Optional hint text, skipped when empty |
Environment Variables
| Variable | Type | Description |
|---|---|---|
| DISCORD_TOKEN | string | Your bot’s token (required) |
| DISCORD_GUILD | string | Your Discord server (guild) ID (required for guild commands) |
| ENVIRONMENTS | string | Comma-separated list of environments (e.g., development,production). Controls which cogs are loaded based on their env field. (required) |
| LOG_LEVEL | string | Log level for src/utils/logger.py (DEBUG, INFO, WARNING, ERROR, CRITICAL). Defaults to INFO |
| LOG_DIR | string | Directory for bot.log, created if missing. Defaults to logs |
| BOTBOX_TOKEN | string | Read by the BotBox CLI, not by your bot. Supplies the token to botbox create and botbox init in headless mode |
Global Flags
| Flag | Description |
|---|---|
--headless | Run without the TUI. Implied by any value flag |
-h, --help | Help for the command |
--version | Print the installed BotBox version |
📝 NOTE
cli.version and defaults.python_version are managed by BotBox and cannot be set with botbox config set.For more examples, see Configuration.