View on GitHub

Add Command

The botbox add command lets you create new cogs and commands for your Discord bot interactively.

Usage

sh
botbox add

You’ll be prompted for:

  • Cog name (file/class name)
  • Command type (slash, prefix, or modal)
  • Command name
  • Scope (guild or global)
  • Description
  • Arguments (name, type, description), or fields for a modal command
  • Return type

You can add multiple commands to a single cog in one session.

📝 NOTE
modal is a slash command that opens a Discord popup form with up to five text inputs. Picking it swaps the argument prompts for field prompts. See Modal Commands.
📝 NOTE
Added in 2.7.0. Older BotBox versions only offer slash and prefix.

What Happens?

  • A new Python file is created in src/cogs/ for your cog
  • The cog and its commands are registered in botbox.conf
  • All boilerplate is handled for you

Example

sh
botbox add

Suppose you add a cog called music with a /play command.
BotBox will generate src/cogs/music.py and update your config automatically.

Headless Usage

Pass the cog name as an argument and the commands as JSON through --commands.

sh
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"
  }
]'

--commands accepts three forms:

FormMeaning
'[...]'Inline JSON array
@commands.jsonRead the JSON from a file
-Read the JSON from stdin

To generate an empty cog with no commands, pass --headless on its own.

sh
botbox add Greeter --headless

For a modal command, set "Type": "modal" and give Fields instead of Args.

sh
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"
  }
]'
📝 NOTE
Argument and field names cannot contain -, and the same validation that runs in the TUI runs in headless mode, so a bad payload fails with an error instead of generating a broken cog.

Next Steps