---
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.
- Annotate an overlay's intent (category, upstream status, provenance) — read the `azldev-overlay-metadata` 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.