CLI Command Reference

A complete list of BotBox CLI commands and their options.

Global Flags

Available on every command.

• --headless — Run without the interactive TUI. Passing any value flag implies this. See Headless Mode.
• -h, --help — Help for the command
• --version — Print the installed BotBox version

Project Management

• Create a new project:

  sh

  botbox create [project-name]

• Initialize in current directory:

  sh

  botbox init

  Flags for create and init:

  • --name — Bot name, can also be the first positional argument on create
  • --description — Bot description
  • --author — Bot author, defaults to user.default_user from the global config
  • --prefix — Single non-alphanumeric command prefix, defaults to defaults.command_prefix
  • --env — env or doppler (default env)
  • --token — Bot token, or set BOTBOX_TOKEN instead
  • --guild — Guild ID, used with --env env
  • --doppler-project — Doppler project, required with --env doppler
  • --doppler-env — Doppler environment, used with --env doppler
  • --license — mit, apache-2.0, gpl-3.0, bsd-3-clause, unlicense, no-license (default mit)
  • --force — Overwrite existing files without prompting

Cog Management

• Add a cog:

  sh

  botbox add [cog-name]

  Flags for add:

  • --commands — JSON array of commands to generate. Accepts inline JSON, @path/to/file.json, or - for stdin

  Commands are slash, prefix, or modal. Modal commands take a Fields array instead of Args, see Modal Commands.

• Remove a cog:

  sh

  botbox remove [cog-name]

  Flags for remove:

  • -y, --yes — Remove without the interactive TUI or confirmation

Configuration

• Show config:

  sh

  botbox config
  botbox config -g

• Display config (alternative):

  sh

  botbox config display
  botbox config display -g

  Flags for config and config display:

  • -g, --global — Show global CLI configuration
  • -l, --local — Show local project configuration (default)
  • -f, --format — Output format (default, json, yaml)
  • -k, --keys-only — Show only configuration keys

• List keys/values:

  sh

  botbox config list
  botbox config list -g

  Flags for config list:

  • -g, --global — Target global configuration
  • -l, --local — Target local configuration (default)

• Get/set a value:

  sh

  botbox config get bot.name
  botbox config get bot.name --raw
  botbox config get -g user.default_user
  botbox config set bot.name "New Name"
  botbox config set -g cli.auto_update true

  Flags for config get and config set:

  • -g, --global — Target global configuration
  • -l, --local — Target local configuration (default)
  • --raw — (get only) Print only the value, useful for scripting

• Sync config:

  sh

  botbox config sync
  botbox config sync --headless

  --headless prints a plain text report instead of rendering the TUI.

Project Upgrades

• Upgrade config schema:

  sh

  botbox project upgrade

Updates

• Update BotBox:

  sh

  botbox update

  Only works if BotBox was installed with go install. Homebrew installs update with brew upgrade botbox.

Running Your Bot

• Run your bot:

  sh

  botbox run

For more details on each command, use --help:

botbox <command> --help