View on GitHub

Headless Mode

Every BotBox command can run without the interactive TUI. This makes BotBox usable from scripts, Makefiles, and CI pipelines.

Added in 2.6.0.

How BotBox Decides

A command runs headless when either of these is true:

  • You pass --headless explicitly
  • You pass any value flag, such as --name, --commands, --yes, etc.

--headless is a persistent flag, so it is available on every command.

📝 NOTE
In headless mode, data goes to stdout and diagnostics go to stderr, so output can be piped into other tools without cleaning it up first.

Headless runs also skip the automatic update check, so a slow or unreachable GitHub API never stalls a pipeline.

Creating a Project

botbox create and botbox init share the same flag set.

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

Project flags:

FlagDescription
--nameBot name, can also be given as the first positional argument
--descriptionBot description
--authorBot author, falls back to user.default_user in the global config
--prefixSingle non-alphanumeric command prefix, falls back to defaults.command_prefix, then !
--envenv or doppler, defaults to env
--tokenBot token, used when --env env
--guildGuild ID, used when --env env
--doppler-projectDoppler project name, required when --env doppler
--doppler-envDoppler environment name, used when --env doppler
--licensemit, apache-2.0, gpl-3.0, bsd-3-clause, unlicense, or no-license
--forceOverwrite existing files without prompting

Keeping Your Token Out of Shell History

--token is read from the BOTBOX_TOKEN environment variable when the flag is omitted.

sh
export BOTBOX_TOKEN=YOUR_TOKEN
botbox create --name MyBot --description "A really cool bot" --author "John Doe"
⚠️ WARNING
Passing --token on the command line writes your bot token into your shell history and into CI logs on some runners. Prefer BOTBOX_TOKEN.

Doppler Projects

sh
botbox create --name MyBot --description "A really cool bot" --author "John Doe" \
  --env doppler --doppler-project my-project --doppler-env dev

--doppler-project is required when --env doppler is set.

Initializing In Place

botbox init takes the same flags and writes into the current directory instead of a new one.

sh
botbox init --name MyBot --description "A really cool bot" --author "John Doe"

Adding a Cog

botbox add takes the cog name as a positional 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 also accepts a file path prefixed with @, or - to read from stdin.

sh
botbox add Greeter --commands @commands.json

cat commands.json | botbox add Greeter --commands -

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

sh
botbox add Greeter --headless

Adding a Modal Command

Modal commands take Fields instead of Args, and Type is modal.

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

Between one and five fields, Style is short or paragraph, and ReturnType is forced to None. See Modal Commands.

Removing a Cog

sh
botbox remove Greeter --yes

-y, --yes removes the cog without the TUI and without a confirmation prompt.

Reading Configuration

botbox config prints JSON or YAML instead of the TUI when you pass --format.

sh
botbox config --format json
botbox config -g --format json

botbox config get prints only the value with --raw, which is what you want inside a shell substitution.

sh
BOT_NAME=$(botbox config get bot.name --raw)
echo "Deploying $BOT_NAME"

Syncing

sh
botbox config sync --headless

This prints a plain text report of what changed instead of rendering the TUI.

Full Example Script

sh
#!/bin/bash
set -e

export BOTBOX_TOKEN="$DISCORD_TOKEN"

botbox create --name MyBot --description "Scaffolded in CI" --author "ci" --guild "$DISCORD_GUILD" --force
cd MyBot

botbox add Greeter --commands @../cogs/greeter.json
botbox config sync --headless
botbox config --format json

Next Steps