Working with catalogs

Catalogs and manifests

Every tool nem can install is described by a pkg.yaml manifest — a small file that tells nem where to fetch the tool, how to verify it, and how to install it. One manifest describes one package.

A catalog is a collection of these manifests, laid out as pkgs/<name>/pkg.yaml. A catalog can be distributed in three ways:

a local directory on your machine
a git repository
an OCI registry

The official catalog

nem ships with the public vi-dev/nem-catalog enabled out of the box, so common tools are available with no setup. It’s an OCI catalog served from ghcr.io/vi-dev/nem-catalog, registered under the reserved name official.

The official catalog is always appended last, so any catalog you add takes precedence over it for any package both define. It is implicit — not stored in config.yaml — so you cannot reorder or remove it with nem catalog reorder or nem catalog remove. The name official is reserved: nem catalog add rejects it with an error.

Disable the official catalog with use-official-catalog: false in config.yaml, or NEM_USE_OFFICIAL_CATALOG=0 (see Configuration).

Add a catalog

nem catalog add requires the source type to be given explicitly with one of its subcommands — git, local-dir, or oci:

nem catalog add local-dir team /path/to/catalog
nem catalog add git team https://github.com/org/catalog.git
nem catalog add oci team ghcr.io/org/catalog:v1

Pass --ref to add git to pin a branch, tag, or commit (defaults to main).

Choosing where artifacts download from

By default, an oci catalog’s package archives and sources still download from wherever each pkg.yaml declares — a GitHub release, or another HTTP host. Add --artifacts registry to fetch them from the catalog’s own registry instead — useful for air-gapped environments, private mirrors, or avoiding upstream rate limits:

nem catalog add oci team ghcr.io/org/catalog:v1 --artifacts registry

--artifacts accepts upstream (the default), registry (strict — never contacts upstream; a missing artifact is a hard error), or prefer-registry (registry first, falling back to upstream only when an artifact isn’t mirrored). NEM_OCI_ARTIFACTS overrides the mode for every OCI catalog. See Artifact source for the full semantics, and Mirror package artifacts to populate a registry with nem author mirror.

List and inspect

nem catalog list
nem catalog info team

Lookup order

When searching for packages, catalogs are searched in order; the first one that provides a package wins. The official catalog is always last (lowest precedence). To set the order of your explicit catalogs, use nem catalog reorder:

nem catalog reorder team extra

Update

Git and OCI catalogs are fetched from an upstream source — a git remote or an OCI registry tag — and cached locally. When that upstream changes (new packages or new versions), pull the latest into your cache:

nem catalog update          # every catalog
nem catalog update team     # one catalog

nem update is the same command, available at the top level:

nem update team

A local-directory catalog is read straight from disk, so it always reflects the current files — there’s nothing to fetch.

Remove

nem catalog remove team

To build and publish your own catalog, see Authoring packages.

Global vs project scope Sandboxed builds