Advanced Usage

Take your BotBox workflow to the next level with these advanced features and tips.

Customizing the Project Template

You can add your own files, folders, or Python modules to the generated project.
Just keep your cogs in src/cogs/ and update botbox.conf if you add or remove them manually.

Using Multiple Environments

Set the env field for each cog in botbox.conf (e.g., development, production)
Only cogs matching the current environment will be loaded at runtime

Automating with Scripts

Use the run.sh script for consistent environment setup
Integrate BotBox commands into your own shell scripts or Makefiles
Run any command headless so nothing waits on a prompt

#!/bin/bash
set -e

export BOTBOX_TOKEN="$DISCORD_TOKEN"

botbox create --name MyBot --description "Scaffolded from a script" --author "$USER" --guild "$DISCORD_GUILD" --force
cd MyBot
botbox add Greeter --commands @../cogs/greeter.json
botbox config sync --headless

Generating cogs from a JSON file is the useful part here. Keep your command definitions in version control and regenerate the cog files whenever they change. See Headless Mode.

Extending BotBox Itself

Want to add your own CLI commands or customize the TUI experience?

Check out the utils package in the BotBox source code.
See how Charmbracelet’s Bubble Tea and Huh are used for interactive, beautiful TUI forms and flows.
All core UI/UX logic for forms, prompts, and navigation is handled in this package.
New commands are implemented using Cobra.

More Advanced Tips

Use Doppler for secret management in teams
Use botbox project upgrade to keep legacy projects up to date
Use botbox config set and get for scripting config changes, with --raw on get so you can capture the value directly
Use botbox config --format json to feed your project config into jq or another tool
Set LOG_LEVEL=DEBUG while working on a cog and drop it back to INFO before deploying