Skip to content

alloy-provisioner Command Reference

alloy-provisioner runs inside a Linux system (PC, laptop, or server, VM, WSL2, or Docker) and applies a blueprint to install packages, download toolchains, and configure the environment. This page documents the CLI; for the full mental model see How Alloy works. The alloy-host reference documents the host-side tool that manages VMs and runs the provisioner inside them.

Subcommands

alloy-provisioner install [name[:tag]]

Install supports two modes:

  • install <name[:tag]>: pull a blueprint from the registry and run it immediately (recommended for Alloy Hub).
  • install with no name (and --blueprint-dir): run a local blueprint directory without pulling from the registry.
sudo alloy-provisioner install community/nordic/nrf91:1.1.3
sudo alloy-provisioner install community/raspberry-pi/raspberry-pi-5:1.0.3 --registry api.alloy-it.io

# Local blueprint (already cloned or in a repo)
sudo alloy-provisioner install --blueprint-dir /path/to/blueprint

# Simulate without executing tasks (still validates and may pull the blueprint)
sudo alloy-provisioner install --dry-run community/nordic/nrf91:1.1.3

Use a tagged blueprint name. Published tags are listed with clone --list community. The default --tag is latest, which is not published on the registry—always pass name:tag or --tag.

Short names without a project prefix are resolved under community/ (e.g. nordic/nrf91:1.1.3 → community/nordic/nrf91:1.1.3).

alloy-provisioner clone <name[:tag]>

Pull blueprint files from the registry without running them. Files are written to: <blueprint-dir>/blueprints/<name> (default base: ~/.alloy-it/).

alloy-provisioner clone community/nordic/nrf91:1.1.3
# Inspect the blueprint, then:
sudo alloy-provisioner install --blueprint-dir ~/.alloy-it/blueprints/community/nordic/nrf91

--list <project>: browse available blueprints

alloy-provisioner clone --list community

Example output shape:

BLUEPRINT                                           TAGS
community/nordic/nrf91                              1.1.3
community/nordic/nrf52                              1.1.3
community/raspberry-pi/raspberry-pi-5             1.0.3
...

Use the blueprint name and tag from the list as the argument to clone or install:

alloy-provisioner clone community/nordic/nrf91:1.1.3
sudo alloy-provisioner install community/nordic/nrf91:1.1.3

alloy-provisioner check

Run pre-flight URL reachability checks on the blueprint without provisioning tasks. Exit code 0 if all checks pass, 1 if any URL is unreachable.

alloy-provisioner check --blueprint-dir /path/to/blueprint

alloy-provisioner update-check

Query GitHub releases and print whether a newer alloy-provisioner version is available.

alloy-provisioner update-check

Running from a local blueprint

sudo alloy-provisioner install --blueprint-dir /path/to/blueprint

For Docker builds where you want tasks with exclude: [docker] to be skipped (required on 1.4.0):

sudo alloy-provisioner install --docker --blueprint-dir /path/to/blueprint

export ALLOY_BLUEPRINT_DIR=/path/to/blueprint
sudo -E alloy-provisioner install --blueprint-dir "$ALLOY_BLUEPRINT_DIR"

Global flags

These apply to install, clone, check, and update-check (see alloy-provisioner --help).

Flag Description
--blueprint-dir Path to the blueprint directory. Overrides ALLOY_BLUEPRINT_DIR. Default: $HOME/.alloy-it
--docker Activate the docker environment tag (skip tasks with exclude: [docker]). Or ALLOY_ENV_DOCKER=1
--wsl2 Activate the wsl2 environment tag. Or ALLOY_ENV_WSL2=1
--dry-run Simulate install: validate blueprint and print execution plan without executing tasks. Or ALLOY_DRY_RUN=1
--preflight Run URL reachability checks before provisioning. Or ALLOY_RUN_PREFLIGHT=1
--env-file Path to a KEY=VALUE env file; if omitted, .env in the blueprint directory is auto-detected
-v, --version Print version and exit

Flags on install and clone only

Flag Description Default
--registry Registry host/URL; overrides ALLOY_URL, ALLOY_REGISTRY_URL, ALLOY_REGISTRY api.alloy-it.io
--tag Blueprint image tag when not given as name:tag latest (use an explicit tag in practice)
--platform Force OS/arch (e.g. linux/arm64, linux/amd64) Current machine

clone only

Flag Description
--list List blueprints in a project (e.g. community) and exit

Environment variables

Variable Purpose
ALLOY_BLUEPRINT_DIR Blueprint directory path (same as --blueprint-dir)
ALLOY_URL, ALLOY_REGISTRY_URL, ALLOY_REGISTRY Registry URL for pulling blueprints
ALLOY_REGISTRY_USERNAME Username for private registry authentication
ALLOY_REGISTRY_PASSWORD Password or token for private registry authentication
ALLOY_ENV_DOCKER If set to 1, activates the docker environment tag
ALLOY_ENV_WSL2 If set to 1, activates the wsl2 environment tag
ALLOY_DRY_RUN If set to 1, same as --dry-run
ALLOY_RUN_PREFLIGHT If set to 1, same as --preflight

Custom variables (e.g. for blueprint required_env:) can be set in an env file and passed with --env-file, or exported before running the provisioner.

alloy-provisioner catalog

The catalog subcommand lets you browse and query the alloy-catalog toolchain repository from the command line. It is stored locally at ~/.alloy-it/catalog/ and must be fetched before first use.

catalog update

alloy-provisioner catalog update

Requires git. Run once before searching, and again to pick up new toolchain versions.

catalog search <query>

Find toolchain descriptors by ID, name, or tag (not Hub blueprints). For published blueprints use clone --list community.

alloy-provisioner catalog search arm
alloy-provisioner catalog search nordic

catalog info <id[@version]>

alloy-provisioner catalog info toolchain.arm-gnu.arm-none-eabi
alloy-provisioner catalog info toolchain.arm-gnu.arm-none-eabi@13.3.rel1

For full background on the catalog, see Available Toolchains.

Next steps