Command Reference¶
Complete reference for all alloy-host commands.
Most commands accept an optional environment name. If omitted, Alloy uses the environment in the current directory, or prompts you to select if multiple are registered.
Architecture: alloy-host runs on your machine (the host). It creates and
manages environments (VM, WSL2, or Docker). The guest runs alloy-provisioner
against the blueprint name:tag recorded at init (files are pulled from the
registry inside the guest, not copied from a host folder). See
How Alloy works for the full model.
Environment lifecycle¶
alloy-host init¶
Create a new environment. The environment directory is created as <cwd>/<name>/ (a folder named after the environment in your current directory).
--blueprint is required. Use a published tag (see alloy-provisioner clone --list community). Local paths such as ./my-blueprint are not supported.
| Flag | Description |
|---|---|
--blueprint, -b |
Registry blueprint name and tag (required) |
--backend |
Backend type: vm (default), wsl2, or docker |
--dockerfile |
Custom Dockerfile for the docker backend |
--wsl-user |
Linux username inside the WSL2 distro (WSL2 only, default: vagrant) |
Examples:
alloy-host init arm-dev --blueprint community/nordic/nrf91:1.1.3
alloy-host init nrf91-dev --blueprint community/nordic/nrf91:1.1.3
alloy-host init arm-dev --blueprint community/nordic/nrf91:1.1.3 --backend wsl2
alloy-host init arm-dev --blueprint community/nordic/nrf91:1.1.3 --backend docker
Init registers the environment but does not start the VM.
alloy-host up¶
Start the environment and run provisioning. Exact behaviour depends on the backend (VM boot vs WSL2 bootstrap vs docker image build). See With Alloy Host.
Examples:
alloy-host stop¶
Stop the environment (vagrant halt, wsl --terminate, docker stop).
Resume with up (backend-dependent whether provisioning runs again).
alloy-host destroy¶
Delete the environment instance (VM, WSL guest, or docker container). Files in
the host <name>/ directory remain. In 2.1.0, destroy also removes the
environment from alloy-host list, with or without --all. --all additionally
removes the docker image (docker) or the wsl-disk/ folder (wsl2); on vm it has
no extra effect.
| Flag | Description |
|---|---|
--all, -a |
Stronger cleanup where the backend supports it (docker: container + image + registry since Alloy Host 2.2.0) |
alloy-host provision¶
Re-run provisioning for the blueprint tag frozen at init. On docker this
rebuilds from the image recipe; it does not hot-patch a running container.
alloy-host list¶
Show all registered environments.
Working with the environment¶
alloy-host ssh¶
Open an interactive shell inside the environment. VM: project sync often
appears under /vagrant. Docker: no host project mount; use a login shell
(bash -l) if toolchain PATH is missing.
Blueprint management¶
alloy-host validate¶
Check blueprint YAML files for syntax errors and missing required fields, without touching the VM.
alloy-host resolve¶
Read toolchains: references from manifest.yml, resolve them against the local catalog, and write alloy.lock.yml.
In release 2.1.0, resolve expects a registered environment context and fails in a plain blueprint authoring folder (no VMs found in registry). For catalog-backed lockfiles, run catalog update first and use resolve from an initialized env when supported, or maintain alloy.lock.yml by hand until the public authoring workflow (F6) ships.
Re-running resolve to refresh @stable refs is not reliable for registry-installed envs today; bump pins in the blueprint or lockfile explicitly.
USB device management¶
alloy-host usb list¶
List USB devices connected to the host. Pass a VM name to see which are already attached to it.
alloy-host usb attach¶
Attach a USB device to a VM. Identify the device by number (from usb list), partial name, or UUID/BUSID.
Examples:
alloy-host usb attach # interactive: pick VM then device
alloy-host usb attach 1 # device 1 to current directory's VM
alloy-host usb attach 1 arm-dev # device 1 to arm-dev
alloy-host usb attach "J-Link" arm-dev # by partial name
alloy-host usb detach¶
Release a USB device back to the host.
alloy-host usb status¶
Show which USB devices are currently attached to any VM or WSL2.
Catalog¶
alloy-host catalog update¶
Clone or pull the latest catalog into ~/.alloy-it/catalog/.
| Flag | Description |
|---|---|
--remote |
Remote Git URL (default: public Alloy catalog) |
alloy-host catalog search¶
Search the local catalog by ID, name, or tag.
alloy-host catalog info¶
Show details about a catalog entry, including all available versions.
alloy-host catalog info toolchain.arm-gnu.arm-none-eabi
alloy-host catalog info toolchain.arm-gnu.arm-none-eabi@13.3.rel1
alloy-host catalog add¶
Validate a version descriptor YAML file and update the tool's index.yaml. Used when contributing to the catalog.
Configuration¶
alloy-host config show¶
Show current configuration: config file path, Vagrant path, VBoxManage path.
alloy-host config set vagrant-path¶
Set a custom path to the Vagrant executable.
alloy-host config set vbox-manage-path¶
Set a custom path to the VBoxManage executable.
alloy-host config unset vagrant-path¶
Remove the custom Vagrant path and revert to auto-discovery.
alloy-host config unset vbox-manage-path¶
Remove the custom VBoxManage path and revert to auto-discovery.
System¶
alloy-host check-health¶
Check host dependencies. 2.1.0: Vagrant and VirtualBox only; exits 0 when found.
2.1.0: no flags.
New in Alloy Host 2.2.0 / alloy-provisioner 1.5.0
alloy-host check-health --backend vm|wsl2|docker|all (default all) reports OK / WARN / FAIL per backend and exits non-zero when a requested backend fails.