StageFreight — CLI Reference

Complete reference for all stagefreight commands, flags, and subcommands.

For conceptual documentation and usage examples, see:

Docker Build — build, push, and manage container images
Release Management — create releases, generate notes, sync across forges
Narrator & Badges — content composition and badge generation
Security Scanning — vulnerability scanning and SBOM generation
Linter Configuration — lint modules and cache contract

Generated sections below are assembled from docs/modules/cli-reference.md via Narrator.

Command Index

stagefreight — Declarative lifecycle runtime — there's a setting for every stage, this is theatre!
stagefreight badge — Badge generation commands
stagefreight badge generate — Generate SVG badges from config or flags
stagefreight build — Build artifacts (binaries, images)
stagefreight build binary — Build Go binaries
stagefreight ci — CI subsystem commands
stagefreight ci render — Render forge-native CI pipeline from .stagefreight.yml
stagefreight ci run — Run a CI subsystem
stagefreight commit — Create a conventional commit from staged or specified files
stagefreight completion — Generate the autocompletion script for the specified shell
stagefreight completion bash — Generate the autocompletion script for bash
stagefreight completion fish — Generate the autocompletion script for fish
stagefreight completion powershell — Generate the autocompletion script for powershell
stagefreight completion zsh — Generate the autocompletion script for zsh
stagefreight component — GitLab CI component management
stagefreight component docs — Generate input documentation from component spec files
stagefreight config — Inspect and manage StageFreight configuration
stagefreight config render — Show the effective config after preset resolution
stagefreight config resolve — Show the config resolution chain with provenance
stagefreight dependency — Dependency management commands
stagefreight dependency update — Update outdated dependencies
stagefreight docker — Docker lifecycle — build, drift, reconcile
stagefreight docker build — Build and push container images
stagefreight docker drift — Show drift status for all Docker compose stacks
stagefreight docker readme — Sync README to container registries
stagefreight docs — Documentation generation commands
stagefreight docs generate — Generate reference documentation from code
stagefreight docs run — Run all enabled documentation generators
stagefreight du — Storage-attribution diagnostic — what is eating disk today
stagefreight gitops — GitOps intelligence — inspect, impact, reconcile
stagefreight gitops impact — Compute which kustomizations are affected by recent changes
stagefreight gitops inspect — Discover and display the Flux dependency graph
stagefreight gitops reconcile — Reconcile affected Flux kustomizations
stagefreight glossary — Show the repo's change-language conventions
stagefreight governance — Governance reconciliation and fleet management
stagefreight governance reconcile — Reconcile governance policy to satellite repos
stagefreight help — Help about any command
stagefreight lint — Run code quality checks
stagefreight manifest — Generate and inspect build manifests
stagefreight manifest diff — Compare two manifests (not yet implemented)
stagefreight manifest generate — Generate manifest from build config and Dockerfile
stagefreight manifest inspect — Pretty-print manifest or specific sections
stagefreight migrate — Migrate config to the latest schema version
stagefreight narrator — Compose and inject content into markdown files
stagefreight narrator compose — Compose modules into a file section from the shell
stagefreight narrator run — Run narrator items from config
stagefreight props — Typed presentation items (badges, etc.)
stagefreight props categories — List prop categories with type counts
stagefreight props list — List all available prop types
stagefreight props render — Resolve and render a prop as markdown
stagefreight props show — Show details for a prop type
stagefreight push — Synchronize the current branch with its remote
stagefreight reconcile — Reconcile infrastructure to declared state
stagefreight release — Release management commands
stagefreight release create — Create a release on the forge and sync to targets
stagefreight release notes — Generate release notes from conventional commits
stagefreight release prune — Prune old releases using retention policy
stagefreight release sync — Project releases from primary forge to mirrors
stagefreight security — Security scanning commands
stagefreight security scan — Run vulnerability scan and generate SBOM
stagefreight sign — Attach an additional signature to already-built release artifacts
stagefreight signing — Signing identity + trust-anchor maintenance
stagefreight signing anchor — Regenerate the canonical signing trust anchor (managed SECURITY.md section)
stagefreight tag — Plan, validate, and create a release tag
stagefreight toolchain — Manage StageFreight toolchains
stagefreight toolchain list — Show installed toolchain versions
stagefreight toolchain prune — Remove old toolchain versions from cache
stagefreight update — Update this stagefreight binary in place from the published image
stagefreight version — Print the version

stagefreight

Usage: stagefreight stagefreight

StageFreight — a declarative lifecycle runtime that governs Git as the source of truth, enforcing operator-defined intent across GitOps workflows, Kubernetes, Docker, and CI ecosystems.

Flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

