Add infrahubctl marketplace CLI for fetching schemas and collections

[minitriga]

Summary

Adds a new infrahubctl marketplace sub-app with a get command that pulls schemas and collections from the public Infrahub Marketplace (marketplace.infrahub.app) into a local directory or to stdout.

infrahubctl marketplace get acme/network-base               # any item, auto-detected
infrahubctl marketplace get acme/network-base -v 1.2.0      # pin a schema version
infrahubctl marketplace get acme/starter-pack               # collection resolved automatically
infrahubctl marketplace get acme/network-base --stdout      # print to stdout, status to stderr
infrahubctl marketplace get acme/foo -o ./infra/schemas     # custom destination

What the command does

• REST-based — talks to the public marketplace REST API (/api/v1/schemas/..., /api/v1/collections/...); no GraphQL involved.
• Auto-detect schema vs collection — probes both endpoints in parallel. One command handles either item type without the caller needing to know which it is. On a rare namespace/name collision, schema wins with a warning; --collection/-c forces the other path.
• Version pinning — --version <semver> pins the download to a specific published schema version; default is whatever the marketplace resolves as latest (echoed back on success).
• Stdout mode — --stdout/-s writes content to real stdout and routes status, warnings, and errors to stderr, so the output can be piped into other tools (e.g. infrahubctl schema check once it grows stdin support). Collections are emitted as multi-doc YAML, with --- separators only inserted when a schema doesn't already start with one. No files are written when --stdout is set.
• Custom destination — --output-dir/-o (default ./schemas) controls where files land; missing parent directories are created.
• Marketplace override — --marketplace-url, infrahubctl.toml marketplace_url, or INFRAHUB_MARKETPLACE_URL env var let you point at staging or a local instance.
• Clean error taxonomy — distinct failure classes (invalid input, not found, network) with exit code 1 for deterministic failures and 2 for transient/network so CI can branch on it. No tracebacks on an unwritable output directory, a missing schema, or a connection refused.

Options

Option	Default	Purpose
IDENTIFIER (positional)	required	namespace/name — a schema or collection
-v, --version TEXT	latest	Pin to a specific published schema version (schemas only)
-c, --collection	auto-detect	Force the collection code path
-s, --stdout	off	Print to stdout, status to stderr; skips disk writes
-o, --output-dir PATH	./schemas	Where to write files
--marketplace-url TEXT	https://marketplace.infrahub.app	Override the marketplace host

Behaviour notes

• Output lines state the resolved item type (Downloaded schema … / Collection …) so the user can detect an unintended match in a collision case.
• Passing --version alongside a collection identifier prints a warning and proceeds with the collection download, rather than failing.
• A missing version on an existing schema reports "no published version ''" with a hint to drop --version, distinct from "schema not found".

Out of scope

No --load convenience flag. get is fetch-only — chain with infrahubctl schema load <dir> (or pipe via --stdout once stdin support lands) to push the result into a running Infrahub.

Test plan

• uv run pytest tests/unit/ctl/test_marketplace_app.py — 20 tests covering auto-detect, collision, error classes, --version, --output-dir, --marketplace-url, --collection override, and --stdout mode (single schema, collection, separator injection).
• uv run invoke lint — ruff, ty, mypy, vale, markdownlint all clean.
• uv run invoke generate-infrahubctl — docs/docs/infrahubctl/infrahubctl-marketplace.mdx regenerated.
• End-to-end smoke test against the live marketplace: infrahubctl marketplace get nonexistent/nonexistent returns the expected not-found message with exit 1.

Artefacts

Full spec, plan, research, contracts, quickstart, and task breakdown under specs/001-marketplace-api-update/ for reviewers who want the design rationale (auto-detect strategy evaluation, error taxonomy decisions, collision precedence).

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying infrahub-sdk-python with    Cloudflare Pages

Latest commit:	63f1162
Status:	✅  Deploy successful!
Preview URL:	https://a209d48c.infrahub-sdk-python.pages.dev
Branch Preview URL:	https://knotty-dibble.infrahub-sdk-python.pages.dev

View logs

[codecov]

Codecov Report

❌ Patch coverage is 91.13924% with 14 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
infrahub_sdk/ctl/marketplace.py	90.90%	8 Missing and 6 partials ⚠️

@@            Coverage Diff             @@
##           stable     #952      +/-   ##
==========================================
+ Coverage   81.41%   81.67%   +0.26%     
==========================================
  Files         134      135       +1     
  Lines       11347    11626     +279     
  Branches     1703     1759      +56     
==========================================
+ Hits         9238     9496     +258     
- Misses       1566     1577      +11     
- Partials      543      553      +10     

