Configuration

BotBox uses a dual configuration system:

• Global CLI configuration (applies to all projects)
• Local project configuration (per-bot settings)

Global Configuration

The global config file is created automatically at:

• Linux/macOS: $HOME/.config/botbox/config.json
• Windows: %USERPROFILE%\.config\botbox\config.json

This file stores CLI-wide preferences, update settings, and user defaults.

Example:

{
  "cli": {
    "version": "2.7.0",
    "check_updates": true,
    "auto_update": false
  },
  "user": {
    "default_user": "your_username",
    "github_username": "your_github"
  },
  "display": {
    "scroll_enabled": true,
    "color_scheme": "default"
  },
  "defaults": {
    "command_prefix": "!",
    "python_version": "3.11",
    "auto_git_init": true
  },
  "dev": {
    "editor": "code"
  }
}

Key fields:

• cli.check_updates – Enable/disable update notifications
• cli.auto_update – Enable/disable automatic updates
• user.default_user – Your default username
• user.github_username – Your GitHub username
• display.color_scheme – UI color scheme
• defaults.command_prefix – Default bot command prefix
• dev.editor – Preferred code editor

Local Project Configuration

Each project has a botbox.conf file in its root directory.
This controls your bot’s metadata and which cogs are loaded.

Example:

{
  "botbox": {
    "version": "2.7.0"
  },
  "bot": {
    "name": "My Awesome Bot",
    "command_prefix": "!",
    "author": "Your Name",
    "description": "A really cool bot!"
  },
  "cogs": [
    {
      "name": "HelloWorld",
      "file": "helloWorld",
      "env": "development",
      "slash_commands": [
        {
          "Name": "hello",
          "Scope": "guild",
          "Type": "slash",
          "Description": "Bot responds with world",
          "Args": [],
          "ReturnType": "None"
        }
      ],
      "prefix_commands": []
    }
  ]
}

Key differences:

• 2.5.0+:

  • slash_commands and prefix_commands are arrays of detailed command objects (with name, type, description, args, etc.)
• 2.4.0 and earlier:

  • slash_commands and prefix_commands are arrays of command names (strings only)

Key fields:

• bot.name – Bot’s name
• bot.description – Description
• bot.command_prefix – Command prefix
• bot.author – Author name
• cogs – List of cogs and their commands

Editing Configuration

You can manage config via the CLI:

• Show config:

botbox config
botbox config -g   # global

• List all keys/values:

botbox config list
botbox config list -g

• Get/set a value:

botbox config get bot.name
botbox config set bot.name "New Name"
botbox config get -g user.default_user
botbox config set -g user.default_user "newuser"

• Print config for a script:

botbox config --format json
botbox config get bot.name --raw

Syncing and Upgrading

• Sync config with cogs:

botbox config sync

• Upgrade old config schemas:

botbox project upgrade

Cog Loading and Environments

Each cog in botbox.conf has an env field (e.g., "env": "development" or "env": "production").

At runtime, BotBox checks the ENVIRONMENTS environment variable (comma-separated list).
A cog is loaded if its env value matches any value in ENVIRONMENTS.

Example:

• If ENVIRONMENTS=development,production, all cogs with env set to either value will be loaded.
• If ENVIRONMENTS=production, only cogs with env: "production" will be loaded.

Next Steps

• Cogs Overview
• Environment Variables
• Troubleshooting