View on GitHub

Create Command

The botbox create command scaffolds a new BotBox project in a new directory with a complete project structure and initial files.

Usage

sh
botbox create [project-name]

You'll be guided through an interactive setup to configure your new project.

Interactive Prompts

You'll be prompted for:

  • Bot name (max 20 characters, must start with alphanumeric, no spaces or special characters)
  • Bot description (max 100 characters)
  • Author name
  • Command prefix (a single non-alphanumeric character, e.g., !)
  • Environment variable setup (.env, Doppler, or none)
  • License type (fetched from GitHub's license API)

What Gets Generated

plaintext
your-bot/
├── README.md
├── botbox.conf
├── requirements.txt
├── run.sh
├── .env (or doppler.yaml)
├── .gitignore
├── LICENSE
├── src/
│   ├── main.py
│   ├── cogs/
│   │   ├── __init__.py
│   │   ├── helloWorld.py
│   │   └── cogs.py
│   └── utils/
│       ├── __init__.py
│       └── logger.py
  • botbox.conf — Project configuration with bot metadata and cog definitions
  • requirements.txt — Python dependencies (discord.py, python-dotenv)
  • run.sh — Script to run your bot (standard or Doppler version)
  • .env or doppler.yaml — Environment variable configuration
  • .gitignore — Ignores logs/, .env, __pycache__/, *.pyc, and venv/
  • src/main.py — Main entry point with cog loading logic
  • src/cogs/helloWorld.py — Example cog with a /hello slash command
  • src/cogs/cogs.py — Cog management commands (reload, list, load, unload)
  • src/utils/logger.py — Logging setup shared by the bot and every cog
  • LICENSE — Your chosen license (optional)

Example

sh
botbox create my-bot

This creates a my-bot/ directory with the full project structure, ready for you to add your Discord bot token and start developing.

Headless Usage

Pass any of the project flags and create skips the TUI entirely.

sh
botbox create --name MyBot --description "A really cool bot" --author "John Doe" --token YOUR_TOKEN --guild GUILD_ID

Flags:

  • --name, --description, --author, --prefix
  • --env (env or doppler), --token, --guild
  • --doppler-project, --doppler-env
  • --license (mit, apache-2.0, gpl-3.0, bsd-3-clause, unlicense, no-license)
  • --force to overwrite existing files without prompting

--author falls back to user.default_user and --prefix falls back to defaults.command_prefix from your global config. The token can come from BOTBOX_TOKEN instead of --token.

Full details in Headless Mode.

Next Steps