Flag	Coverage Δ
integration-tests	41.57% <31.64%> (-0.27%)	⬇️
python-3.10	55.05% <90.50%> (+0.69%)	⬆️
python-3.11	55.05% <90.50%> (+0.70%)	⬆️
python-3.12	55.07% <90.50%> (+0.72%)	⬆️
python-3.13	55.05% <90.50%> (+0.69%)	⬆️
python-3.14	55.05% <90.50%> (+0.69%)	⬆️
python-filler-3.12	22.38% <1.26%> (-0.37%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
infrahub_sdk/config.py	91.19% <100.00%> (+0.05%)	⬆️
infrahub_sdk/ctl/cli_commands.py	72.54% <100.00%> (+0.21%)	⬆️
infrahub_sdk/ctl/config.py	67.85% <100.00%> (+0.58%)	⬆️
infrahub_sdk/ctl/marketplace.py	90.90% <90.90%> (ø)

... and 54 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[cubic-dev-ai]

3 issues found across 12 files

_{You’re at about 95% of the monthly review limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="infrahub_sdk/ctl/marketplace.py">

<violation number="1" location="infrahub_sdk/ctl/marketplace.py:99">
P1: Partial probe failures are misclassified as not-found. A transport failure on either endpoint (when no 200 winner exists) should return a network error, not deterministic not-found.</violation>

<violation number="2" location="infrahub_sdk/ctl/marketplace.py:243">
P1: Network/HTTP errors during the actual download path can still exit with code 1 because uncaught `httpx` exceptions are handled by the default decorator exit code.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[ogenstad]

Is this configuration actually used anywhere? It seems like the app is using either the parameter defined when running the command line or the entry in the infrahubctl config which shadows this one.

It looks like this is just dead code now, but could be fine if we later refactor infrahubctl and remove that config section alltogether.

[minitriga]

The marketplace_url field in ConfigBase isn't wired into the marketplace command today (which reads from SETTINGS.active.marketplace_url). It's a forward-looking field intended to survive once we retire the infrahubctl.toml / Settings layer — happy to drop it now if you'd prefer to keep things minimal.

[ogenstad]

By default we'll have a falsy statement here, i.e. None the function signature makes us believe that collection can have three states True, False, None which is not true, the only possible options are True or None as there doesn't seem to be a way to set it to False. As a result we have some dead code below that also acknowledges this. It seems like we compensate for the error here with code that we know will be unreachable below. This should just be a bool that defaults to False.

[minitriga]

Fixed in 69fc5ba — changed to collection: bool = False with is_flag=True. The elif collection: / else: branches are now just if collection: ... else: auto-detect, removing the unreachable force-schema path entirely.

[ogenstad]

Refactor once the param above has been changed to a pure bool and not a bool | None, then reverse the condition so the first option is the True one.

[ogenstad]

I'd also suggest that after the first check for collections we add the type as:

if collection:
    item_type: MarketplaceItemType = "collection"

[minitriga]

Fixed in 69fc5ba — condition is now if collection: item_type: MarketplaceItemType = "collection" / else: auto-detect.

[minitriga]

Fixed in 69fc5ba — added item_type: MarketplaceItemType = "collection" on the collection branch.

[ogenstad]

In general code is easier to read if we lead with a truthy statement, so:

if prefetched:
    resp = prefetched
else:
    resp = await client.get(_collection_url(base_url, namespace, name))

[minitriga]

Fixed in 69fc5ba — if prefetched: now leads.

[ogenstad]

I'd also suggest that after the first check for collections we add the type as:

if collection:
    item_type: MarketplaceItemType = "collection"

[ogenstad]

When we have this many parameters to a function I'd suggest to use keyword arguments for everything so that it's crystal clear regarding what parameter each one is instead on relying on positional parameters.

[minitriga]

Fixed in 69fc5ba — both _download_schema and _download_collection calls now use keyword arguments throughout.

[ogenstad]

I don't really have a strong opinion here, but if a user specifically requests a specific version but ends up on a collection instead I wonder if a better approach would be to fail with and error so that the user could choose if they want to remove the --version param instead or if this is fine. Only raising a thought here.

[minitriga]

Kept the warn-and-proceed behaviour for now — feels less surprising for a user who runs get acme/starter-pack --version 1.0.0 and just forgot collections don't have versions. Happy to flip it to a hard error if you'd prefer.

[ogenstad]

Here we assume that we have the correct order of the variables returned from _parse_identifier(identifier).

I think it could be a bit cleaner to have _parse_identifier return an object like this:

  @dataclass(frozen=True, slots=True)
  class MarketplaceIdentifier:
      namespace: str
      name: str

That way there's no confusion and there are several other functions where we pass in both name and namespace which could be replaced by one variable.

[minitriga]

Fixed in 69fc5ba — _parse_identifier now returns a MarketplaceIdentifier(namespace, name) frozen dataclass, eliminating positional ordering assumptions.

[ogenstad]

Assuming we don't want to support an empty string as a version I'd change this to:

if version and schema_confirmed_exists:

[minitriga]

Fixed in 69fc5ba — changed to if version and schema_confirmed_exists:.

[cubic-dev-ai]

1 issue found across 10 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="infrahub_sdk/ctl/marketplace.py">

<violation number="1" location="infrahub_sdk/ctl/marketplace.py:255">
P1: ZIP entry path not validated before write. This can write files outside --output-dir. Validate and block absolute/parent-traversal paths before writing.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: ZIP entry path not validated before write. This can write files outside --output-dir. Validate and block absolute/parent-traversal paths before writing.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At infrahub_sdk/ctl/marketplace.py, line 255:

<comment>ZIP entry path not validated before write. This can write files outside --output-dir. Validate and block absolute/parent-traversal paths before writing.</comment>

<file context>
@@ -182,55 +214,49 @@ async def _download_collection(
+        _mkdir_or_fail(output_dir)
+        for schema_name in schema_names:
+            content = archive.read(schema_name).decode("utf-8")
+            file_path = output_dir / schema_name
+            file_path.write_text(content, encoding="utf-8")
+            console.print(f"[green]Downloaded {schema_name} -> {file_path}")
</file context>

Suggested change

	file_path = output_dir / schema_name
	candidate_path = Path(schema_name)
	if candidate_path.is_absolute() or ".." in candidate_path.parts:
	_fail(_ErrorClass.INVALID_INPUT, f"Invalid schema path in archive: {schema_name}")
	file_path = (output_dir / candidate_path).resolve()
	if output_dir.resolve() not in file_path.parents and file_path != output_dir.resolve():
	_fail(_ErrorClass.INVALID_INPUT, f"Invalid schema path in archive: {schema_name}")