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) and copies the blueprint into each
environment. The actual provisioning (installing packages, downloading
toolchains, writing env files) is performed inside the guest by
alloy-provisioner, which alloy-host triggers via backend bootstrap logic.
See How Alloy works for the full model.
Environment lifecycle¶
alloy-host init¶
Create a new environment. The environment directory is placed at ~/.alloy-it/envs/<name>/ by default.
--blueprint is required.
| Flag | Description |
|---|---|
--blueprint, -b |
Blueprint name to use (required) |
--backend |
Backend type: vm (default), wsl2, or docker |
--wsl-user |
Linux username inside the WSL2 distro (WSL2 only, default: vagrant) |
--path |
Override base directory for the environment (default: ~/.alloy-it/envs/) |
Examples:
alloy-host init arm-dev --blueprint arm-gcc
alloy-host init nrf91-dev --blueprint nrf91
alloy-host init arm-dev --blueprint arm-gcc --backend wsl2
alloy-host init arm-dev --blueprint arm-gcc --backend docker
alloy-host init arm-dev --blueprint arm-gcc --path ~/projects/embedded
Init registers the environment but does not start the VM.
alloy-host up¶
Start the environment. Creates and provisions it if it doesn't exist yet; resumes it if it's stopped.
Examples:
alloy-host stop¶
Stop or suspend the environment (backend-dependent). Data and state are
preserved. Resume with up.
alloy-host destroy¶
Delete the environment instance. The environment directory and its files are not
affected; recreate it any time with alloy-host up.
| Flag | Description |
|---|---|
--all, -a |
Also delete the persistent data disk. Permanent. |
alloy-host provision¶
Re-run the blueprint on an already-running environment. Tasks that previously completed are skipped. Use this after modifying the blueprint.
alloy-host list¶
Show all registered environments.
Working with the environment¶
alloy-host ssh¶
Open an interactive shell inside the environment. Your host project directory is
available at /vagrant.
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 with the exact URLs and checksums for your host architecture.
Run this after adding or changing toolchains: entries in your manifest. Commit the resulting alloy.lock.yml.
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 that Vagrant and VirtualBox (VBoxManage) are installed and report their versions.