README.md

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.

The CLI accepts registry schema v4 only. Schema v4 packages may declare index_dependencies, a list of other registered package names in the same ROS distribution. compose includes these packages' repositories recursively.

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, tag, or reference design. 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). Aliases from the
# registry vocabulary resolve too: --tags ai selects the same as --tags ml.
aw-index-cli compose --rosdistro jazzy --tags sensing perception

# Compose entries marked as a reference design.
aw-index-cli compose --rosdistro jazzy --reference-design --stdout | vcs import src

# 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, --tags, and --reference-design composes the entire distribution. That is 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.5.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 are 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 to choose root packages. In schema v4, each root's index_dependencies are then included transitively, regardless of the filters. For example, selecting a planning package also imports its indexed common library even when that library does not match --tags planning. Unknown dependency names and dependency cycles are errors.
• 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 are selected or required as dependencies.
• Each entry is pure vcs2l: type/url/version only. The selected and dependency package names live in the # selected packages by repository: header comment, not the YAML body. check reads this header to verify the included packages.

For example, a schema v4 package can declare:

packages:
  my_planner:
    tags: [planning]
    index_dependencies: [my_map_library]

my_map_library must be registered in the same distribution. The .repos file imports its repository automatically when you compose my_planner. Registration derives these Index edges from upstream package.xml dependency names. If a dependency also has a ROS build farm binary, the Index source is included in the workspace. Install remaining dependencies with rosdep after importing:

rosdep install --from-paths src --ignore-src --rosdistro jazzy -y
colcon build --packages-up-to my_planner

--ignore-src skips binary installation for packages in the source workspace.

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. list displays packages matching the filters; it does not expand their index_dependencies.

License

Apache-2.0. See LICENSE.