badge — Badge generation commands
build — Build artifacts (binaries, images)
ci — CI subsystem commands
commit — Create a conventional commit from staged or specified files
completion — Generate the autocompletion script for the specified shell
component — GitLab CI component management
config — Inspect and manage StageFreight configuration
dependency — Dependency management commands
docker — Docker lifecycle — build, drift, reconcile
docs — Documentation generation commands
du — Storage-attribution diagnostic — what is eating disk today
gitops — GitOps intelligence — inspect, impact, reconcile
glossary — Show the repo's change-language conventions
governance — Governance reconciliation and fleet management
help — Help about any command
lint — Run code quality checks
manifest — Generate and inspect build manifests
migrate — Migrate config to the latest schema version
narrator — Compose and inject content into markdown files
props — Typed presentation items (badges, etc.)
push — Synchronize the current branch with its remote
reconcile — Reconcile infrastructure to declared state
release — Release management commands
security — Security scanning commands
sign — Attach an additional signature to already-built release artifacts
signing — Signing identity + trust-anchor maintenance
tag — Plan, validate, and create a release tag
toolchain — Manage StageFreight toolchains
update — Update this stagefreight binary in place from the published image
version — Print the version

stagefreight badge

Usage: stagefreight badge badge

Generate SVG badges from config or ad-hoc flags.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

generate — Generate SVG badges from config or flags

stagefreight badge generate

Usage: stagefreight badge generate [name...]

Generate SVG badges defined in narrator config items.

Config-driven (no flags): generates all narrator badge items with output paths, or named items if specified. Ad-hoc (--label + --value): generates a single badge from flags.

Flags:

Name	Type	Default	Description
`--color`	string	`#4c1`	ad-hoc badge color (hex)
`--label`	string	—	ad-hoc badge label (left side)
`--output`	string	`.stagefreight/badges/custom.svg`	output file path
`--status`	string	—	status-driven color: passed, warning, critical
`--value`	string	—	ad-hoc badge value (right side)

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

See also: stagefreight badge

stagefreight build

Usage: stagefreight build build

Build binaries, container images, and other artifacts.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

binary — Build Go binaries

See also: stagefreight · stagefreight build binary

stagefreight build binary

Usage: stagefreight build binary binary

Build Go binaries for configured platforms.

Compiles Go binaries using go build, cross-compiling for all configured platforms. Injects version, commit, and build date via ldflags.

Flags:

Name	Type	Default	Description
`--build`	string	—	build specific entry by ID (default: all)
`--dry-run`	bool	—	show plan without executing
`--local`	bool	—	build for current platform only
`--output-dir`	string	—	override output directory
`--platform`	stringSlice	—	override platforms (comma-separated)

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

See also: stagefreight build

stagefreight ci

Usage: stagefreight ci ci

Provider-neutral CI entry points.

Generated CI files translate forge-native context into SF_CI_* environment variables, then call stagefreight ci run . Phase behavior is configured in .stagefreight.yml. CI files are generated by ci render.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

render — Render forge-native CI pipeline from .stagefreight.yml
run — Run a CI subsystem

stagefreight ci render

Usage: stagefreight ci render <forge>

Generate a forge-native CI pipeline file from StageFreight configuration.

Supported forges: gitlab, github, gitea, forgejo, azuredevops (azuredevops is experimental)

The rendered file is a committed generated artifact. StageFreight owns the pipeline document — it is not hand-maintained.

Modes: --write Write the rendered pipeline to the repo (e.g. .gitlab-ci.yml) --check Verify the committed pipeline matches what would be rendered (exit 1 if stale) (default) Print the rendered pipeline to stdout

Flags:

Name	Type	Default	Description
`--check`	bool	—	verify committed pipeline is up to date
`--write`	bool	—	write rendered pipeline to repo

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

See also: stagefreight ci · stagefreight ci run

stagefreight ci run

Usage: stagefreight ci run <subsystem>

Run a CI phase or legacy subsystem by name.

Canonical phases: audition, perform, review, publish, narrate

Generated CI files set SF_CI_* environment variables, then call this command. Phase behavior is configured in .stagefreight.yml.

Exit codes: 0=success, 1=phase error, 2=config error, 3=context error

Flags:

Name	Type	Default	Description
`--tag`	string	—	release tag (overrides SF_CI_TAG for release subsystem)
`-h, --help`	bool	—	help for run

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

See also: stagefreight ci · stagefreight ci render

stagefreight commit

Usage: stagefreight commit [summary] [paths...]

Create a git commit with conventional commit formatting.

Summary can be provided as a positional argument or via --message. Paths can be provided as positional args (after summary or after --), via --add flags, --all, or from the existing staging area.

In CI environments, the push refspec is auto-detected from CI_COMMIT_REF_NAME or CI_COMMIT_BRANCH. Use --refspec for explicit control.

