openapi-cli4ai 0.6.0__tar.gz → 0.7.0__tar.gz

{openapi_cli4ai-0.6.0 → openapi_cli4ai-0.7.0}/.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
         python-version: ["3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: true
       - name: Set up Python ${{ matrix.python-version }}
@@ -31,7 +31,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
       - name: Sync dependencies
         run: uv sync --locked
       - name: Ruff check
@@ -43,7 +43,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
       - name: Sync dependencies
         run: uv sync --locked
       - name: Run mypy

{openapi_cli4ai-0.6.0 → openapi_cli4ai-0.7.0}/.github/workflows/codeql.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: github/codeql-action/init@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
+      - uses: github/codeql-action/init@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4.37.8
         with:
           languages: python
-      - uses: github/codeql-action/analyze@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
+      - uses: github/codeql-action/analyze@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4.37.8

{openapi_cli4ai-0.6.0 → openapi_cli4ai-0.7.0}/.github/workflows/publish.yml

@@ -14,7 +14,7 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
       - name: Build sdist and wheel
         run: uv build
       - name: Upload artifacts
@@ -42,8 +42,8 @@ jobs:
           name: dist
           path: dist/
       - name: Generate attestations
-        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
         with:
           subject-path: dist/*
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

{openapi_cli4ai-0.6.0 → openapi_cli4ai-0.7.0}/.github/workflows/validate-profiles.yml

@@ -19,6 +19,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
       - name: Validate catalog profiles
         run: uv run --locked openapi-cli4ai catalog validate --all
+      - name: Check profiles/index.json is current
+        run: uv run --locked openapi-cli4ai catalog index --check

{openapi_cli4ai-0.6.0 → openapi_cli4ai-0.7.0}/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.7.0] - 2026-09-11
+
+### Added
+
+- `--profile` is accepted after the subcommand (`openapi-cli4ai endpoints --profile x`); long form only, since `-p` is reused by subcommands (#52)
+- `catalog install --dry-run` prints the exact profile file that would be written and changes nothing (#53)
+- `catalog uninstall <name>` removes an installed catalog profile plus its cached spec and token, with confirm prompt and `--force` (#54)
+- Drop-in profiles: one file per profile under `~/.openapi-cli4ai/profiles.d/<name>.toml`, read alongside `~/.openapi-cli4ai.toml` (a drop-in overrides a same-named entry). `catalog install` writes there. No migration needed (#56)
+- Remote catalog index: `catalog list`/`search`/`show`/`install` merge `profiles/index.json` from `main` over the bundled catalog (3 s timeout, cached one hour, silent fallback to cache then bundled; every remote entry is re-validated). `OAC_CATALOG_OFFLINE=1` disables it. New `catalog index` command generates the committed index; CI checks it is current (#57)
+- DNS TXT domain verification: a profile may set `domain_verified = true`; `catalog validate` resolves `_openapi-cli4ai.<domain>` and requires `github=<maintainer>`. Shown as a `✓ dns` badge, separate from the tier (#58)
+
+### Changed
+
+- `cli.py` split into `config.py`, `catalog.py`, `validator.py` plus small state/UI modules; behavior unchanged (#55)
+- Adopted ruff 0.16's default rule set; the rule selection is no longer implicit (#50, #51)
+- Dependency updates: `typer` 0.27.2, `click` 8.5, `python-dotenv`, `mypy`, `types-PyYAML`, and the GitHub Actions group (#49, #50)
+
+### Fixed
+
+- Rich swallowed TOML table headers such as `[profiles.x]` in `profile show` output; now rendered as plain text (#53)
+- File paths in install output are never wrapped across lines (#56)
+
 ## [0.6.0] - 2026-07-31
 
 ### Added

{openapi_cli4ai-0.6.0 → openapi_cli4ai-0.7.0}/CONTRIBUTING.md

@@ -16,12 +16,17 @@ Thanks for your interest in contributing!
 src/openapi_cli4ai/
   __init__.py       # Package exports
   __main__.py       # python -m support
-  cli.py            # All CLI code lives here
+  cli.py            # Typer commands, HTTP/auth flows, spec fetching
+  config.py         # Config file, cache dir, active-profile precedence
+  catalog.py        # Bundled profile catalog: load, find, map to a profile
+  validator.py      # Catalog profile validator (shared by `catalog validate` and CI)
+  _state.py         # Runtime flags set by the root command (--verbose, --profile, ...)
+  _ui.py            # Shared Rich consoles and the verbose logger
 openapi-cli4ai      # Standalone shim (imports from package)
 tests/              # pytest tests
 ```
 
-The core code lives in `src/openapi_cli4ai/cli.py`. The standalone `openapi-cli4ai` script is a thin shim that imports from the package.
+Commands live in `src/openapi_cli4ai/cli.py`; it imports the helpers it needs from the service modules, so tests can patch either the service module or the `cli` binding. The standalone `openapi-cli4ai` script is a thin shim that imports from the package.
 
 ## Testing
 
@@ -48,10 +53,16 @@ pytest tests/ -m "not integration" -v
 3. Keep the `description` factual. `source` must be the API's own developer or
    docs URL (same domain as `base_url`).
 4. Validate locally: `uv run openapi-cli4ai catalog validate profiles/community/<slug>.toml`
-
-CI runs `catalog validate --all` on every PR touching `profiles/`, checking the
-fields, a live spec fetch, ownership, and absence of inline secrets — errors
-appear inline on the PR. Profiles that are primarily promotional will be closed
+5. Regenerate the index and commit it: `uv run openapi-cli4ai catalog index`
+6. Optional: claim the domain-verified badge by setting `domain_verified = true`
+   and publishing a `_openapi-cli4ai.<domain>` TXT record naming you; see
+   "Domain verification" in [`profiles/README.md`](profiles/README.md).
+
+CI runs `catalog validate --all` and `catalog index --check` on every PR touching
+`profiles/`, checking the fields, a live spec fetch, ownership, absence of inline
+secrets, any `domain_verified` claim against DNS, and that `profiles/index.json`
+is current — errors appear inline on the PR. Once merged, the profile is visible to every installed CLI within an hour
+via the remote index (see `profiles/README.md`, "Freshness"). Profiles that are primarily promotional will be closed
 without review.
 
 ## Reporting Issues

{openapi_cli4ai-0.6.0 → openapi_cli4ai-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: openapi-cli4ai
-Version: 0.6.0
+Version: 0.7.0
 Summary: Turn any REST API with an OpenAPI spec into an AI-ready CLI
 Project-URL: Homepage, https://github.com/dbgorilla/openapi-cli4ai
 Project-URL: Repository, https://github.com/dbgorilla/openapi-cli4ai
@@ -237,6 +237,8 @@ openapi-cli4ai logout
 
 Profiles are stored in `~/.openapi-cli4ai.toml`. Secrets are referenced via environment variables — never stored in the config file.
 
+Profiles can also live one-per-file under `~/.openapi-cli4ai/profiles.d/<name>.toml`, where the file holds the profile's keys directly (no `[profiles.<name>]` header) and the file name is the profile name. `catalog install` writes there so installing, upgrading and uninstalling a profile touch only that file. Both locations are read; a drop-in overrides a same-named entry in `~/.openapi-cli4ai.toml`. `active_profile` is only read from `~/.openapi-cli4ai.toml`.
+
 ```toml
 active_profile = "myapi"
 

{openapi_cli4ai-0.6.0 → openapi_cli4ai-0.7.0}/README.md

@@ -208,6 +208,8 @@ openapi-cli4ai logout
 
 Profiles are stored in `~/.openapi-cli4ai.toml`. Secrets are referenced via environment variables — never stored in the config file.
 
+Profiles can also live one-per-file under `~/.openapi-cli4ai/profiles.d/<name>.toml`, where the file holds the profile's keys directly (no `[profiles.<name>]` header) and the file name is the profile name. `catalog install` writes there so installing, upgrading and uninstalling a profile touch only that file. Both locations are read; a drop-in overrides a same-named entry in `~/.openapi-cli4ai.toml`. `active_profile` is only read from `~/.openapi-cli4ai.toml`.
+
 ```toml
 active_profile = "myapi"
 

{openapi_cli4ai-0.6.0 → openapi_cli4ai-0.7.0}/profiles/README.md

@@ -3,7 +3,8 @@
 Ready-made **profiles** for public APIs. A profile is the small bit of config
 `openapi-cli4ai` needs to talk to an API: a base URL, where its OpenAPI spec
 lives, and how it authenticates. The catalog is bundled into the package, so
-these commands work offline:
+these commands work offline; when online they also pick up profiles merged to
+`main` since your release (see [Freshness](#freshness)):
 
 ```bash
 openapi-cli4ai catalog search cov            # find profiles
@@ -26,12 +27,30 @@ a **tier**, shown next to every entry, not a gate on being listed.
 | **Verified** | `verified/` | A maintainer confirmed the spec loads and the auth flow works. |
 | **Community** | `community/` | Contributed via PR and passed automated validation. Not manually vetted. |
 
+Independently of the tier, a profile can carry a **domain-verified** badge
+(`✓ dns` in listings): the owner of the API's domain has published a DNS TXT
+record naming the maintainer, so the listing is backed by domain control, not
+just a self-declared `source`. See [Domain verification](#domain-verification).
+
 New submissions go to `community/`; a maintainer may promote a profile to
 `verified/` after checking it end to end. Installing a **community** profile
 prompts for confirmation (it shows the `base_url` your credentials would be
 sent to); **verified** profiles install without a prompt. Use `--yes` to skip
 the prompt in scripts.
 
+## Freshness
+
+The bundled catalog is the offline baseline. On top of it, `catalog list`,
+`search`, `show` and `install` fetch [`index.json`](index.json) from this
+repository's `main` branch (3 s timeout, cached for an hour under
+`~/.cache/openapi-cli4ai/`) and merge it in, so a profile is usable as soon as
+its PR merges. Any failure falls back to the cached index, then to the bundled
+copy, silently. Every remote entry is re-checked with the offline validator
+before use; a bad one is skipped. Set `OAC_CATALOG_OFFLINE=1` to never fetch.
+
+`index.json` is generated from the TOML files by `openapi-cli4ai catalog index`
+and committed; CI fails a PR whose index is stale.
+
 ## Profile format
 
 One profile per file, named `<slug>.toml`:
@@ -45,6 +64,8 @@ source = "https://example.com/docs"      # the API's official docs (same domain
 base_url = "https://api.example.com"
 openapi_url = "https://api.example.com/openapi.json"   # or: openapi_path = "/openapi.json"
 
+domain_verified = true                   # optional: see "Domain verification" below
+
 [auth]
 type = "api-key"                         # none | bearer | oidc | device | api-key | basic
 env_var = "EXAMPLE_API_KEY"              # reference secrets by env var — never inline them
@@ -55,6 +76,22 @@ Auth field names match the CLI's runtime config; see
 [`../examples/profiles.toml.example`](../examples/profiles.toml.example) for
 each auth type.
 
+## Domain verification
+
+To claim the `✓ dns` badge, set `domain_verified = true` in the profile and have
+the API's domain owner publish this TXT record (registrable domain of
+`base_url`, e.g. `api.acme.co.uk` → `acme.co.uk`):
+
+```
+_openapi-cli4ai.acme.co.uk.  IN  TXT  "github=<maintainer>"
+```
+
+`<maintainer>` must equal the profile's `maintainer` field (case-insensitive).
+`catalog validate` resolves the record and fails the PR if it is missing or
+names someone else; the claim is re-checked on every profile change. Remove the
+claim (or the record) to drop the badge. The lookup needs `dnspython`, which
+`uv sync` installs for contributors; end users never resolve DNS.
+
 ## Contributing a profile
 
 1. Create `community/<slug>.toml` in the format above.
@@ -62,10 +99,12 @@ each auth type.
 3. Keep `description` factual. `source` must be the API's own developer/docs
    URL (same registrable domain as `base_url`).
 
-Validate before opening the PR — the CLI is the single source of truth:
+Validate before opening the PR — the CLI is the single source of truth — and
+regenerate the index:
 
 ```bash
 uv run openapi-cli4ai catalog validate profiles/community/<slug>.toml
+uv run openapi-cli4ai catalog index
 ```
 
 CI runs `catalog validate --all` on every PR touching `profiles/`. It checks the

openapi_cli4ai-0.7.0/profiles/index.json

@@ -0,0 +1,33 @@
+{
+  "profiles": [
+    {
+      "auth": {
+        "env_var": "XQUIK_API_KEY",
+        "header": "x-api-key",
+        "type": "api-key"
+      },
+      "base_url": "https://xquik.com",
+      "description": "Xquik REST API",
+      "maintainer": "kriptoburak",
+      "name": "xquik",
+      "openapi_url": "https://xquik.com/openapi.json",
+      "slug": "xquik",
+      "source": "https://xquik.com",
+      "tier": "community"
+    },
+    {
+      "auth": {
+        "type": "none"
+      },
+      "base_url": "https://petstore3.swagger.io/api/v3",
+      "description": "Swagger Petstore \u2014 the OpenAPI 3 sample API",
+      "maintainer": "dbgorilla",
+      "name": "petstore",
+      "openapi_url": "https://petstore3.swagger.io/api/v3/openapi.json",
+      "slug": "petstore",
+      "source": "https://petstore3.swagger.io",
+      "tier": "verified"
+    }
+  ],
+  "version": 1
+}

{openapi_cli4ai-0.6.0 → openapi_cli4ai-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openapi-cli4ai"
-version = "0.6.0"
+version = "0.7.0"
 description = "Turn any REST API with an OpenAPI spec into an AI-ready CLI"
 readme = "README.md"
 license = "MIT"
@@ -46,12 +46,14 @@ dev = [
     "pytest>=8",
     "pytest-cov>=5",
     "click>=8,<9",
-    # ruff pinned <0.16: 0.16 stabilized RUF059 (and others) that flag ~450
-    # existing lines. CI runs the locked ruff (uv run) instead of uvx-latest so
-    # lint is deterministic; a future bump comes via Dependabot and is gated by CI.
-    "ruff>=0.15,<0.16",
+    # CI runs the locked ruff (uv run) instead of uvx-latest so lint is
+    # deterministic; a bump comes via Dependabot and is gated by CI.
+    "ruff>=0.15,<0.17",
     "mypy>=1.10,<3",
     "types-PyYAML>=6,<7",
+    # DNS TXT domain verification in `catalog validate` (CI + contributors);
+    # end users never resolve DNS, so this is not a runtime dependency.
+    "dnspython>=2.4,<3",
 ]
 
 [tool.hatch.build.targets.wheel]
@@ -66,6 +68,15 @@ packages = ["src/openapi_cli4ai"]
 line-length = 120
 target-version = "py311"
 
+[tool.ruff.lint]
+# Rule set = ruff's defaults for the locked version. Drift is guarded by the
+# version cap on the dev dependency plus uv.lock; a ruff bump arrives via
+# Dependabot and is gated by CI, so new rules are adopted deliberately.
+# RUF059 (unused unpacked variable) is ignored in tests: fixtures return
+# tuples like `mod, tmp_path, cache_dir = tmp_config` and unpacking the
+# full shape is clearer than `_`-prefixing whichever half a test skips.
+per-file-ignores = { "tests/**" = ["RUF059"] }
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 markers = ["integration: live API tests (may be slow)"]

{openapi_cli4ai-0.6.0 → openapi_cli4ai-0.7.0}/src/openapi_cli4ai/__init__.py

@@ -3,4 +3,4 @@
 from openapi_cli4ai.cli import VERSION, app
 
 __version__ = VERSION
-__all__ = ["app", "VERSION", "__version__"]
+__all__ = ["VERSION", "__version__", "app"]

openapi_cli4ai-0.7.0/src/openapi_cli4ai/_state.py

@@ -0,0 +1,22 @@
+"""Runtime settings set once by the root command and read by every layer.
+
+Module globals on purpose: the CLI is a single process handling one command,
+and tests set these directly (``_state._verbose_mode = True``).
+"""
+
+from __future__ import annotations
+
+_insecure_mode = False
+_verbose_mode = False
+_timeout_seconds = 60.0
+_max_retries = 0
+_profile_override: str | None = None
+
+
+def set_insecure_mode(insecure: bool) -> None:
+    global _insecure_mode
+    _insecure_mode = insecure
+
+
+def get_verify_ssl() -> bool:
+    return not _insecure_mode

openapi_cli4ai-0.7.0/src/openapi_cli4ai/_ui.py

@@ -0,0 +1,16 @@
+"""Shared Rich consoles and the verbose logger."""
+
+from __future__ import annotations
+
+from rich.console import Console
+
+from openapi_cli4ai import _state
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def _verbose(msg: str) -> None:
+    """Print a verbose message to stderr if verbose mode is enabled."""
+    if _state._verbose_mode:
+        err_console.print(f"[dim]> {msg}[/dim]")

openapi_cli4ai-0.7.0/src/openapi_cli4ai/catalog.py

@@ -0,0 +1,247 @@
+"""Profile catalog: ready-made API profiles (load, search, map to a runtime profile).
+
+Two sources, merged: the catalog bundled in the wheel (always available, so
+every command works offline) and a remote index published from the main
+branch, so a newly merged profile is visible before the next release. The
+remote index is cached for CATALOG_INDEX_TTL seconds and any failure falls
+back to the cache, then to the bundled copy.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import json
+import os
+import re
+import time
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import httpx
+from rich.table import Table
+
+from openapi_cli4ai import config
+from openapi_cli4ai._ui import _verbose as _log
+from openapi_cli4ai._ui import console
+
+CATALOG_TIERS = ("verified", "community")
+_CATALOG_META_FIELDS = ("name", "description", "maintainer", "source", "domain_verified")
+
+# Remote index: generated by `catalog index` and committed to profiles/index.json.
+CATALOG_INDEX_URL = "https://raw.githubusercontent.com/dbgorilla/openapi-cli4ai/main/profiles/index.json"
+CATALOG_INDEX_TTL = 3600  # seconds
+CATALOG_INDEX_VERSION = 1
+_CATALOG_INDEX_MAX_BYTES = 1024 * 1024
+_CATALOG_INDEX_TIMEOUT = httpx.Timeout(3.0, connect=2.0)  # never make an offline user wait
+# Set to any value to skip the remote index entirely (CI, air-gapped, tests).
+CATALOG_OFFLINE_ENV = "OAC_CATALOG_OFFLINE"
+_SLUG_RE = re.compile(r"[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?")
+
+
+def _catalog_root() -> Any:
+    """Locate the catalog: bundled in the wheel, else profiles/ in a source checkout."""
+    try:
+        bundled = importlib.resources.files("openapi_cli4ai") / "_catalog"
+        if bundled.is_dir():
+            return bundled
+    except (ModuleNotFoundError, FileNotFoundError, AttributeError, TypeError):
+        pass
+    dev = Path(__file__).resolve().parents[2] / "profiles"
+    return dev if dev.is_dir() else None
+
+
+def _load_catalog(remote: bool = True) -> list[dict]:
+    """Return every catalog profile as a dict with _tier and _slug attached.
+
+    Bundled entries first, then the remote index merged on top (a remote entry
+    replaces a bundled one with the same slug). `remote=False` returns only the
+    bundled copy; `catalog validate --all` and `catalog index` use that so they
+    describe the files in this checkout, not whatever main currently publishes.
+    """
+    entries = _load_bundled_catalog()
+    if not remote:
+        return entries
+    remote_entries = _fetch_remote_index()
+    if not remote_entries:
+        return entries
+    merged = {e["_slug"]: e for e in entries}
+    for entry in remote_entries:
+        merged[entry["_slug"]] = entry
+    return list(merged.values())
+
+
+def _load_bundled_catalog() -> list[dict]:
+    """Read the catalog shipped in the wheel (or profiles/ in a source checkout)."""
+    root = _catalog_root()
+    entries: list[dict] = []
+    if root is None:
+        return entries
+    for tier in CATALOG_TIERS:
+        tier_dir = root / tier
+        if not tier_dir.is_dir():
+            continue
+        for item in sorted(tier_dir.iterdir(), key=lambda p: p.name):
+            if not item.name.endswith(".toml"):
+                continue
+            try:
+                entry = tomllib.loads(item.read_text(encoding="utf-8"))
+            except (OSError, tomllib.TOMLDecodeError):
+                continue
+            entry["_tier"] = tier
+            entry["_slug"] = item.name[: -len(".toml")]
+            entries.append(entry)
+    return entries
+
+
+# ── Remote index ──────────────────────────────────────────────────────────────
+def build_index(entries: list[dict]) -> dict:
+    """Serialisable, deterministic index of catalog entries (no timestamps, sorted)."""
+    profiles = []
+    for entry in sorted(entries, key=lambda e: (e.get("_tier", ""), e.get("_slug", ""))):
+        record = {k: v for k, v in entry.items() if not k.startswith("_")}
+        record["tier"] = entry.get("_tier")
+        record["slug"] = entry.get("_slug")
+        profiles.append(record)
+    return {"version": CATALOG_INDEX_VERSION, "profiles": profiles}
+
+
+def index_json(entries: list[dict]) -> str:
+    return json.dumps(build_index(entries), indent=2, sort_keys=True) + "\n"
+
+
+def _index_to_entries(index: Any) -> list[dict] | None:
+    """Turn a parsed index into catalog entries. None if the document is malformed.
+
+    Every entry must pass the offline validator; a bad one is skipped, not fatal,
+    so one broken profile on main cannot blank the catalog for everyone.
+    """
+    # Local import: validator imports this module for _catalog_to_profile.
+    from openapi_cli4ai.validator import _validate_catalog_entry
+
+    if not isinstance(index, dict) or index.get("version") != CATALOG_INDEX_VERSION:
+        return None
+    profiles = index.get("profiles")
+    if not isinstance(profiles, list):
+        return None
+    entries: list[dict] = []
+    for record in profiles:
+        if not isinstance(record, dict):
+            continue
+        entry = dict(record)
+        tier = entry.pop("tier", None)
+        slug = entry.pop("slug", None)
+        if tier not in CATALOG_TIERS or not isinstance(slug, str) or not _SLUG_RE.fullmatch(slug):
+            continue
+        entry["_tier"] = tier
+        entry["_slug"] = slug
+        errors, _warnings = _validate_catalog_entry(entry, check_spec=False)
+        if errors:
+            _log(f"catalog index: skipping '{slug}': {errors[0]}")
+            continue
+        entries.append(entry)
+    return entries
+
+
+def _index_cache_path() -> Path:
+    return config.CACHE_DIR / "catalog_index.json"
+
+
+def _download_index() -> Any:
+    """GET the remote index. Raises httpx.HTTPError or ValueError on any problem."""
+    with httpx.Client(timeout=_CATALOG_INDEX_TIMEOUT, follow_redirects=False) as client:
+        resp = client.get(CATALOG_INDEX_URL)
+        resp.raise_for_status()
+        if len(resp.content) > _CATALOG_INDEX_MAX_BYTES:
+            raise ValueError(f"index exceeds {_CATALOG_INDEX_MAX_BYTES // 1024}KB")
+        return resp.json()
+
+
+def _read_index_cache() -> tuple[float, Any] | None:
+    try:
+        cached = json.loads(_index_cache_path().read_text(encoding="utf-8"))
+        return float(cached["fetched_at"]), cached["index"]
+    except (OSError, ValueError, KeyError, TypeError):
+        return None
+
+
+def _fetch_remote_index() -> list[dict] | None:
+    """Remote catalog entries, via the TTL cache. None means: use the bundled copy only."""
+    if os.environ.get(CATALOG_OFFLINE_ENV):
+        return None
+    cached = _read_index_cache()
+    if cached is not None and time.time() - cached[0] < CATALOG_INDEX_TTL:
+        return _index_to_entries(cached[1])
+    try:
+        index = _download_index()
+    except (httpx.HTTPError, ValueError) as exc:
+        _log(f"catalog index: fetch failed ({exc}); using {'cached' if cached else 'bundled'} catalog")
+        return _index_to_entries(cached[1]) if cached else None
+    entries = _index_to_entries(index)
+    if entries is None:
+        _log("catalog index: malformed document; using bundled catalog")
+        return None
+    try:
+        config.ensure_dirs()
+        config._atomic_write(_index_cache_path(), json.dumps({"fetched_at": time.time(), "index": index}))
+    except OSError as exc:
+        _log(f"catalog index: could not write cache: {exc}")
+    return entries
+
+
+def _catalog_find(name: str) -> dict | None:
+    for entry in _load_catalog():
+        if name in (entry.get("_slug"), entry.get("name")):
+            return entry
+    return None
+
+
+def _catalog_to_profile(entry: dict) -> dict:
+    """Map a catalog entry to a runtime profile (drop catalog-only metadata)."""
+    profile = {k: v for k, v in entry.items() if k not in _CATALOG_META_FIELDS and not k.startswith("_")}
+    profile["verify_ssl"] = True
+    return profile
+
+
+def _auth_env_vars(auth: dict) -> list[str]:
+    """Environment variables the user must set for this auth config."""
+    keys = {
+        "api-key": ("env_var",),
+        "bearer": ("token_env_var",),
+        "basic": ("username_env_var", "password_env_var"),
+    }.get(auth.get("type", "none"), ())
+    return [auth[k] for k in keys if auth.get(k)]
+
+
+def _auth_uses_login(auth: dict) -> bool:
+    kind = auth.get("type", "none")
+    return kind in ("oidc", "device") or (kind == "bearer" and bool(auth.get("token_endpoint")))
+
+
+def _auth_summary(auth: dict) -> str:
+    kind = auth.get("type", "none")
+    if _auth_uses_login(auth):
+        return f"{kind} → run 'login'"
+    env = _auth_env_vars(auth)
+    return f"{kind} → set {', '.join(env)}" if env else kind
+
+
+def _render_catalog(entries: list[dict], title: str) -> None:
+    if not entries:
+        console.print("[dim]The catalog is empty.[/dim]")
+        return
+    table = Table(title=f"{title} ({len(entries)})")
+    table.add_column("Name", style="cyan")
+    table.add_column("Tier")
+    table.add_column("Domain")
+    table.add_column("Description", style="green")
+    for entry in sorted(entries, key=lambda e: (e.get("_tier", ""), e.get("_slug", ""))):
+        tier = entry.get("_tier", "community")
+        style = "bold green" if tier == "verified" else "yellow"
+        domain = "[bold blue]✓ dns[/bold blue]" if entry.get("domain_verified") is True else ""
+        table.add_row(entry.get("_slug", "?"), f"[{style}]{tier}[/{style}]", domain, str(entry.get("description", "")))
+    console.print(table)
+    console.print(
+        "[dim]Install one with: openapi-cli4ai catalog install <name>. "
+        "✓ dns = the API's domain owner published a DNS TXT record naming the maintainer.[/dim]"
+    )