Skip to content

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!
    • badge — Badge generation commands
      • generate — Generate SVG badges from config or flags
    • build — Build artifacts (binaries, images)
      • binary — Build Go binaries
    • ci — CI subsystem commands
      • checkout — Materialize the repository workspace via go-git (no git binary required)
      • render — Render forge-native CI pipeline from .stagefreight.yml
      • run — Run a CI subsystem
    • commit — Create a conventional commit from staged or specified files
    • component — GitLab CI component management
      • docs — Generate input documentation from component spec files
    • config — Inspect and manage StageFreight configuration
      • render — Show the effective config after preset resolution
      • resolve — Show the config resolution chain with provenance
    • dependency — Dependency management commands
      • update — Update outdated dependencies
    • docker — Docker lifecycle — build, drift, reconcile
      • build — Build and push container images
      • drift — Show drift status for all Docker compose stacks
      • readme — Sync README to container registries
    • docs — Documentation generation commands
      • generate — Generate reference documentation from code
      • run — Run the narrate producers locally (badges + patches)
    • du — Storage-attribution diagnostic — what is eating disk today
    • gitops — GitOps intelligence — inspect, impact, reconcile
      • impact — Compute which kustomizations are affected by recent changes
      • inspect — Discover and display the Flux dependency graph
      • reconcile — Reconcile affected Flux kustomizations
    • glossary — Show the repo's change-language conventions
    • governance — Governance reconciliation and fleet management
      • reconcile — Reconcile governance policy to satellite repos
    • lint — Run code quality checks
    • manifest — Generate and inspect build manifests
      • diff — Compare two manifests (not yet implemented)
      • generate — Generate manifest from build config and Dockerfile
      • inspect — Pretty-print manifest or specific sections
    • migrate — Migrate config to the latest schema version
    • narrator — Compose and inject content into markdown files
      • compose — Compose modules into a file section from the shell
      • run — Run narrator items from config
    • props — Typed presentation items (badges, etc.)
      • 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
    • pull — Plan and bring the remote's commits into the current branch
    • push — Plan and push the current branch to its remote (or an explicit destination)
    • reconcile — Reconcile infrastructure to declared state
    • release — Release management commands
      • 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
    • security — Security scanning commands
      • scan — Run vulnerability scan and generate SBOM
    • sign — Attach an additional signature to already-built release artifacts
    • signing — Signing identity + trust-anchor maintenance
      • anchor — Regenerate the canonical signing trust anchor (managed SECURITY.md section)
    • tag — Plan, validate, and create a release tag
    • test — Run the project's test suites (go test / cargo test / custom)
    • toolchain — Manage StageFreight toolchains
      • list — Show installed toolchain versions
      • prune — Remove old toolchain versions from cache
    • update — Update this stagefreight binary in place from the published image
    • version — Print the version

Global flags

Available on every command:

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

stagefreight

Usage: 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
  • 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
  • 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.)
  • pull — Plan and bring the remote's commits into the current branch
  • push — Plan and push the current branch to its remote (or an explicit destination)
  • 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
  • test — Run the project's test suites (go test / cargo test / custom)
  • toolchain — Manage StageFreight toolchains
  • update — Update this stagefreight binary in place from the published image
  • version — Print the version

stagefreight badge

↩ stagefreight

Usage: stagefreight badge

Generate SVG badges from config or ad-hoc flags.

Subcommands:

  • generate — Generate SVG badges from config or flags

stagefreight badge generate

↩ stagefreight badge

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 Options 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 — passed · warning · critical status-driven color
--value string — — ad-hoc badge value (right side)

Plus the global flags.

stagefreight build

↩ stagefreight

Usage: stagefreight build

Build binaries, container images, and other artifacts.

Subcommands:

  • binary — Build Go binaries

stagefreight build binary

↩ stagefreight build

Usage: stagefreight build 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)

Plus the global flags.

stagefreight ci

↩ stagefreight

Usage: stagefreight 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.

Subcommands:

  • checkout — Materialize the repository workspace via go-git (no git binary required)
  • render — Render forge-native CI pipeline from .stagefreight.yml
  • run — Run a CI subsystem

stagefreight ci checkout

↩ stagefreight ci

Usage: stagefreight ci checkout

Clone the CI repository into the workspace using the embedded go-git transport.

On Actions-family container jobs (GitHub/Gitea/Forgejo) the checkout runs INSIDE the StageFreight image, which carries no git binary — so actions/checkout would fall back to a .git-less REST tarball, breaking every git-aware subsystem. This command clones the repo itself (auth resolved from GITHUB_TOKEN etc. via the standard resolver) so a real .git is present. go-git is ownership-agnostic, so no safe.directory is required.

GitLab does not use this — its runner clones at the runner level and the container inherits the .git.

Exit codes: 0=success, 1=checkout error, 3=context error

Plus the global flags.