Examples: stagefreight commit -t docs -m "refresh generated docs" stagefreight commit -t docs "refresh generated docs" stagefreight commit -t feat "add api validation" src/api/ src/config/config.go stagefreight commit -t fix -m "handle nil config" -- src/api/ src/config/config.go stagefreight commit -t docs --add README.md -m "document commit flow" -- docs/ examples/ stagefreight commit --dry-run -t docs -m "test generated docs" --add docs/ -- README.md stagefreight commit -t feat --breaking -m "replace auth middleware" -- src/auth/ stagefreight commit -t docs -m "refresh docs" --push --refspec HEAD:refs/heads/main stagefreight commit -t feat -m "hotfix auth flow" --push --refspec HEAD:refs/heads/release/v1

Flags:

Name	Type	Default	Description
`--add`	stringSlice	—	files/dirs to stage (repeatable, supports globs)
`--all`	bool	—	stage all changes (git add -A)
`--body`	string	—	commit body (appended after blank line)
`--breaking`	bool	—	mark as breaking change (!)
`--dry-run`	bool	—	show what would be committed without executing
`--maintainer-override`	bool	—	bypass governance/policy failures when the commit path is still deterministic

does NOT bypass mechanical failures (detached HEAD, hook rejection, sync errors)
bypassed checks are recorded in output and result |

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight completion

Usage: stagefreight completion completion

Generate the autocompletion script for stagefreight for the specified shell. See each sub-command's help for details on how to use the generated script.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

bash — Generate the autocompletion script for bash
fish — Generate the autocompletion script for fish
powershell — Generate the autocompletion script for powershell
zsh — Generate the autocompletion script for zsh

stagefreight completion bash

Usage: stagefreight completion bash bash

Generate the autocompletion script for the bash shell.

This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager.

To load completions in your current shell session:

source <(stagefreight completion bash)

To load completions for every new session, execute once:

Linux:

stagefreight completion bash > /etc/bash_completion.d/stagefreight

macOS:

stagefreight completion bash > $(brew --prefix)/etc/bash_completion.d/stagefreight

You will need to start a new shell for this setup to take effect.

Flags:

Name	Type	Default	Description
`--no-descriptions`	bool	—	disable completion descriptions

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight completion fish

Usage: stagefreight completion fish fish

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

stagefreight completion fish | source

To load completions for every new session, execute once:

stagefreight completion fish > ~/.config/fish/completions/stagefreight.fish

You will need to start a new shell for this setup to take effect.

Flags:

Name	Type	Default	Description
`--no-descriptions`	bool	—	disable completion descriptions

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight completion powershell

Usage: stagefreight completion powershell powershell

Generate the autocompletion script for powershell.

To load completions in your current shell session:

stagefreight completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command to your powershell profile.

Flags:

Name	Type	Default	Description
`--no-descriptions`	bool	—	disable completion descriptions

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight completion zsh

Usage: stagefreight completion zsh zsh

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

source <(stagefreight completion zsh)

To load completions for every new session, execute once:

Linux:

stagefreight completion zsh > "${fpath[1]}/_stagefreight"

macOS:

stagefreight completion zsh > $(brew --prefix)/share/zsh/site-functions/_stagefreight

You will need to start a new shell for this setup to take effect.

Flags:

Name	Type	Default	Description
`--no-descriptions`	bool	—	disable completion descriptions

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight component

Usage: stagefreight component component

Parse component specs, generate documentation, and manage component releases.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

docs — Generate input documentation from component spec files

stagefreight component docs

Usage: stagefreight component docs docs

Parse GitLab CI component spec files and generate markdown documentation tables for their inputs.

Supports custom group metadata via comments:

input_section_name- Group Title

input_section_desc- Group description text

Output modes:

Default: print markdown to stdout
--output: write markdown to a file
--readme: inject docs between markers in target file

Flags:

Name	Type	Default	Description
`--readme`	string	—	inject docs between markers in target file (section name from narrator config)
`--spec`	stringSlice	—	component spec file(s) to parse (repeatable)
`-o, --output`	string	—	write docs to file

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

See also: stagefreight component

stagefreight config

Usage: stagefreight config config

Commands for inspecting resolved config, rendering effective config, and managing governance.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

render — Show the effective config after preset resolution
resolve — Show the config resolution chain with provenance

stagefreight config render

Usage: stagefreight config render render

Renders the effective StageFreight config from .stagefreight.yml.

Without --gated: shows config after preset resolution (what config declares). With --gated: shows runnable plan (what will actually execute after capability gating).

Flags:

Name	Type	Default	Description
`--gated`	bool	—	Show runnable plan after capability gating

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight config resolve

Usage: stagefreight config resolve resolve

Shows how the effective config was resolved:

Preset sources and what they contributed
Source provenance for each value

Flags:

Name	Type	Default	Description
`-v, --verbose`	bool	—	Show full resolution trace

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)

stagefreight dependency

Usage: stagefreight dependency dependency

Aliases: deps

Resolve, update, and audit project dependencies.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

update — Update outdated dependencies

stagefreight dependency update

Usage: stagefreight dependency update [path]

