aw-index-cli

aw-index-cli is the consumer CLI for the Autoware Index registry. It reads a distribution manifest (distributions/<rosdistro>.yaml) and composes a vcs2l .repos file you can vcs import into a workspace.

The registry is repository-keyed: each entry is one repository with exactly one ref and the packages it hosts.

Install

With pipx (recommended for an isolated CLI):

pipx install aw-index-cli   # first install
pipx upgrade aw-index-cli   # update to the latest release

Commands

• compose — render a .repos file from a distribution.
• check — gate a composed .repos against the registry and sweep history.
• list — list registry packages with their latest validation status.

compose

Select what you need by package, repository, or tag — the distribution is fetched from GitHub by default, so no registry checkout is required.

# Recommended: compose just the packages you want.
aw-index-cli compose --rosdistro jazzy \
  --packages autoware_livox_tag_filter

# …or pull in whole repository entries by their registry key.
aw-index-cli compose --rosdistro jazzy \
  --repository autoware_livox_tag_filter

# Narrow by tag (filters can be combined; they are ANDed).
aw-index-cli compose --rosdistro jazzy --tags sensing perception

# Print to stdout instead of writing a file.
aw-index-cli compose --rosdistro jazzy \
  --packages autoware_livox_tag_filter --stdout

[!TIP] Omitting all of --packages, --repository, and --tags composes the entire distribution — supported, but usually you want to name what you consume.

Example output for compose --rosdistro jazzy --repository livox-tools (a monorepo entry hosting two registered packages):

# aw-index-cli 0.4.0
# source: autowarefoundation/autoware-index@main
# rosdistro: jazzy
# tags: all
# repository: livox-tools
# generated_at: 2026-06-11T12:00:00+00:00
# selected packages by repository:
#   livox-tools: autoware_livox_decoder, autoware_livox_tag_filter
# Generated file — re-run 'aw-index-cli compose …' to update; do not edit by hand.

repositories:
  livox-tools:
    type: git
    url: https://github.com/autowarefoundation/autoware_livox_tag_filter
    version: main

Less common sources — a local registry checkout, or a fork / specific git ref:

# Read from a local registry checkout instead of GitHub.
aw-index-cli compose --rosdistro jazzy \
  --packages autoware_livox_tag_filter \
  --registry-path /path/to/autoware-index

# Fetch the distribution from a fork at a specific branch/tag/sha.
aw-index-cli compose --rosdistro jazzy \
  --packages autoware_livox_tag_filter \
  --registry-repo me/autoware-index-fork --registry-ref dev

How entries are composed

• Entry keys are registry repository keys — the directory vcs import clones into.
• Filters are ANDed. An unknown --packages name or --repository key is a hard error, never a silent empty result.
• A monorepo collapses to one entry at its single ref, however many of its packages match.
• Each entry is pure vcs2l — type/url/version only. The selected package names live in the # selected packages by repository: header comment, not the YAML body.

[!NOTE] A clone may include unregistered sibling packages the index makes no claims about. To build only the packages you selected, pass their names to colcon:

colcon build --packages-up-to autoware_livox_tag_filter  # names from the header comment

Key options

• --rosdistro (required): ROS distribution, e.g. jazzy.
• --packages / --repository / --tags: selection filters.
• --autoware: informational only — recorded in the header, not a ref selector.
• --registry-path: read a local file or registry directory instead of GitHub.
• --registry-repo / --registry-ref: GitHub source repo (default autowarefoundation/autoware-index) and git ref (default main).
• --repo-root / --name / --output: where and under what name to write the .repos (default <repo-root>/repositories/autoware-index.repos).
• --stdout: print instead of writing a file.
• --no-timestamp: omit generated_at for byte-identical output.

[!IMPORTANT] There is no import command — pipe compose straight into vcs:

aw-index-cli compose --rosdistro jazzy --packages autoware_livox_tag_filter --stdout \
  | vcs import src

check

Verify a composed .repos is still current: every repository at the registry's ref, and each package passing its latest sweep — the registry's periodic build/test against the current Autoware release. Intended as a CI gate after vcs import.

# Auto-discovers ./autoware-index.repos or ./*/autoware-index.repos; rosdistro is
# read from the file's header. Exit code is the gate.
aw-index-cli check

# Or point at a specific file.
aw-index-cli check --repos repositories/autoware-index.repos --rosdistro jazzy

Per repository it reports ref drift, removal from the registry, each package's latest status (pass/fail/—) and the Autoware version tested, and — for branch refs — whether the branch advanced past the last sweep.

• Exit 0 — all pass, no drift.
• Exit 1 — any failing validation, ref drift, or removed package (with --strict, also unvalidated packages or a branch that advanced since the sweep).
• Exit 2 — could not run (bad/missing .repos, registry load error).

Options mirror compose, plus --data-ref (default data), --strict, and --format {table,json}.

[!NOTE] Without git on PATH the branch-drift check is silently skipped, so a green check isn't a complete guarantee.

list

Enumerate the packages registered for a distro with their latest sweep status — discovery plus a health readout, without composing anything.

aw-index-cli list --rosdistro jazzy
aw-index-cli list --rosdistro jazzy --tags sensing --format json

Accepts the same selection filters as compose. Exit 0 normally; with --strict, exit 1 if any selected package is failing or unvalidated; exit 2 on a registry load error.

License

Apache-2.0. See LICENSE.