BotBox

---

📖 Table of Contents

• About
• Features
• Installation
• Usage
• Configuration
• Troubleshooting
• Roadmap
• Version History
• License
• Contributors

---

✨ About

Bot Box is your ultimate companion for creating Discord bots with ease. Forget the tedious boilerplate and dive straight into building the unique functionalities that make your bot stand out.

Want to learn more? Check out our new website! Also includes detailed documentation on how to use BotBox!

Built with Go, Cobra, Bubble Tea and Huh, Bot Box offers an intuitive command-line interface to quickly generate Discord bot projects. It champions a cog-based architecture for modularity, simplifies .env management, and provides built-in utilities to automate bot configuration and extension development.

---

🚀 Features

• Headless Mode: Every command can run without the interactive TUI using flags, so Bot Box works in scripts and CI.
• Modal Commands: Generate slash commands that open Discord modals with up to five text inputs, defined interactively or from JSON.
• Multipage Modal Flows: Chain up to ten modal pages with branching rules that route users based on their answers, bridged by Continue buttons since Discord can't chain modals directly.
• Custom Responses: Any command can define its own response messages, and modal flow responses can substitute submitted values with {field} placeholders.
• Built-in Logging: Generated bots come with a ready to use logger with file rotation and console output, configured through LOG_LEVEL and LOG_DIR.
• Dynamic Help Command: Generated bots include a permission aware, paginated /help that reads the live bot state, so it stays accurate after cogs are loaded, unloaded, or reloaded without a restart. Output format is controlled by bot.help_style (compact or detailed).
• Admin Tools: Generated bots ship with /sync, /status, /uptime, and /set-prefix, all locked behind administrator permissions and an OWNER_IDS owner check.
• Docker Support: Turn any Bot Box project into a container with botbox docker init, generating a Dockerfile, docker-compose.yml, and .dockerignore matched to your env or Doppler setup.
• Cog Editing: Modify existing cogs with botbox edit, add, edit, or remove commands interactively or from flags, with automatic file regeneration and backups.
• Slash Command Support: Seamless integration via discord.ext.commands.
• Automated Cog Generation: Generate new cogs with predefined commands and arguments effortlessly.
• Project Initialization: Quick setup with .env and botbox.conf files.
• Dynamic cog maintenance: Used botbox.conf to dynamically load cogs and provide an interface for users to load, reload, and unload cogs as needed.
• Global Configuration Management: Centralized settings stored in $HOME/.config/botbox/config.json for user preferences, update settings, and defaults.
• Automatic Updates: Built-in update checking and automatic updating capabilities to keep your CLI tool current.
• Dual Configuration System: Manage both global CLI settings and local project configurations with intuitive commands.
• Project Upgrade System: Seamlessly upgrade legacy project configurations to the latest schema format.
• Modular Design: Easily extendable and maintainable structure.

---

🛠️ Installation

Bot Box requires Go to be installed on your system.

Prerequisites: Go Installation

It is highly recommended to follow the official Golang documentation for the most up-to-date installation instructions.

Alternatively, you can use webi for a quick installation:

Linux/macOS:

curl -sS https://webi.sh/golang | sh; \
source ~/.config/envman/PATH.env

Windows:

curl.exe https://webi.ms/golang | powershell

Install Bot Box CLI

Once Go is installed, use the following command to install Bot Box:

go install github.com/choice404/botbox/v2@latest

Bot Box will automatically create a global configuration file at $HOME/.config/botbox/config.json when you first run any command. This file stores your CLI preferences, update settings, and default values.

---

💡 Usage

Bot Box provides several commands to help you manage your bot project and CLI configuration.

Project Management

Create a new Bot Box project

botbox create

This command will prompt you to provide project details (like bot name, prefix, etc.) and then generate a new project with initial files.

Initialize a Bot Box project in the current directory

botbox init

Use this command to set up a new Bot Box project in your current working directory.

Add a new cog to the current Bot Box project

