Godotbot

For me, GDScript has been missing ergonomic tools for package management and module importing in a certain way that I'm both accustomed to and like in my experience with other languages, until now! It's your friendly helper robot for managing Godot projects - it's Godotbot!

Godobot is a small ecosystem:

• CLI for managing Godot packages/dependencies/addons
• Module loader for GDScript
• Godot GUI interface plugin for the Godotbot CLI

I ended up spending more effort than I originally expected, but it was fun, it solves a need for me, and helped me learn more about Rust -- I hope it's useful to some of you as well. Happy coding and have fun making games!

The following contents document how to use the CLI and the Botfile. For documentation on how to use the module loader in your source code please see here please see here.

Table of Contents

• Installation
  • From Binary Release
  • From Source
• How to Use
  • Example Botfile
  • Private Repositories
  • Man Page
• Commands
  • Basic Commands
  • Configuration Commands
  • Utility Commands
  • Global Flags
• Some Other Notes
  • Dependency Resolution
  • Performance
  • .gitignore
  • Do commit
• Contributing

---

Installation

From Binary Release (Recommended)

Linux/macOS

# Download for your platform
wget https://github.com/rdgd/bot/releases/download/v0.0.29/bot-linux-amd64
# or
wget https://github.com/rdgd/bot/releases/download/v0.0.29/bot-macos-amd64

# Install
chmod +x bot-*
sudo mv bot-* /usr/local/bin/bot
sudo bot install-completions # registers manpage and autocompletions for popular shells (bash, zsh)

Windows

1. Download bot-windows-amd64.exe
2. Rename to bot.exe
3. Move to a directory in your PATH (e.g., C:\Program Files\bot\)
4. Add to PATH if needed: System Properties → Environment Variables → Path → Add directory

From Source

# Clone and build
git clone https://github.com/your-username/bot
cd bot
cargo build --release

# Install
sudo cp target/release/bot /usr/local/bin/
sudo bot install-completions

How to use

Godotbot is driven by the Botfile in your project.

1. Run command bot init. This will generate a Botfile in your current directory. You may also pass it a project name like bot init my-proj. If you do this, Godotbot will set up a project in a directory of that name.
2. Add your dependencies to the Botfile file manually or use the command bot add ${github-username/repo-name} ${valid-tag}
3. Run command bot install. This installs your dependencies to your project's addons/ folder.

Example Botfile

[package]
name = "my-project"
version = "0.1.0"
enable_plugins = false # Not required. Packages which represent Godot editor plugins are enabled by default.

[deps]
dialogic-godot/dialogic = "v2.0" # Github-username/repo-name = valid-tag
ramokz/phantom-camera = "v0.7.0"
my-addon = { "path": "../my-local-addon" }

Package Sources:

• GitHub: author/project = "version"
• Local path: name = { "path": "../relative/path" }

Package Settings:

• enable_plugins - Automatically enable plugins in project.godot (default: true)
  • Set to false to disable auto-enabling and manage plugins manually

Private Repositories

Bot supports private GitHub repositories using Personal Access Tokens (PAT).

Setup Authentication

Option 1: Config File (Recommended)

# Create a token at https://github.com/settings/tokens with 'repo' scope
bot config set github-token ghp_xxxxxxxxxxxx

# Verify it's set
bot config get github-token
# Output: github-token = ghp_...xxxx (masked)

Option 2: Environment Variable

# Set token for single command
GITHUB_TOKEN=ghp_xxxxxxxxxxxx bot install

# Or export for session
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
bot install

Creating a GitHub Token:

1. Go to https://github.com/settings/tokens
2. Click "Generate new token" → "Generate new token (classic)"
3. Give it a name (e.g., "Bot CLI")
4. Select scope: repo (Full control of private repositories)
5. Generate and copy the token
6. Configure bot: bot config set github-token ghp_YOUR_TOKEN

The token is stored in ~/.bot/config (Unix/macOS) or %USERPROFILE%\.bot\config (Windows). Environment variables take precedence over config file.

Man Page

Running the command bot install-completions installs the manpage, which allows you to:

man bot

---

Commands

Basic Commands

bot init

bot init
# or
bot init my-project # will create the project in a directory of the name provided (my-project)
#or
bot init --godot-version x.x.x

• Creates a new Botfile
• Creates or updates addons/ directory
• Populates addons with Godotbot core plug-in/library
• Creates or updates your project.godot file

Botfile has following structure:

[package]
name = "my-project" # either the name you provided or the name of the current directory by default 
version = "0.1.0"
godot_version = "4.5.1" # Latest stable release is default value, but you can specify your version.

[deps]

bot add <author/project> <version>

Add a dependency to the Botfile (or update existing version).

Arguments:

• <author/project> - GitHub repository in format author/project
• <version> - Git tag version (e.g., v1.0.0, v2.0)

Examples:

bot add dialogic-godot/dialogic v2.0
bot add ramokz/phantom-camera v0.7.0

Behavior:

• Creates Botfile if it doesn't exist
• Updates existing dependency versions

bot install

Download and install all dependencies from the Botfile.

bot install

bot list

Display all dependencies from the Botfile and their installation status.

bot list

Shows whether each package is installed in the addons/ directory.

bot remove <author/project> [--keep]

Remove a dependency from the Botfile.

bot remove dialogic-godot/dialogic
bot remove ramokz/phantom-camera --keep  # Keep addon files

bot verify

Verify all Botfile dependencies exist on GitHub.

bot verify

Checks that each package version exists and can be downloaded. Useful for CI/CD validation.

bot outdated

Check for newer versions of dependencies.

bot outdated

Queries GitHub releases API to find available updates.

bot update [author/project...]

Update dependencies to latest GitHub releases.

bot update                           # Update all packages
bot update dialogic-godot/dialogic   # Update specific package

Fetches latest release tags from GitHub

Configuration Commands

bot config set <key> <value>

Set configuration values.

Supported Keys:

• github-token - Personal Access Token for private repositories

Example:

bot config set github-token ghp_xxxxxxxxxxxx

Config Location:

• Unix/macOS: ~/.bot/config
• Windows: %USERPROFILE%\.bot\config

bot config get <key>

Retrieve configuration values.

Example:

bot config get github-token
# Output: github-token = ghp_...xxxx (masked)

Note: github-token is masked in output, showing only the first and last 4 characters.

Utility Commands

bot upgrade

Upgrade bot to the latest version.

bot upgrade

bot clean

Clear the global package cache.

bot clean

Cache Location:

• Unix/macOS: $HOME/.bot/cache
• Windows: %USERPROFILE%\.bot\cache

Removes the entire cache directory

bot install-completions

Install man page and shell completions.

sudo bot install-completions

After installation, you can access the man page with man bot.

Global Flags

--verbose / -v

Enable verbose logging for detailed operation output.

bot -v install
bot --verbose outdated

--quiet / -q

Suppress all non-error output.

bot -q install
bot --quiet update

--help`

Display help information.

bot --help
# or
bot init --help
# or
bot add --help

Flags must appear before the command name.

---

Some Other Notes

Dependency Resolution

• Automatically installs transitive dependencies if the dependency provides a Botfile.
• Warns when multiple packages require different versions.
• Prioritizes first-resolved version in conflict scenarios. If your project defined it as a dependency, it is always preferred.

Performance

• Downloads packages in paralell.
• Global Godotbot cache avoids re-downloading (~/.bot/cache)
• Made with love in Rust. It's damn fast!

.gitignore

• addons/ Don't commit installed dependencies

Do commit

• Botfile

Contributing

Head over to Discord