Resolve, update, and verify project dependencies.

Generates artifacts: deps.patch, deps-report.md, resolve.json. Use --dry-run to resolve and report without applying changes.

Flags:

Name	Type	Default	Description
`--bundle`	bool	—	include deps-updated.tgz
`--dry-run`	bool	—	resolve and report without applying changes
`--ecosystem`	stringSlice	—	filter to specific ecosystem(s)
`--no-verify`	bool	—	skip go test after update
`--no-vulncheck`	bool	—	skip govulncheck after update
`--output`	string	`.stagefreight/deps`	output directory for artifacts
`--policy`	string	`all`	update policy: all, security

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

See also: stagefreight dependency

stagefreight docker

Usage: stagefreight docker docker

Docker lifecycle intelligence and container image management.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

build — Build and push container images
drift — Show drift status for all Docker compose stacks
readme — Sync README to container registries

stagefreight docker build

Usage: stagefreight docker build build

Build container images using docker buildx.

Detects Dockerfiles, resolves tags from git, and pushes to configured registries.

Flags:

Name	Type	Default	Description
`--build`	string	—	build a specific entry by ID (default: all)
`--build-mode`	string	—	build execution strategy: crucible (self-proving self-build)
`--dry-run`	bool	—	show the plan without executing
`--local`	bool	—	build for current platform, load into daemon
`--platform`	stringSlice	—	override platforms (comma-separated)
`--tag`	stringSlice	—	override/add tags
`--target`	string	—	override Dockerfile target stage

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight docker drift

Usage: stagefreight docker drift drift

Scan IaC, resolve inventory targets, and compute drift for each stack. Read-only — no mutations. Reuses the same plan model as reconcile.

Examples: stagefreight docker drift

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight docker readme

Usage: stagefreight docker readme readme

Push README content to container registries that support description APIs.

Docker Hub receives both short (100-char) and full markdown descriptions. Quay and Harbor receive short descriptions only. Other registries are silently skipped.

Flags:

Name	Type	Default	Description
`--dry-run`	bool	—	show prepared content without pushing

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight docs

Usage: stagefreight docs docs

Generate reference documentation from code and config structs.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

generate — Generate reference documentation from code
run — Run all enabled documentation generators

stagefreight docs generate

Usage: stagefreight docs generate generate

Generate CLI and config reference documentation as markdown fragments.

Output files are written to docs/modules/ and are designed to be assembled into reference pages via narrator's kind: include.

Generated files: docs/modules/cli-reference.md — CLI command reference from Cobra tree docs/modules/config-reference.md — Config schema reference from Go structs

Flags:

Name	Type	Default	Description
`--output-dir`	string	`docs/modules`	output directory for generated fragments

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight docs run

Usage: stagefreight docs run run

Composed command that runs all enabled generators from docs config: badges, reference docs, narrator, and docker readme.

Reads docs.generators in .stagefreight.yml to determine which generators to run. This is the same logic used by 'stagefreight ci run docs' (without auto-commit — use ci run docs for that).

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight du

Usage: stagefreight du du

Report what StageFreight and its CI occupy on disk, grouped so an operator can act: the persistent cache mount (toolchains by version, build/scan caches by subsystem, per-project rust targets), the Docker daemon(s) (host vs dind, images by family with tags, dangling, volumes, build cache), and discovered repositories. Bars are share of total disk; a reclaim ledger names the biggest wins. Read-only.

Flags:

Name	Type	Default	Description
`--cache`	string	—	persistent cache mount path (default /stagefreight; on a runner host use e.g. /opt/docker/gitlab-runner/stagefreight)
`--json`	bool	—	machine-readable JSON output
`--max-depth`	int	`3`	repository discovery recursion depth
`--no-repos`	bool	—	skip repository discovery
`--repos`	string	—	comma-separated roots to discover repositories under (default: $HOME)

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight gitops

Usage: stagefreight gitops gitops

GitOps intelligence — inspect, impact, reconcile

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

impact — Compute which kustomizations are affected by recent changes
inspect — Discover and display the Flux dependency graph
reconcile — Reconcile affected Flux kustomizations

stagefreight gitops impact

Usage: stagefreight gitops impact impact

Determine which Flux Kustomizations are affected by file changes between two refs. Walks the reverse dependency graph for transitive impact. Outputs the ordered reconcile set.

Flags:

Name	Type	Default	Description
`--base`	string	`HEAD~1`	base ref for diff
`--head`	string	`HEAD`	head ref for diff

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight gitops inspect

Usage: stagefreight gitops inspect inspect

Walk the repository and discover all Flux Kustomization objects. Display the dependency graph, paths, orphans, and bootstrap state.

No configuration needed — everything is derived from actual manifests.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight gitops reconcile

Usage: stagefreight gitops reconcile reconcile