botbox add

It is highly recommended to use botbox add to generate new cogs within your projects. While you can manually add cogs, this will incur overhead as you'll need to manually update botbox.conf and potentially main.py.

You'll be prompted to define:

• Cog name
• Command names and descriptions
• Argument names, types, and descriptions
• Return types

The new cog will be saved in the cogs/ directory and automatically registered in botbox.conf.

Remove a cog from the current Bot Box project

botbox remove

You'll be prompted to select a cog to remove. This command will also update botbox.conf accordingly.

Edit an existing cog

botbox edit

Select a cog and then add, edit, or remove its commands through the same forms the add command uses, with existing values prefilled. Applying changes regenerates the cog file from its definition and updates botbox.conf. A .py.bak backup of the previous file is written first, since regeneration does not preserve custom code written inside command bodies.

Headless editing works through flags, which can be combined and apply as replace, then remove, then add:

# Remove a command
botbox edit MyCog --remove-command greet

# Add commands from JSON, same format as botbox add --commands
botbox edit MyCog --add-commands @commands.json

# Replace every command in the cog
botbox edit MyCog --replace-commands @commands.json

# Change the cog environment and skip the backup file
botbox edit MyCog --env production --no-backup

Upgrade project configuration

botbox project upgrade

Upgrade your botbox.conf file to the latest schema format. This command will:

• Parse your existing configuration file
• Analyze your cog files to extract detailed command information
• Create a backup of your original configuration
• Upgrade to the latest schema while preserving all settings

Add Docker files to a project

botbox docker init

Generates a Dockerfile, docker-compose.yml, and .dockerignore in the project root, matched to how the project handles environment variables. Projects using a .env file get an env_file entry in the compose file, Doppler projects get the Doppler CLI in the image and expect DOPPLER_TOKEN in the environment. Use --python to pick the base image version and --force to overwrite existing files. New projects can opt in during creation, either through the prompt or with the --docker flag.

docker compose up -d

The compose file mounts logs/ and botbox.conf, and includes a commented development block that mounts src/ so /reload-cog picks up code changes without rebuilding the image.

Headless Mode

Every command can run without the interactive TUI. Providing any value flag implies headless mode, or pass --headless explicitly. Data goes to stdout and diagnostics go to stderr so output can be piped.

Create or initialize a project headlessly

# Create a new project with flags
botbox create --name MyBot --description "A really cool bot" --author "John Doe" --token YOUR_TOKEN --guild GUILD_ID

# The token can come from the BOTBOX_TOKEN environment variable instead
export BOTBOX_TOKEN=YOUR_TOKEN
botbox create --name MyBot --description "A really cool bot" --author "John Doe"

# Doppler based projects
botbox create --name MyBot --description "A really cool bot" --author "John Doe" --env doppler --doppler-project my-project --doppler-env dev

# Initialize in the current directory with the same flags
botbox init --name MyBot --description "A really cool bot" --author "John Doe"

Use --force to overwrite existing files without prompting. --author and --prefix fall back to user.default_user and defaults.command_prefix from the global config.

Add a cog headlessly

The --commands flag takes a JSON array of commands, either inline, from a file with @path/to/file.json, or from stdin with -.

botbox add Greeter --commands '[
  {
    "Name": "greet",
    "Scope": "guild",
    "Type": "slash",
    "Description": "Greets a user",
    "Args": [
      { "Name": "user", "Type": "discord.Member", "Description": "The user to greet" }
    ],
    "ReturnType": "None"
  }
]'

# Or from a file
botbox add Greeter --commands @commands.json

# A cog with no commands
botbox add Greeter --headless

# A modal command, opens a Discord modal with text inputs when the slash command runs
botbox add Feedback --commands '[
  {
    "Name": "feedback",
    "Scope": "guild",
    "Type": "modal",
    "Description": "Collects user feedback",
    "Fields": [
      { "Name": "subject", "Label": "Subject", "Style": "short", "Required": true, "Placeholder": "Short summary" },
      { "Name": "details", "Label": "Details", "Style": "paragraph", "Required": false, "Placeholder": "" }
    ],
    "ReturnType": "None"
  }
]'