stagefreight ci render

↩ stagefreight ci

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

Plus the global flags.

stagefreight ci run

↩ stagefreight ci

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)

Plus the global flags.

stagefreight commit

↩ stagefreight

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
--push bool — push after commit
--refspec string — push refspec (e.g. HEAD:refs/heads/main)
--remote string origin git remote for push
--sign-off bool — add Signed-off-by trailer
--skip-ci bool — append [skip ci] to subject line
-m, --message string — commit summary message
-s, --scope string — commit scope
-t, --type string — conventional commit type (e.g. feat, fix, docs, chore); custom types resolve against glossary.types in config

Plus the global flags.

stagefreight component

↩ stagefreight

Usage: stagefreight component

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

Subcommands:

  • docs — Generate input documentation from component spec files

stagefreight component docs

↩ stagefreight component

Usage: stagefreight component 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

Plus the global flags.

stagefreight config

↩ stagefreight

Usage: stagefreight config

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

Subcommands:

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

stagefreight config render

↩ stagefreight config

Usage: stagefreight config 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

Plus the global flags.

stagefreight config resolve

↩ stagefreight config

Usage: stagefreight config 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

Plus the global flags.

stagefreight dependency

↩ stagefreight

Usage: stagefreight dependency

Aliases: deps

Resolve, update, and audit project dependencies.

Subcommands:

  • update — Update outdated dependencies

stagefreight dependency update

↩ stagefreight dependency

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 Options Description
--bundle bool — — include deps-updated.tgz
--dry-run bool — — resolve and report without applying changes
--ecosystem stringSlice — — filter to specific ecosystem(s)
--max-update string — major · minor · patch update-type ceiling (default from config, else minor)
--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 all · security update policy

Plus the global flags.

stagefreight docker

↩ stagefreight

Usage: stagefreight docker

Docker lifecycle intelligence and container image management.

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

↩ stagefreight docker

Usage: stagefreight docker build

Build container images using docker buildx.

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

Flags:

Name Type Default Options Description
--build string — — build a specific entry by ID (default: all)
--build-mode string — crucible build execution strategy (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

Plus the global flags.

stagefreight docker drift

↩ stagefreight docker

Usage: stagefreight docker 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

Plus the global flags.

stagefreight docker readme

↩ stagefreight docker

Usage: stagefreight docker 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

Plus the global flags.

stagefreight docs

↩ stagefreight

Usage: stagefreight docs

Generate reference documentation from code and config structs.

Subcommands:

  • generate — Generate reference documentation from code
  • run — Run the narrate producers locally (badges + patches)

stagefreight docs generate

↩ stagefreight docs

Usage: stagefreight docs 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
-h, --help bool — help for generate

Plus the global flags.

stagefreight docs run

↩ stagefreight docs

Usage: stagefreight docs run

Runs the presence-enabled narrate producers from config — render badges and apply marked-region patches to files — without committing. Same producer logic as 'stagefreight ci run narrate' (which also lands build trees + auto-commits).

Plus the global flags.

stagefreight du

↩ stagefreight

Usage: stagefreight 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)

Plus the global flags.

stagefreight gitops

↩ stagefreight

Usage: stagefreight gitops

GitOps intelligence — inspect, impact, reconcile

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

↩ stagefreight gitops

Usage: stagefreight gitops 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

Plus the global flags.

stagefreight gitops inspect

↩ stagefreight gitops

Usage: stagefreight gitops 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.

Plus the global flags.

stagefreight gitops reconcile

↩ stagefreight gitops

Usage: stagefreight gitops 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)

Plus the global flags.

stagefreight glossary

↩ stagefreight

Usage: stagefreight 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

Plus the global flags.

stagefreight governance

↩ stagefreight

Usage: stagefreight governance

Commands for reconciling governance policy across governed repositories.

Subcommands:

  • reconcile — Reconcile governance policy to satellite repos

stagefreight governance reconcile

↩ stagefreight governance

Usage: stagefreight governance 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

Plus the global flags.

stagefreight lint

↩ stagefreight

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 Options 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 — changed · full scan level (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)

Plus the global flags.

stagefreight manifest

↩ stagefreight

Usage: stagefreight 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)

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

↩ stagefreight manifest

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

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

Plus the global flags.

stagefreight manifest generate

↩ stagefreight manifest

Usage: stagefreight manifest 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)

Plus the global flags.

stagefreight manifest inspect

↩ stagefreight manifest

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 Options Description
--build-id string — — resolve manifest for a specific build ID
--format string human json · table · human output format
--section string — — dot-path into manifest (e.g., inventories.pip)

Plus the global flags.

stagefreight migrate

↩ stagefreight

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

Plus the global flags.

stagefreight narrator

↩ stagefreight

Usage: stagefreight 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.

Subcommands:

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

stagefreight narrator compose

