Quick Start

Ready to build your first Discord bot with BotBox?
Follow these steps to get up and running in minutes.

1. Create a New Project

Open your terminal and run:

botbox create

You’ll be guided through an interactive setup to name your bot, set a prefix, choose your environment variable method, and more.

2. Enter Project Details

You’ll be prompted for:

Bot name
Description
Author
Command prefix (default: !)
Environment variable setup (.env or Doppler)
License type

3. Your Project Structure

After setup, your new project will look like this:

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

💡 TIP

Prefer flags over prompts? Every step here has a headless equivalent, see Headless Mode.

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

4. Add Your Discord Bot Token

If you chose .env during setup, open the generated .env file and add your Discord bot token and guild ID:

env

DISCORD_TOKEN=your-bot-token-here
DISCORD_GUILD=your-guild-id-here

If you chose Doppler, make sure your Doppler project and environment are set up with the correct secrets.

5. Install Python Dependencies

Navigate to your project directory and set up your Python environment:

cd your-bot
python3 -m venv venv
source venv/bin/activate
python3 -m pip install -r requirements.txt

6. Run Your Bot

Start your bot using the provided script:

./run.sh

Or, if you want to use the CLI:

botbox run

7. Add a New Cog

To add a new feature (cog) to your bot:

botbox add

You’ll be prompted to name your cog and define its commands and arguments.