Other headless commands

# Remove a cog without confirmation
botbox remove Greeter --yes

# Print the project or global config as JSON
botbox config --format json
botbox config -g --format json

# Print only a value, useful for scripting
botbox config get bot.name --raw

# Synchronize cogs and print a plain report
botbox config sync --headless

Configuration Management

Bot Box now provides comprehensive configuration management for both global CLI settings and local project settings.

Display configuration

# Display local project configuration (default)
botbox config

# Display local project configuration (explicit)
botbox config -l

# Display global CLI configuration
botbox config -g

List all configuration keys and values

# List local project configuration (default)
botbox config list

# List local project configuration (explicit)
botbox config list -l

# List global CLI configuration
botbox config list -g

Get specific configuration values

# Get local project values (default)
botbox config get bot.name
botbox config get bot.author

# Get local project values (explicit)
botbox config get -l bot.description

# Get global CLI values
botbox config get -g user.default_user
botbox config get -g cli.check_updates

Set configuration values

# Set local project values (default)
botbox config set bot.name "My Awesome Bot"
botbox config set bot.command_prefix "!"

# Set local project values (explicit)
botbox config set -l bot.author "John Doe"

# Set global CLI values
botbox config set -g user.default_user "john_doe"
botbox config set -g cli.check_updates true
botbox config set -g cli.auto_update false

Synchronize cog configuration

botbox config sync

This command synchronizes your botbox.conf file with the actual cog files in your project, ensuring consistency between your configuration and code.

Update Management

Update Bot Box

botbox update

Manually update Bot Box to the latest version. The CLI can also automatically check for updates and update itself based on your global configuration settings.

---

⚙️ Configuration

Bot Box uses a dual configuration system to manage both global CLI settings and local project settings.

Global Configuration ($HOME/.config/botbox/config.json)

The global configuration file stores CLI-wide settings and user preferences. It's automatically created when you first run any Bot Box command. Key settings include:

• CLI Settings: Update checking and auto-update preferences
• User Settings: Default username and GitHub username
• Display Settings: UI preferences like color scheme and scroll behavior
• Default Settings: Default command prefix and auto-git initialization
• Development Settings: Preferred code editor

Example global configuration structure:

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

Available Global Configuration Keys:

• 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.scroll_enabled - Enable/disable scrolling in UI
• display.color_scheme - UI color scheme preference
• defaults.command_prefix - Default bot command prefix
• defaults.auto_git_init - Auto-initialize git repositories
• dev.editor - Preferred code editor

Note: The cli.version and defaults.python_version keys are read-only and managed automatically by Bot Box.

Local Project Configuration (botbox.conf)

This is the central configuration file for your Bot Box project, crucial for dynamically loading, reloading, and unloading cogs via /src/main.py and /src/cogs/cogs.py.

The Bot Box CLI tool automatically keeps botbox.conf synchronized with your project. If you choose to add or remove cogs manually (without the CLI tool), you must manually update botbox.conf or manage cog loading within /src/main.py and /src/cogs/cogs.py.

Available Local Configuration Keys:

• bot.name - Your bot's name
• bot.description - Your bot's description
• bot.command_prefix - Your bot's command prefix
• bot.author - Your name as the bot author
• bot.help_style - How the generated /help command formats its output, compact or detailed. The help cog reads this at runtime so changes apply without restarting the bot
• bot.env_provider - How the project supplies environment variables, env or doppler. Projects created before this key existed report the provider detected from doppler.yaml or .env in the project root

Example botbox.conf structure:

