Bundles compose existing Spec Kit components—extensions, presets, workflows, and steps—into a single, versioned, installable unit docs/reference/bundles.md3 Rather than adding new behavior, a bundle curates a stack of primitives that a specific team or role needs and installs them in one step through each component's own machinery docs/reference/bundles.md3-6
Bundles support full provenance tracking, allowing for clean removal or refreshes without collateral damage to other installed components docs/reference/bundles.md5-6
Users discover bundles through a catalog stack similar to extensions and presets. The specify bundle command group provides tools for searching and inspecting these packages before installation.
The specify bundle search command queries active catalogs for available bundles docs/reference/bundles.md9-11
verified for organization-curated entries, community otherwise) via the _trust_badge helper src/specify_cli/commands/bundle/__init__.py77-83 docs/reference/bundles.md18-19--json for machine-readable discovery, emitting fields like id, role, and install_policy src/specify_cli/commands/bundle/__init__.py157-173The specify bundle info <bundle_id> command displays full metadata and the fully expanded component set docs/reference/bundles.md23-31 This includes:
This diagram illustrates how the CLI layer interacts with the CatalogStack and BundleManifest to provide bundle metadata.
"Bundle Discovery Flow"
Sources: src/specify_cli/commands/bundle/__init__.py142-209 docs/reference/bundles.md9-32
The bundle installation process is designed to be idempotent and integration-aware.
Bundles can be installed from a catalog ID or a local path (zip artifact, directory, or bundle.yml) docs/reference/bundles.md36-44
install automatically invokes _run_init, which calls the specify init callback in-process src/specify_cli/commands/bundle/__init__.py92-126 docs/reference/bundles.md46-47claude), it will only install if the project matches that integration. The _resolve_init_integration helper manages this precedence src/specify_cli/commands/bundle/__init__.py128-136The following diagram maps the logical installation steps to the code entities and data persistence layers.
"Bundle Installation Logic"
Sources: src/specify_cli/commands/bundle/__init__.py92-136 src/specify_cli/bundler/models/records.py23 docs/reference/bundles.md46-47
The specify bundle group is implemented as a typer.Typer app with a nested catalog subcommand group src/specify_cli/commands/bundle/__init__.py25-36
| Command | Description | Key Options |
|---|---|---|
search | Search catalogs for bundles src/specify_cli/commands/bundle/__init__.py142 | --json, --offline |
info | Show expanded component set src/specify_cli/commands/bundle/__init__.py194 | --json, --offline |
install | Install bundle and its components docs/reference/bundles.md36 | --integration, --offline |
update | Refresh components to pinned versions docs/reference/bundles.md51 | --all, --offline |
remove | Uninstall bundle-owned components docs/reference/bundles.md63 | N/A |
list | List installed bundles in project docs/reference/bundles.md71 | --json |
validate | Check bundle.yml and references docs/reference/bundles.md96 | --path, --offline |
build | Create a distributable .zip artifact docs/reference/bundles.md109 | --path, --output |
catalog list | List bundle catalog sources tests/contract/test_bundle_cli.py98-99 | N/A |
Sources: src/specify_cli/commands/bundle/__init__.py25-36 docs/reference/bundles.md9-120 tests/contract/test_bundle_cli.py35-40
The bundle system relies on a "thin" management layer that delegates actual file operations to the underlying primitive systems.
update. Idempotency checks are ID-based; if a component ID exists, the bundler skips it unless an update is requested docs/reference/bundles.md61gemini cannot be installed into a project initialized for claude unless the project is switched first docs/reference/bundles.md46.specify/bundles/.records.json. This is managed via the load_records function src/specify_cli/commands/bundle/__init__.py23 This allows the remove command to safely delete only what it originally provided docs/reference/bundles.md5-6 docs/reference/bundles.md63-69Sources: docs/reference/bundles.md5-6 docs/reference/bundles.md46 docs/reference/bundles.md61 docs/reference/bundles.md63-69 src/specify_cli/commands/bundle/__init__.py23