Reconcile Flux kustomizations affected by recent changes. By default, computes impact from HEAD~1..HEAD and reconciles the affected set. Use --all to reconcile everything, or --only to target a specific kustomization.

Flags:

Name	Type	Default	Description
`--all`	bool	—	reconcile all kustomizations
`--dry-run`	bool	—	preview reconcile set without executing
`--only`	string	—	reconcile only this kustomization (ns/name)

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight glossary

Usage: stagefreight glossary glossary

Display the glossary of commit types, aliases, and release visibility defined in .stagefreight.yml.

This is the shared semantic model used by commit authoring, tag planning, and release rendering. Use --json for machine-readable output.

Flags:

Name	Type	Default	Description
`--json`	bool	—	output as JSON

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight governance

Usage: stagefreight governance governance

Commands for reconciling governance policy across governed repositories.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

reconcile — Reconcile governance policy to satellite repos

stagefreight governance reconcile

Usage: stagefreight governance reconcile reconcile

Reads governance clusters from the policy repo, resolves presets, generates managed configs, and commits to satellite repos.

Forge identity (provider, URL, credentials) is read from sources.primary in .stagefreight.yml — the same config every StageFreight repo uses.

Use --dry-run to preview changes without committing.

Flags:

Name	Type	Default	Description
`--apply`	bool	—	Actually commit changes (required for real writes)
`--dry-run`	bool	—	Preview changes without committing
`--path`	string	—	Override governance clusters file path
`--ref`	string	—	Override governance source ref
`--source`	string	—	Override governance source repo URL

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

See also: stagefreight governance

stagefreight help

Usage: stagefreight help [command]

Help provides help for any command in the application. Simply type stagefreight help [path to command] for full details.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight lint

Usage: stagefreight lint [paths...]

Run cache-aware, delta-only code quality checks.

By default, only changed files are scanned (--level changed). Use --level full or --all to scan everything.

Modules run in parallel and results are cached by content hash.

Flags:

Name	Type	Default	Description
`--all`	bool	—	scan all files (shorthand for --level full)
`--baseline`	bool	—	diff against the merge-base: mark newly-introduced non-text artifacts and findings
`--dry-run`	bool	—	with --fix-safe: preview what would change without writing
`--fix-safe`	bool	—	auto-apply proven-safe fixes (trailing whitespace, final newline) to authored files
`--level`	string	—	scan level: changed or full (default: from config, then changed)
`--module`	stringSlice	—	run only these modules (comma-separated)
`--no-cache`	bool	—	disable cache (clear and rescan)
`--no-module`	stringSlice	—	skip these modules (comma-separated)

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight manifest

Usage: stagefreight manifest manifest

Manifest generates a normalized view of build evidence from Dockerfile analysis, SBOM data, and security scans into a single deterministic JSON document.

Subcommands: generate Create manifest from build config and Dockerfile inspect Pretty-print manifest or specific sections diff Compare two manifests (not yet implemented)

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

diff — Compare two manifests (not yet implemented)
generate — Generate manifest from build config and Dockerfile
inspect — Pretty-print manifest or specific sections

stagefreight manifest diff

Usage: stagefreight manifest diff <manifest-a> <manifest-b>

Diff compares two manifest JSON files and shows what changed between them.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight manifest generate

Usage: stagefreight manifest generate generate

Generate creates a normalized manifest JSON for each build defined in .stagefreight.yml. The manifest captures inventory (packages, binaries, base image versions) extracted from Dockerfile analysis.

Output location is controlled by manifest.mode in config: ephemeral temp location, discarded after use (default) workspace .stagefreight/manifests/, not auto-committed commit included in docs commit publish exported as release asset

Flags:

Name	Type	Default	Description
`--build-id`	string	—	generate for a specific build ID only
`--dry-run`	bool	—	preview manifest without writing files
`--output`	string	—	output format: json (default: summary)
`--platform`	string	—	filter to a specific platform (os/arch)

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight manifest inspect

Usage: stagefreight manifest inspect [manifest-path]

Inspect reads a manifest JSON and displays it in human-readable format.

If no path is given, resolves the manifest from config and build ID. Use --section to extract a specific dot-path (e.g., inventories.pip). Use --format to control output: json, table, human (default: human).

Flags:

Name	Type	Default	Description
`--build-id`	string	—	resolve manifest for a specific build ID
`--format`	string	`human`	output format: json, table, human
`--section`	string	—	dot-path into manifest (e.g., inventories.pip)

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight migrate

Usage: stagefreight migrate [file]

Migrate a .stagefreight.yml config file to the latest schema version.

By default, prints the migrated config to stdout. Use --in-place to overwrite the file, or --output to write to a different path.

Currently the latest schema version is 1. Future schema changes will add migration steps here.

Note: The pre-version config format (before version: 1) is not supported by this migration tool — it was an unversioned alpha that must be rewritten.

Flags:

