azldev

name

azldev

description

Read this before running azldev or editing azldev config, and whenever working in a repo that contains an azldev.toml file; do not guess azldev's commands or config. Explains how to use the azldev CLI to build a distro from TOML config, including the core concepts (components, overlays, distros, rendered specs, locks), running azldev (repo root or -C, plus the -q and -O json flags), the common commands, and where to go for each workflow. Triggers include azldev, comp build, comp render, comp update, build a component, add a component, distro config.

Using azldev

azldev builds a Linux distribution from TOML configuration. It imports RPM specs from an upstream distro and customizes them with an overlay system — no spec forking. Components render to specs and sidecar build inputs, then build into RPMs; images assemble RPMs into bootable artifacts.

Orient yourself

• Run azldev from the repo root (where azldev.toml lives), or pass -C <dir>.
• Global, agent-friendly flags: -q (quiet) and -O json (machine-readable output). They work on every command.
• Config is a stitched TOML hierarchy: azldev.toml includes the distro and project config, which include the component files (**/*.comp.toml) into one namespace.

Core concepts

• Component — a unit of packaging that renders to a spec and sidecar build inputs, then builds into one or more RPMs. Its spec source is upstream (default), a pinned upstream distro/version, or a local spec.
• Overlay — a semantic patch applied to a spec or source file at render time, so you customize upstream without forking it.
• Distro — a named build target (*.distro.toml) with upstream URIs, release versions, and build inputs.
• Rendered spec — the generated .spec after overlays; a build input, never hand-edited.
• Lock — a per-component file pinning the resolved upstream commit and an input fingerprint.

Common commands

Top-level commands in this build:

• azldev completion — Generate the autocompletion script for the specified shell
• azldev component — Manage components
• azldev config — Manage tool configuration
• azldev docs — Documentation commands
• azldev image — Manage Azure Linux images
• azldev package — Manage binary package configuration
• azldev project — Manage Azure Linux projects
• azldev repo — Inspect and manage RPM repositories
• azldev version — Print the CLI version

Everyday tasks (add -q -O json when scripting):

Task	Command
List components	azldev comp list -a
Inspect one component	azldev comp list -p <name>
Add a component	azldev comp add
Build a component	azldev comp build -p <name>
Render specs	azldev comp render -p <name> (or -a)
Refresh a lock	azldev comp update -p <name>
List / build images	azldev image list / azldev image build

comp is an alias for component. Always confirm current syntax with azldev <command> --help.

The hidden advanced group (adv) contains specialist integrations such as MCP and mock helpers; it is intentionally omitted from normal help.

Where to go next

• Add a new component — read the azldev-add-component skill.
• Edit or review a component's TOML — read the azldev-comp-toml skill.
• Add or change overlays — read the azldev-overlays skill.
• Build, iterate, and debug a component — read the azldev-build-component skill.
• Build, boot, and register images — read the azldev-image skill.
• Refresh a lock and finalize for a PR — read the azldev-update-component skill.
• Remove a component — read the azldev-remove-component skill.
• Test built RPMs in a chroot — read the azldev-mock skill.

Golden rules

• Never edit generated output — rendered specs and the output/work/log dirs are produced by azldev. Change the source config and re-render.
• Re-run azldev comp update before opening a PR — the lock fingerprint covers the whole component config, and lock / rendered-spec CI checks run on committed state.
• Every overlay needs a description explaining why the change is needed.

Generated by azldev docs agent; do not hand-edit. Generated for azldev version v0.3.0.