{
  "botbox": {
    "version": "2.5.0"
  },
  "bot": {
    "name": "My Awesome Bot",
    "command_prefix": "!",
    "author": "Austin \"Choice404\" Choi",
    "description": "A really cool bot!",
    "help_style": "compact",
    "env_provider": "env"
  },
  "cogs": [{
    "name": "HelloWorld",
    "file": "helloWorld",
    "env": "development",
    "slash_commands": [
      {
        "Name": "hello",
        "Scope": "guild",
        "Type": "slash",
        "Description": "HelloWorld!",
        "Args": [],
        "ReturnType": "None"
      }
    ],
    "prefix_commands": []
  }]
}

Configuration Schema Upgrades

Bot Box automatically handles configuration schema upgrades. If you have an older project with a legacy botbox.conf format, use:

botbox project upgrade

This will:

1. Backup your original config - Creates botbox.conf.backup
2. Parse cog files - Extracts detailed command information from your Python files
3. Upgrade schema - Converts legacy string arrays to modern CommandInfo objects
4. Preserve settings - Maintains all your existing bot configuration
5. Add missing fields - Ensures compatibility with the latest Bot Box version

Legacy vs Modern Format:

Legacy format (pre-2.5.0):

{
  "cogs": [{
    "name": "MyCog",
    "file": "mycog",
    "slash_commands": ["command1", "command2"],
    "prefix_commands": ["old_command"]
  }]
}

Modern format (2.5.0+):

{
  "cogs": [{
    "name": "MyCog",
    "file": "mycog",
    "slash_commands": [
      {
        "Name": "command1",
        "Type": "slash",
        "Scope": "guild",
        "Description": "Command description",
        "Args": [...],
        "ReturnType": "None"
      }
    ],
    "prefix_commands": [...]
  }]
}

---

🐛 Troubleshooting

• Missing botbox.conf? Run botbox init in your project directory to generate it.
• Missing global config? The global configuration file will be automatically created when you run any Bot Box command.
• Legacy config format? Run botbox project upgrade to upgrade your configuration to the latest schema.
• Cogs not loading?
  • Verify cog names in botbox.conf match the actual file names in the cogs/ directory.
  • Ensure the cog files exist.
  • Run botbox config sync to synchronize your configuration with your cog files.
• Token errors? Make sure your .env file is present in the project root and contains DISCORD_BOT_TOKEN=YOUR_TOKEN_HERE.
• Update issues? If automatic updates fail, try running botbox update manually.
• Configuration issues? Use botbox config list to view all current settings, or botbox config list -g for global settings.
• Panic or crashes? Ensure you're running the latest version with botbox update, and check that your project structure is valid.

---

🛣️ Roadmap (TODO)

• Expand botbox.conf to include:
  • More details about each command provided via botbox add.
  • Expected bot responses.
• Global configuration management system
• Automatic update checking and updating
• Project configuration upgrade system
• Add a proper changelog
• New commands:
  • botbox edit command for modifying existing cogs/commands.
  • botbox project update for migrating between major versions.
• Advanced dynamic bot building:
  • Create cogs containing "blocks" that can be dynamically added and connected for complex functionality through BotBox.
• Enhanced project templates and scaffolding options.

---

📜 Version History