Name	Type	Default	Description
`-i, --in-place`	bool	—	overwrite the config file in place
`-o, --output`	string	—	write migrated config to this path

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight narrator

Usage: stagefreight narrator narrator

Narrator manages README sections using markers.

Compose badges, shields, text, and other modules into managed sections. Content between markers is owned by StageFreight and replaced on each run. Everything outside markers is never touched.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

compose — Compose modules into a file section from the shell
run — Run narrator items from config

stagefreight narrator compose

Usage: stagefreight narrator compose [items...]

Compose modules into a managed section of a markdown file.

Items are specified as type:value pairs with optional comma-separated fields:

badge:,output:,link: shield:,link:,label: text: component: break:

Examples: stagefreight narrator compose -f README.md -s badges
badge:release,output:.stagefreight/badges/release.svg,link:https://github.com/myorg/myrepo/releases
shield:docker/pulls/myorg/myrepo,link:https://hub.docker.com/r/myorg/myrepo

stagefreight narrator compose -f README.md --plain
--placement-match "^## Installation" --placement-position above
text:"## Prerequisites"

Flags:

Name	Type	Default	Description
`--dry-run`	bool	—	preview changes without writing
`--inline`	bool	—	insert inline (no newline padding)
`--placement-match`	string	—	anchor to a regex match
`--placement-position`	string	`below`	position: above, below (default), replace
`--placement-section`	string	—	anchor to a named section
`--plain`	bool	—	output without section markers
`-f, --file`	string	—	target file path (required)
`-s, --section`	string	—	target section name

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight narrator run

Usage: stagefreight narrator run run

Execute all narrator items defined in the narrator config.

Each item is composed from its kind and placed into the target file according to its placement markers. Existing managed content between markers is replaced idempotently.

Items sharing the same placement markers are composed together: inline items are joined with spaces, block items with newlines.

Flags:

Name	Type	Default	Description
`--dry-run`	bool	—	preview changes without writing files

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight props

Usage: stagefreight props props

Props is StageFreight's composable presentation subsystem.

Declarative, discoverable, validated, schema-aware presentation items. Badges are the first prop format. Use 'props list' to see all available types.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

categories — List prop categories with type counts
list — List all available prop types
render — Resolve and render a prop as markdown
show — Show details for a prop type

stagefreight props categories

Usage: stagefreight props categories categories

List prop categories with type counts

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight props list

Usage: stagefreight props list list

List all registered prop types, grouped by category.

Use --category to filter to a specific category.

Flags:

Name	Type	Default	Description
`--category`	string	—	filter by category

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight props render

Usage: stagefreight props render render

Resolve a prop type with the given parameters and print the resulting markdown.

Example: stagefreight props render --type docker-pulls --param image=prplanit/stagefreight

Flags:

Name	Type	Default	Description
`--param`	stringArray	—	param in key=value format (repeatable)
`--type`	string	—	prop type ID (required)

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight props show

Usage: stagefreight props show <type>

Show description, parameters, and example config for a prop type.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight push

Usage: stagefreight push push

Push the current branch to its remote using the convergence engine.

Handles diverged branches, missing upstream tracking, and up-to-date states. Push behavior is shared with 'commit --push' — same engine, standalone entry point.

Flags:

Name	Type	Default	Description
`--no-rebase`	bool	—	fail instead of rebasing on diverged branch
`--refspec`	string	—	push refspec (e.g. HEAD:refs/heads/main)
`--remote`	string	`origin`	git remote to push to

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight reconcile

Usage: stagefreight reconcile reconcile

Universal lifecycle reconciliation trigger.

Reads lifecycle.mode from .stagefreight.yml and dispatches to the configured backend (flux, compose, etc.). All intelligence lives in StageFreight — CI and CLI are just transports.

Examples: stagefreight reconcile stagefreight reconcile --dry-run

Flags:

Name	Type	Default	Description
`--dry-run`	bool	—	show plan without executing

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight release

Usage: stagefreight release release

Create releases, generate notes, update badges, and sync across forges.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

create — Create a release on the forge and sync to targets
notes — Generate release notes from conventional commits
prune — Prune old releases using retention policy
sync — Project releases from primary forge to mirrors

stagefreight release create

Usage: stagefreight release create create

Create a release on the detected forge (GitLab, GitHub, Gitea) with generated or provided release notes.

Optionally uploads assets (scan artifacts, SBOMs) and adds registry image links. Syncs to configured remote release targets unless --skip-sync is set.

Flags:

Name	Type	Default	Description
`--asset`	stringSlice	—	files to attach to release (repeatable)
`--catalog-links`	bool	`true`	add GitLab Catalog link to release
`--draft`	bool	—	create as draft release
`--name`	string	—	release name (default: tag)
`--notes`	string	—	path to release notes markdown file
`--prerelease`	bool	—	mark as prerelease
`--registry-links`	bool	`true`	add registry image links to release
`--security-summary`	string	—	path to security output directory (reads summary.md)
`--skip-sync`	bool	—	skip syncing to other forges
`--tag`	string	—	release tag (default: detected from git)

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight release notes