↩ stagefreight narrator

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:<label>,output:<path>,link:<url>
shield:<path>,link:<url>,label:<text>
text:<markdown content>
component:<spec-file-path>
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

Plus the global flags.

stagefreight narrator run

↩ stagefreight narrator

Usage: stagefreight narrator 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

Plus the global flags.

stagefreight props

↩ stagefreight

Usage: stagefreight 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.

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

↩ stagefreight props

Usage: stagefreight props categories

List prop categories with type counts

Plus the global flags.

stagefreight props list

↩ stagefreight props

Usage: stagefreight props 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

Plus the global flags.

stagefreight props render

↩ stagefreight props

Usage: stagefreight props 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 — a prop type id — run stagefreight props list to see them (required)

Plus the global flags.

stagefreight props show

↩ stagefreight props

Usage: stagefreight props show <type>

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

Plus the global flags.

stagefreight pull

↩ stagefreight

Usage: stagefreight pull

Pull the current branch's remote into your local branch.

StageFreight shows the plan and executes it: fast-forward when you're behind, or rebase your local commits onto the remote (with your confirmation) when the branch has diverged. It refuses on a mid-flight git operation rather than acting on a half-finished state.

Flags:

Name Type Default Description
--remote string origin git remote to pull from
--yes bool — approve a rebase-onto-remote (diverged branch) without prompting

Plus the global flags.

stagefreight push

↩ stagefreight

Usage: stagefreight push [remote] [branch]

Push the current branch to its remote, or to an explicit destination.

With no arguments, StageFreight plans against the branch's own upstream — uploading, creating tracking, fast-forwarding, or (for a protected destination) replaying with your confirmation. It never silently rewrites a feature branch.

With "push " it plans an explicit cross-target push (e.g. a feature branch onto origin/main): ahead/behind are computed against that destination — fast-forward when it is behind you (Confirm on protected trunk), refuse when it already contains you, and hand the rebase back to git when the two have diverged.

Flags:

Name Type Default Description
--no-rebase bool — legacy: fail instead of rebasing on a diverged branch (refspec path only)
--refspec string — push refspec (e.g. HEAD:refs/heads/main) — uses the legacy convergence path
--remote string origin git remote to push to
--yes bool — approve a transformational plan (e.g. replay onto a protected branch) without prompting

Plus the global flags.

stagefreight reconcile

↩ stagefreight

Usage: stagefreight 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

Plus the global flags.

stagefreight release

↩ stagefreight

Usage: stagefreight release

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

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

↩ stagefreight release

Usage: stagefreight release 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)

Plus the global flags.

stagefreight release notes

↩ stagefreight release

Usage: stagefreight release 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)

Plus the global flags.

stagefreight release prune

↩ stagefreight release

Usage: stagefreight release 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

Plus the global flags.

stagefreight release sync

↩ stagefreight release

Usage: stagefreight release 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

Plus the global flags.

stagefreight security

↩ stagefreight

Usage: stagefreight security

Vulnerability scanning, SBOM generation, and security attestation.

Subcommands:

  • scan — Run vulnerability scan and generate SBOM

stagefreight security scan

↩ stagefreight security

Usage: stagefreight security 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 Options 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 — none · counts · detailed · full override detail level for summary
--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)

Plus the global flags.

stagefreight sign

↩ stagefreight

Usage: stagefreight 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
--profile string — a signing_profiles[].id from config to sign under (required)
--skip-images bool — sign only release blobs, not published image digests

Plus the global flags.

stagefreight signing

↩ stagefreight

Usage: stagefreight signing

Signing identity + trust-anchor maintenance

Subcommands:

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

stagefreight signing anchor

↩ stagefreight signing

Usage: stagefreight signing 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

Plus the global flags.

stagefreight tag

↩ stagefreight

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

Plus the global flags.

stagefreight test

↩ stagefreight

Usage: stagefreight test [suite-id...]

Run StageFreight test suites locally — the SAME suites, resolved the same way, the CI audition phase runs. No arguments runs all suites; pass suite ids to run a subset, or --gate to filter by lifecycle tier.

Suites are auto-synthesized from your builds when none are declared in .stagefreight.yml (a go builder → "go test ./..."; a rust builder → "cargo test").

Flags:

Name Type Default Options Description
--gate string — perform · advisory run only suites with this gate

Plus the global flags.

stagefreight toolchain

↩ stagefreight

Usage: stagefreight 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

Subcommands:

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

stagefreight toolchain list

↩ stagefreight toolchain

Usage: stagefreight toolchain list

Show installed toolchain versions

Plus the global flags.

stagefreight toolchain prune

↩ stagefreight toolchain

Usage: stagefreight toolchain 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

Plus the global flags.

stagefreight update

↩ stagefreight

Usage: stagefreight 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 <ref>

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)

Plus the global flags.

stagefreight version

↩ stagefreight

Usage: stagefreight 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

Plus the global flags.