Skip to main content

​
Install the CLI

The CLI requires Node 20 or newer. The installed superflag executable runs on Node directly; Bun is needed only for contributing to the source repository. The current CLI package is @superflag-sh/cli@0.7.0. When upgrading from 0.4, update automation to the documented exit vocabulary: missing resources now exit 5, while command usage and local validation errors exit 2. Branch on the machine envelope’s error.code and the published exit contract instead of preserving the older incidental status codes.

​
Verify the executable and contract

The version command prints the package version exactly. The contract command prints the stable machine-readable command, schema, capability, and exit-code contract bundled into the installed package.

​
Install the matching agent skill

From the root of a consumer repository:
The default target is .agents/skills/superflag/. Installation writes a provenance manifest that binds the vendored instructions to the exact installed CLI package. Commit the skill directory and run superflag skill check in CI. When intentionally upgrading the pinned CLI version, review the public skill diff and refresh it with superflag skill update. Do not copy instructions from a local Superflag source checkout or create a cross-repository symlink. Consumer repositories and CI must work without the Superflag development workspace.

​
First run

doctor --json checks token resolution, saved context, endpoints, and API reachability. It always prints its diagnostic result; healthy: false exits 1, so automation must inspect both JSON and process status.

​
Global options

Authenticate securely

Use browser login, environment injection, or a strict token file.

Agent workflows

Install the matching skill, then discover, diagnose, plan, apply, and verify.