• 2.11.0 Added the botbox edit command for modifying existing cogs, interactively with prefilled forms or through flags, with automatic cog file regeneration and .py.bak backups. Fixed prefix command argument descriptions being lost during config sync and prefix command scope drifting between guild and global
• 2.10.0 Added multipage modal flows. Modal commands can now chain up to ten pages with branch rules that route users based on submitted values, with per user session state and Continue button bridges between pages. Added custom response messages for all command types with {field} placeholder substitution in flow responses. Both available in the TUI and headless mode with full config sync round trip through an embedded flow definition
• 2.9.0 Added Docker support. botbox docker init generates a Dockerfile, docker-compose.yml, and .dockerignore for any project, new projects can opt in at creation with the --docker flag or the new prompt, and the files adapt to .env or Doppler projects through the new bot.env_provider config key
• 2.8.0 Generated bots now include a dynamic /help command that filters by user permissions, paginates with buttons, reflects cog reloads without a restart, and formats output based on the new bot.help_style config key. Added an admin cog with /sync, /status, /uptime, and /set-prefix behind administrator permissions and an OWNER_IDS owner check. Fixed guild scoped commands being synced globally and cog reloads never re-registering commands
• 2.7.0 Added modal commands, a new command type that generates slash commands opening Discord modals with up to five text inputs, available in the TUI and headless mode with full config sync support. Generated bots now include a logger with file rotation under src/utils/logger.py, LOG_LEVEL and LOG_DIR in the .env, and all generated prints replaced with logger calls
• 2.6.3 Moved all generated file templates out of Go strings into embedded template files with byte identical output. Generated projects now include requirements.txt and a .gitignore. Fixed a crash when the global config fails to load, config sync wiping the cog list when parsing finds nothing, non atomic botbox.conf writes, guild commands being misread as global during sync, and several cog parser bugs. Added parser and config tests
• 2.6.2 Re-release of 2.6.0. The Go module proxy had permanently cached old deleted tags for 2.6.0 and 2.6.1, so installing those versions through go install would fetch stale code
• 2.6.0 Added headless mode so every command can run without the TUI using flags, with clean stdout for scripting. Added a release workflow so new versions are published on GitHub automatically. The update command now verifies the installed binary reports the expected version and warns about PATH conflicts. Extracted form validation into shared validators and added the first unit tests
• 2.5.4 Fixed the bot name being overwritten with the absolute path during create, ignored project creation errors in create and init, and a mismatch between the generated cog file name and the file entry in botbox.conf. Unified the guild env var to DISCORD_GUILD in all generated code and added validation to the cog name argument
• 2.5.3 Fixed issues with project and cog generation. Getting guild info and setting guild scope for slash commands. Added input validation to argument forms to prevent "-" in argument names
• 2.5.2 Fixed a bit with the huh/tea display since long Huh.Groups won't display everything properly. Updated copyright and licenses in each file and updated command descriptions
• 2.5.1 Made the final view in the custom tea/huh form manager scrollable (This is enabled regardless of scroll_enabled status in the global config for long content)
• 2.5.0: Added global CLI configuration system, comprehensive config management commands (botbox config set/get/list with -l/-g flags), automatic update checking and updating capabilities, project configuration upgrade system (botbox project upgrade), and improved configuration synchronization.
• 2.4.1: Updated the cli to use the alt screen buffer through Bubble Tea
• 2.4.0: Wrapped all the Huh forms in Tea for more complex functionality and smoother UX. Updated configuration to be more detailed and added more functionality for development.
• 2.3.2: Updated the add command so that the confirmation for command information is displayed properly
• 2.3.1: Fixed up some small stuff in the file generation here and there, version numbering, etc.
• 2.3.0: Added remove command; updated botbox.conf schema; improved prefix command generation support.
• 2.2.6: Fixed add command bug; added MIT license to generated files; updated project template.
• 2.2.4: Improved README.md generation; token input is now hidden.
• 2.2.0: Configuration transitioned to botbox.conf; add command modified.
• 2.1.0: Fixed issues with setting prefixes, license creation; added flags to config command.
• 2.0.4: Updated README.md with installation instructions and v2 imports.
• 2.0.3: Enforced single non-alphanumeric character custom prefixes in CLI form.
• 2.0.2: Brew release via taps; updated imports to use GitHub paths.
• 2.0.1: GitHub releases implemented using goreleaser.
• 2.0.0: Major refactor of the project in Go (Python scrapped for CLI core).
• 1.0.0: Initial version with basic boilerplate generation for cogs and main file.

(Minor patch versions between major/minor releases are omitted for brevity)

---

⚖️ License

This project is licensed under the MIT License, © 2025 Austin "Choice404" Choi.

---

🤝 Contributors

• Austin Choi — Original author and maintainer