Usage: stagefreight release notes notes

Generate markdown release notes from the git log between two refs.

Parses conventional commits (feat, fix, chore, etc.) and groups them by category. Optionally embeds a security scan summary.

If --from is omitted, finds the previous tag automatically. If --to is omitted, defaults to HEAD.

Flags:

Name	Type	Default	Description
`--from`	string	—	start ref (default: previous tag)
`--security-summary`	string	—	path to security summary markdown to embed
`--to`	string	—	end ref (default: HEAD)
`-o, --output`	string	—	write notes to file (default: stdout)

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight release prune

Usage: stagefreight release prune prune

Delete old releases on the detected forge using the retention policy from the primary release target in .stagefreight.yml.

Alias templates from the release target are converted to patterns so only releases matching the configured tag scheme are candidates.

Use --dry-run to preview what would be deleted without deleting.

Flags:

Name	Type	Default	Description
`--dry-run`	bool	—	show what would be deleted without deleting

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight release sync

Usage: stagefreight release sync sync

Reads releases from the primary forge and projects missing ones to mirrors that declare sync.releases: true.

Use --dry-run to preview what would be created without making changes. Without --dry-run, missing releases are created on each mirror.

Flags:

Name	Type	Default	Description
`--dry-run`	bool	—	Preview only, do not create releases

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight security

Usage: stagefreight security security

Vulnerability scanning, SBOM generation, and security attestation.

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

scan — Run vulnerability scan and generate SBOM

stagefreight security scan

Usage: stagefreight security scan scan

Scan a container image for vulnerabilities using Trivy and Grype, then deduplicate results and optionally generate SBOM artifacts using Syft.

Individual scanners can be toggled via security.scanners in .stagefreight.yml. Results are written to the output directory as JSON, SARIF, and SBOM files. A markdown summary is generated at the configured detail level for embedding in release notes.

Flags:

Name	Type	Default	Description
`--fail-on-critical`	bool	—	exit non-zero if critical vulnerabilities found
`--image`	string	—	image reference or tarball to scan (required)
`--sbom`	bool	`true`	generate SBOM artifacts
`--security-detail`	string	—	override detail level for summary: none, counts, detailed, full
`--skip`	bool	—	skip scan (for pipeline control)
`--strict`	bool	—	fail if scan is partial, target lacks digest identity, or artifact verification fails
`-o, --output`	string	—	output directory for artifacts (default: from config)

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

See also: stagefreight security

stagefreight sign

Usage: stagefreight sign sign

Layers an additional signature onto the immutable artifacts a build already produced — a human publication act, separate from CI artifact production. The canonical use is hardware (YubiKey) authorization of an official release: CI builds and records the artifacts; a maintainer, on a machine with the token, runs this and physically touches the key.

It is strictly ADDITIVE and manifest-sourced:

never rebuilds, republishes, or mutates artifact contents
validates recorded digests first (refuses to sign drifted artifacts)
writes a distinct signature file, preserving lower-tier signatures
extends the results manifest with new trust evidence (never replaces)

The operation is generic — interactivity emerges from the selected profile's trust class (hardware prompts for touch/PIN; key/kms/oidc are non-interactive). It signs the release SHA256SUMS and each published image digest; when the profile opts into attestation (attestation: true) it also attests the build provenance onto those digests under the same tier — recorded as first-class, additive evidence.

Flags:

Name	Type	Default	Description
`--config`	string	`.stagefreight.yml`	config file
`--profile`	string	—	signing_profile id to sign under (required)
`--skip-images`	bool	—	sign only release blobs, not published image digests

Inherited flags:

Name	Type	Default	Description
`-v, --verbose`	bool	—	verbose output

stagefreight signing

Usage: stagefreight signing signing

Signing identity + trust-anchor maintenance

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

anchor — Regenerate the canonical signing trust anchor (managed SECURITY.md section)

stagefreight signing anchor

Usage: stagefreight signing anchor anchor

Regenerates the managed signing-anchor section — the stable, committed, canonical trust anchor that per-release Verification sections reference.

It updates ONLY the marked section (between and

), preserving all surrounding operator-authored

security prose. Deterministic and idempotent. This is an explicit docs-generation step: it never runs during publish and never mutates the repo silently.

Flags:

Name	Type	Default	Description
`--config`	string	`.stagefreight.yml`	config file
`--file`	string	`SECURITY.md`	file whose managed signing-anchor section to update

Inherited flags:

Name	Type	Default	Description
`-v, --verbose`	bool	—	verbose output

See also: stagefreight signing

stagefreight tag

Usage: stagefreight tag [version]

Release tag planner with policy enforcement, semantic highlights, and interactive approval.

