GDAM is the Godot Addon Manager.
Use it to install, link, remove, and publish Godot addons from GitHub release assets through a small CLI and the public registry at gdam.dev.
macOS and Linux:
curl -fsSL https://raw.githubusercontent.com/aviorstudio/gdam/main/scripts/install_cli.sh | shInstall a specific version:
curl -fsSL https://raw.githubusercontent.com/aviorstudio/gdam/main/scripts/install_cli.sh | VERSION=0.0.5 shWindows builds are available from GitHub Releases.
If you have the Go toolchain, install it from the module path instead:
go install github.com/aviorstudio/gdam@latestOr run it without installing anything:
go run github.com/aviorstudio/gdam@latest --versionReplace @latest with a release tag to pin a version. This route compiles from source; the installer script and the release archives ship prebuilt binaries.
From a Godot project:
gdam init
gdam add @username/addon
gdam installInstall an exact, case-sensitive GitHub Release tag:
gdam add @username/addon@Release-1Without a tag, the registry selects the newest stable (non-prerelease) Release.
Exact tags may select prereleases. Tags are opaque: v1.2.3 and 1.2.3 are
different, and hash-looking text is accepted only when it names a registered
GitHub Release. Tags may contain Git ref characters, including /, as long as
the package specification remains unambiguous (tags cannot contain @).
Remove an addon:
gdam remove @username/addonLink a local addon while developing it:
gdam link @username/addon /path/to/addon
gdam unlink @username/addonCheck your installed CLI version:
gdam --versionIf you hit GitHub rate limits while installing addons, set GITHUB_TOKEN.
| Variable | Purpose |
|---|---|
GDAM_SECRET_KEY | Secret key used by gdam publish in CI |
GDAM_API_URL | Registry API base url, defaults to https://api.gdam.dev |
GITHUB_TOKEN | Optional GitHub token to avoid rate limits when downloading |
Set GDAM_API_URL to run the CLI against a local registry while developing it.
The CLI ships no credentials of its own: reads are public, and publishing is
authenticated with your secret key.
gdam init creates a gdam.json file in a Godot project. Each registered
dependency stores its exact Release tag in a tag field. Old manifests with a
version field are intentionally unsupported and must be recreated with
gdam add @owner/addon@<exact-tag>; GDAM never rewrites them automatically.
gdam add, gdam remove, and gdam install keep the manifest in sync with
installed addons under res://addons/.
Local development links are tracked separately with gdam.link.json, so a project can use an unpublished local addon without changing the published dependency manifest.
Registry releases are installed from GitHub Release assets. Publish one exact GitHub Release tag and, optionally, an asset selector. There is no separate semantic package version.
The asset name can be anything the publisher chooses. That ZIP should contain the addon files at the archive root, including plugin.cfg. GDAM installs the asset into its local convention, such as res://addons/@username_addon/, regardless of the asset filename.
For CI publishing, create a secret key from the owner settings page, store it as GDAM_SECRET_KEY, and publish releases with:
gdam publish @username/addon Release-1 @owner_repo.zipSecret keys are scoped to one user or org and can only publish releases for existing addons under that owner. If ASSET_NAME is omitted, gdam publish uses @owner_repo.zip from GITHUB_REPOSITORY when available.
The registry supplies the GitHub Release ID, exact tag, commit SHA, asset ID, asset name, SHA-256 digest, publication time, and prerelease state. Before each install, GDAM rechecks that identity with GitHub, downloads through the immutable asset-ID endpoint, and verifies the digest before extraction. Any release, tag, commit, asset, digest, truncation, or archive-layout drift fails closed.
Registry requests time out after 30 seconds and response bodies are limited to
4 MiB. Asset downloads time out after two
minutes, follow at most five redirects, and are limited to 128 MiB. Authorization
is removed on cross-origin redirects. Extraction rejects absolute paths, ..
traversal, backslashes, and symlinks; it permits at most 10,000 entries and 512
MiB total uncompressed content. ZIP assets must contain plugin.cfg at the
archive root.
Build the CLI:
./scripts/cli_build.shRun tests:
go test ./...CLI releases use v* tags. The manual release workflow must run from main, accepts a patch, minor, or major bump, runs Go tests, injects version/build metadata, and builds gdam binaries for Linux, macOS, and Windows with checksums. It needs no repository secrets — the binary contains no keys.
MIT