Project pins

HubBound file

The project-level HubBound file — like package.json for kits and artifacts. Commit it so the team shares the same pins.

What it is

The HubBound file (hubbound.json on disk) lives at the project root and pins which artifacts and kits belong to that repo, at which exact versions (or latest).

It is the local-scope counterpart to global installs. Profile manifests reuse the same JSON shape, but live under the user config profiles/ tree — not in the repo.

Dev Profiles init command

What it is for

Declare the tooling a project expects. Running hubbound install with no arguments (when a manifest is found) bulk-installs every pin — similar to bare npm install reading package.json.

Local install and upgrade also write resolved versions back into the file so pins stay accurate.

File structure

Created by hubbound init. Three top-level fields — project name plus two pin maps.

{
  "name": "my-app",
  "artifacts": {
    "jane-a1b2c3/my-hook": "1.2.0"
  },
  "kits": {
    "jane-a1b2c3/ai-tools-bundle": "latest"
  }
}
name Project label. Defaults to the directory basename when you run hubbound init. Informational — not used as an install key.
artifacts Map of artifact pins. Each key is an author/name tag (e.g. jane-a1b2c3/my-hook); each value is the pinned version string ("1.2.0") or the literal "latest".
kits Map of kit pins — same shape as artifacts. Kits are bundles that pull multiple artifacts/tools in one go.
  • Pins are exact versions (or the literal latest) — not semver ranges.
  • latest is resolved at install/upgrade time; the resolved version is written back when recording entries.
  • HubBound finds the file by walking up from the current directory.

Compatible commands

These commands read and/or write the project hubbound.json.

$ hubbound init

$ hubbound install artifact jane-a1b2c3/my-hook

$ hubbound install

$ hubbound upgrade all

hubbound init Create hubbound.json in the current directory (fails if it already exists).
hubbound install No args + manifest found → install every pin. With args + local scope → install and record the pin.
hubbound upgrade In local scope, refresh pins in hubbound.json after upgrading (single entity or all).
--scope local|global Default scope: local if a hubbound.json is found above cwd, otherwise global.
install upgrade init

vs profile manifests

Same JSON schema. Different location and purpose.

  • Project hubbound.json → local/project scope; usually committed.
  • profiles/<name>/hubbound.json → global profile pins; under user config.
  • --profile on install always targets a profile file and forces global scope.
  • Bare hubbound install requires a project hubbound.json (or run hubbound init first).
Dev Profiles