@airig/cli

airig

Distribute and manage AI setups across coding agents from one project-local .ai/ directory.

Usage

Install the CLI globally to use the short airig command:

npm install --global @airig/cli

airig add <owner/repo>[@version]
airig add .
airig update <owner/repo>@<version>
airig remove [owner/repo|.]
airig publish [tag]

For one-off usage without a global install, run the npm Package directly:

npx @airig/cli add <owner/repo>[@version]
npx @airig/cli add .
npx @airig/cli update <owner/repo>@<version>
npx @airig/cli remove [owner/repo|.]
npx @airig/cli publish [tag]

The Package is named @airig/cli; the installed binary is airig.

What It Does

airig installs selected AI Setup artifacts from immutable GitHub releases into .ai/, then links them into provider-specific config paths. It supports local author dogfooding with add ., explicit version updates, interactive removal, and publishing .ai/ as an ai.zip release asset.

Remote Setup Releases are pinned to exact versions in .ai/ai.json. add and update verify GitHub release immutability before writing remote content.

Maintainer Releases

Use Package releases to publish the @airig/cli npm Package, which provides the airig CLI:

pnpm release

The release script is maintainer-facing. It uses bumpp to choose the next Package version, update Package metadata, create the release commit, create a v<version> tag, and push the commit and tag. Pushed v* tags trigger .github/workflows/publish-package.yml, which installs dependencies, runs tests, builds the CLI, and publishes the Package to npm.

npm publishing uses trusted publishing with GitHub Actions OIDC. Do not add a long-lived npm token for Package releases.

Package releases are separate from Setup Releases. airig publish [tag] creates a GitHub immutable Setup Release containing ai.zip from .ai/; it does not publish the npm Package.

Author Workflow

• Create AI Setup artifacts under .ai/.
• Run airig add . to wire local artifacts into your repo.
• Tag a release with your normal git tooling.
• Run airig publish to upload ai.zip to an immutable GitHub Setup Release.
• Share airig add yourname/repo.

For AI Setup repositories, use bumpp to create and push release tags from a package script:

{
  "scripts": {
    "release": "bumpp"
  }
}

To publish Setup Releases from your AI Setup repository with GitHub Actions, copy resources/templates/publish.yml to .github/workflows/publish.yml in that repository. The workflow publishes when bumpp pushes a v* tag and expects an AIRIG_PUBLISH_TOKEN repository secret. Create that secret from a fine-grained GitHub PAT scoped only to the Setup Release repository with:

• Contents: Read and write
• Administration: Read-only

Requirements

• Node.js 24.11.0 or newer in the Node 24 release line.
• GitHub immutable releases enabled for repositories that publish Setup Releases.
• GITHUB_TOKEN when running publish. For local use or custom GitHub Actions workflows, use a fine-grained GitHub PAT scoped to the Setup Release repository with Contents read/write access to create releases and Administration read-only access so airig publish can verify immutable releases are enabled before publishing.