From 00f6a80201eb49e69942638d9e76a136fb5c7e30 Mon Sep 17 00:00:00 2001 From: Quratulain-bilal Date: Tue, 30 Jun 2026 16:13:17 +0500 Subject: [PATCH] docs: document integration catalog subcommands (#3206) * docs: document integration catalog subcommands the integration reference omits the 'specify integration catalog' subcommand group (list/add/remove) that exists in code, while the extension, preset, and workflow references all document their catalog equivalents. add a catalog management section matching that structure. * docs: address review feedback on integration catalog section - catalogs are consulted by the discovery commands (search/info), not install; install resolves from the built-in registry - 'catalog list' shows project sources as removable only when configured, otherwise active sources are non-removable --- docs/reference/integrations.md | 41 ++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md index c2fe1d8ea..18dbdd1c4 100644 --- a/docs/reference/integrations.md +++ b/docs/reference/integrations.md @@ -173,6 +173,47 @@ is `null` when no installed integration set can be evaluated, such as when the integration state is missing, unreadable, lacks a valid recorded integration list, or records no installed integrations. +## Catalog Management + +Integration catalogs control where the discovery commands (`search` and `info`) look for integrations. Catalogs are checked in priority order. + +### List Catalogs + +```bash +specify integration catalog list +``` + +Shows the active catalog sources. Project-level sources (when configured) are removable by index; otherwise the active sources are shown as non-removable. + +### Add a Catalog + +```bash +specify integration catalog add +``` + +| Option | Description | +| --------------- | ----------------------------- | +| `--name ` | Optional name for the catalog | + +Adds a custom catalog URL to the project's `.specify/integration-catalogs.yml`. The URL must use HTTPS (except `http://localhost`, `http://127.0.0.1`, or `http://[::1]` for local testing). + +### Remove a Catalog + +```bash +specify integration catalog remove +``` + +Removes a project catalog source by its 0-based index in `catalog list`. + +### Catalog Resolution Order + +Catalogs are resolved in this order (first match wins): + +1. **Environment variable** — `SPECKIT_INTEGRATION_CATALOG_URL` overrides all catalogs +2. **Project config** — `.specify/integration-catalogs.yml` +3. **User config** — `~/.specify/integration-catalogs.yml` +4. **Built-in defaults** — official catalog + community catalog + ## Integration-Specific Options Some integrations accept additional options via `--integration-options`: