From 5ba5b564ad7c591bfefb060fe5aeebfb188b6c93 Mon Sep 17 00:00:00 2001 From: Quratulain-bilal Date: Mon, 29 Jun 2026 05:16:28 +0500 Subject: [PATCH 1/2] 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/reference/integrations.md | 41 ++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md index 36829ec8be..99a7a736a0 100644 --- a/docs/reference/integrations.md +++ b/docs/reference/integrations.md @@ -152,6 +152,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 `search` and `install` look for integrations. Catalogs are checked in priority order. + +### List Catalogs + +```bash +specify integration catalog list +``` + +Shows the active catalog sources. Project-level sources are removable; built-in sources are shown for reference. + +### 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`: From fb697be15cfcb62481e1396c390b534da424795e Mon Sep 17 00:00:00 2001 From: Quratulain-bilal Date: Mon, 29 Jun 2026 23:34:51 +0500 Subject: [PATCH 2/2] 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 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md index 99a7a736a0..685cfa10fb 100644 --- a/docs/reference/integrations.md +++ b/docs/reference/integrations.md @@ -154,7 +154,7 @@ list, or records no installed integrations. ## Catalog Management -Integration catalogs control where `search` and `install` look for integrations. Catalogs are checked in priority order. +Integration catalogs control where the discovery commands (`search` and `info`) look for integrations. Catalogs are checked in priority order. ### List Catalogs @@ -162,7 +162,7 @@ Integration catalogs control where `search` and `install` look for integrations. specify integration catalog list ``` -Shows the active catalog sources. Project-level sources are removable; built-in sources are shown for reference. +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