`catalog`

Add and list external catalogs in jbang-catalog.json.

When to use it

Share common script aliases across repositories.
Inspect imported catalogs before resolving an alias.
Add a team catalog during project setup.

Common workflows

jbx catalog list --json
jbx catalog add team https://example.com/jbang-catalog.json
jbx catalog add local ./tools/jbang-catalog.json

Real-life examples

Add a shared team catalog

jbx catalog list --json
jbx catalog add team https://example.com/jbang-catalog.json
jbx catalog list --json

Use catalog when a repository imports shared aliases or templates. List first so you do not add duplicate names or shadow a local catalog entry by accident.

Agent loop

Read existing catalogs with jbx catalog list --json.
Add one catalog with a clear name and URL/path.
Re-read list output and verify the new entry.
Inspect git diff jbang-catalog.json before relying on imported aliases.

Agent notes

Catalog URLs are part of the repository's executable discovery path. Prefer stable HTTPS URLs or checked-in relative paths; avoid personal scratch URLs.

JSON and schema

jbx catalog list --json returns imported catalog names and locations. Example output and field notes: catalog JSON.

Example JSON:

[
  {
    "name": "team",
    "catalogRef": "https://example.com/jbang-catalog.json",
    "catalog": "https://example.com/jbang-catalog.json",
    "description": null,
    "import": false
  }
]

Verification checklist

New catalog entry has the intended name and URL/path.
Existing catalog entries are unchanged.
Imported aliases/templates resolve only after the catalog is trusted by the repository owner.

Arguments and flags

This section is copied from the CLI help for this release so the page explains the actual accepted arguments.

`jbx catalog`

Manage external catalogs from jbang-catalog.json

Usage: jbx catalog <COMMAND>

Commands:
  add   Add an external catalog reference
  list  List external catalog references
  help  Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

`jbx catalog list`

List external catalog references

Usage: jbx catalog list [OPTIONS]

Options:
      --json  Print JSON instead of tab-separated text
  -h, --help  Print help

`jbx catalog add`

Add an external catalog reference

Usage: jbx catalog add [OPTIONS] <NAME> <CATALOG_REF>

Arguments:
  <NAME>         Catalog name
  <CATALOG_REF>  Catalog path, URL, or directory

Options:
  -g, --global                     Use the global user catalog file (~/.jbang/jbang-catalog.json)
  -f, --file <FILE>                Path to the catalog file or directory to use
      --description <DESCRIPTION>  Description for the catalog
      --import                     Import aliases and templates from this catalog into local lookup
      --force                      Force overwrite of an existing catalog reference
  -h, --help                       Print help

Skill

Agents can fetch the matching versioned skill with:

jbx skill get jbx-catalog