Modes: stagefreight tag v0.5.0 Explicit version stagefreight tag --patch Bump from previous release stagefreight tag --minor stagefreight tag --major stagefreight tag Interactive selection (TTY only)

The tag is validated against versioning.tags before creation. Highlights are generated from the glossary pipeline or prompted when in interactive mode.

Flags:

Name	Type	Default	Description
`--dry-run`	bool	—	preview only, do not create tag
`--from`	string	—	override previous release boundary
`--json`	bool	—	output plan as JSON (implies --dry-run)
`--major`	bool	—	bump major from previous release
`--minor`	bool	—	bump minor from previous release
`--patch`	bool	—	bump patch from previous release
`--push`	bool	—	push tag to origin after creation
`--target`	string	—	ref to tag (default: HEAD)
`-m, --message`	string	—	override tag message
`-y, --yes`	bool	—	skip approval prompt

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight toolchain

Usage: stagefreight toolchain toolchain

Inspect and manage the StageFreight toolchain cache.

StageFreight resolves external tools (Go, Trivy, Grype, etc.) at runtime: downloaded, checksum-verified, cached, and executed by absolute path.

Subcommands: list Show installed toolchain versions prune Remove old toolchain versions from cache

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

Subcommands:

list — Show installed toolchain versions
prune — Remove old toolchain versions from cache

stagefreight toolchain list

Usage: stagefreight toolchain list list

Show installed toolchain versions

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight toolchain prune

Usage: stagefreight toolchain prune prune

Remove old toolchain versions from writable cache roots.

By default, shows what would be deleted (dry-run). Use --confirm to actually delete.

Safety:

Never prunes read-only cache roots
Never prunes the version currently pinned in .stagefreight.yml
Keeps at least --keep-latest versions per tool

Flags:

Name	Type	Default	Description
`--confirm`	bool	—	actually delete (default is dry-run)
`--keep-latest`	int	`1`	keep the N most recent versions per tool
`--older-than`	int	—	only prune versions installed more than N days ago
`--tool`	string	—	filter to specific tool

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight update

Usage: stagefreight update update

Pull the StageFreight image and atomically replace the running binary with the one inside it.

stagefreight update docker.io/prplanit/stagefreight:latest stagefreight update --dev docker.io/prplanit/stagefreight:latest-dev stagefreight update --image

The image binary is static (CGO_ENABLED=0) so it runs on any linux host; it is verified to run here before the swap, and the swap is atomic — the running process is unaffected.

Flags:

Name	Type	Default	Description
`--dev`	bool	—	update from the latest-dev image instead of the latest release
`--image`	string	—	image ref to update from (overrides default and --dev)

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)
`-v, --verbose`	bool	—	verbose output

stagefreight version

Usage: stagefreight version version

Print the version. --verbose adds build + runtime provenance (Go version, executable SHA-256, replay-guard capability) so a stale binary cannot masquerade as a guarded build.

Flags:

Name	Type	Default	Description
`--verbose`	bool	—	show full build + runtime provenance

Inherited flags:

Name	Type	Default	Description
`--config`	string	—	config file (default: .stagefreight.yml)

Uh oh!

FilesExpand file tree

CLI.md

Latest commit

History

CLI.md

File metadata and controls

StageFreight — CLI Reference

Command Index

stagefreight

stagefreight badge

stagefreight badge generate

stagefreight build

stagefreight build binary

stagefreight ci

stagefreight ci render

stagefreight ci run

stagefreight commit

stagefreight completion

stagefreight completion bash

Linux:

macOS:

stagefreight completion fish

stagefreight completion powershell

stagefreight completion zsh

Linux:

macOS:

stagefreight component

stagefreight component docs

input_section_name- Group Title

input_section_desc- Group description text

stagefreight config

stagefreight config render

stagefreight config resolve

stagefreight dependency

stagefreight dependency update

stagefreight docker

stagefreight docker build

stagefreight docker drift

stagefreight docker readme

stagefreight docs

stagefreight docs generate

stagefreight docs run

stagefreight du

stagefreight gitops

stagefreight gitops impact

stagefreight gitops inspect

stagefreight gitops reconcile

stagefreight glossary

stagefreight governance

stagefreight governance reconcile

stagefreight help

stagefreight lint

stagefreight manifest

stagefreight manifest diff

stagefreight manifest generate

stagefreight manifest inspect

stagefreight migrate

stagefreight narrator

stagefreight narrator compose

stagefreight narrator run

stagefreight props

stagefreight props categories

stagefreight props list

stagefreight props render

stagefreight props show

stagefreight push

stagefreight reconcile

stagefreight release

stagefreight release create

stagefreight release notes

stagefreight release prune

stagefreight release sync

stagefreight security

stagefreight security scan

stagefreight sign

stagefreight signing

stagefreight signing anchor

stagefreight tag

stagefreight toolchain