CLI

The analysis commands (lint, check, impact, generate, trace) start by printing the tool version and the version of every schema they read or write (to stderr, so JSON on stdout stays clean):

 flowpact  v0.5.0  config schema v1 · contract schema v1 · report schema v1 · node v24.4.0
root . · config .github/flowpact/flowpact.config.yml

flowpact --version prints the same line.

flowpact lintCopy Anchor Link

Analyzes all workflows and local actions and reports findings.

flowpact lint [paths…] [options]

The summary card at the end:

Output formatsCopy Anchor Link

flowpact lint -o flowpact-report.json           # JSON file + pretty output in the terminal
flowpact lint -o flowpact.sarif                 # SARIF file for code scanning
flowpact lint -o flowpact-report.md             # Markdown file, e.g. for $GITHUB_STEP_SUMMARY
flowpact lint -o flowpact-report.txt            # plain-text copy of the pretty report
flowpact lint --format json > report.json  # JSON only

JSON reportCopy Anchor Link

The JSON report follows /schemas/report/v1.json:

{
  "$schema": "https://rumankazi.github.io/flowpact/schemas/report/v1.json",
  "meta": { "tool": "flowpact", "version": "0.5.0", "schemas": { "config": 1, "contract": 1, "report": 1 }, "node": "v24.4.0", "platform": "linux-x64", "root": "/home/runner/work/app/app", "durationMs": 31 },
  "summary": { "errors": 1, "warnings": 0, "infos": 0, "suppressed": 0, "byCode": { "FP401": 1 } },
  "findings": [
    {
      "code": "FP401",
      "name": "empty-binding-for-matrix-combo",
      "severity": "error",
      "message": "Input \"config\" for .github/workflows/run-suite.yml is empty in 1 of 3 matrix combinations — matrix.config is not defined there",
      "loc": { "file": ".github/workflows/tests.yml", "line": 23, "column": 19, "endLine": 23, "endColumn": 32 },
      "related": [{ "loc": { "file": ".github/workflows/tests.yml", "line": 18, "column": 13 }, "message": "this include entry has no `config`" }],
      "combos": ["{ name: windows }"],
      "symbol": ".github/workflows/run-suite.yml#inputs.config",
      "why": "…", "fix": "…",
      "docsUrl": "https://rumankazi.github.io/flowpact/docs/rules/fp401",
      "fingerprint": "3f2a9c0d81b7e645"
    }
  ],
  "suppressed": [],
  "rules": [{ "code": "FP101", "name": "missing-required-input", "severity": "error" }, "…"]
}

• symbol identifies what the finding is about; use it as the target of an override.
• suppressed lists findings accepted by overrides, each with an override object (index, reason, expires, owner); they are not part of the counts.
• In flowpact check, contracts holds the contract comparison: drift, the number of breaking changes, counts per status and one entry per contract file with its status and semantic changes.
• fingerprint is stable across unrelated edits (line shifts, changed counts), so it can be used to track findings over time.
• rules lists every rule with its code, name and effective severity (off included).
• With --impact (or flowpact impact), impact holds the verdict: the baseline, the required and declared impact, ok, and every graded change. See Impact mode.

flowpact checkCopy Anchor Link

Everything flowpact lint does, plus a comparison with the contracts committed in .github/flowpact/.

flowpact check [paths…] [options] [--patch <file>]

It takes the same options as flowpact lint. Contract findings — missing (FP801), outdated (FP802), breaking (FP803), orphaned (FP804) and invalid (FP805) contracts — are errors by default, so the command exits 1 until the contracts are regenerated.

With paths, the comparison covers the contracts of those workflows and actions, and the contracts that list them as a consumer: a caller that stops passing an input or reading an output changes its callee's contract, so that drift is reported too.

flowpact generateCopy Anchor Link

Writes the contract for every workflow and local action, and deletes contracts whose workflow or action no longer exists.

flowpact generate [--dry-run] [--patch <file>] [--out <dir>]

It also accepts --root, --config and the logging and color options. The table lists every contract file as new, changed, removed or unchanged, with the semantic changes underneath; breaking changes are marked. Running it twice in a row changes nothing.

flowpact graphCopy Anchor Link

Shows which workflows call which reusable workflows and local actions.

flowpact graph [--format tree|mermaid|dot|json]

Edges are labelled with the calling job (jobs.build, or the step for local actions), ×N when the call fans out over N matrix combinations, and (inherit) for secrets: inherit. Reusable workflows in other repositories appear as remote nodes, local targets that do not exist as missing nodes, and job-level calls to files outside .github/workflows (FP606) as invalid location nodes.

flowpact traceCopy Anchor Link

Shows where a value flows to, or with --up where it comes from.

flowpact trace <symbol> [--up] [--depth n] [--format pretty|json]

Each symbol is expanded once per trace; where the same value is reached again through another path (for example shared callees), the tree says ↑ shown above instead of repeating it. --format json always prints { "query", "direction", "traces": [...] }, however many symbols matched.

Symbols can be written in several ways:

flowpact impactCopy Anchor Link

For publishers of reusable workflows and actions: checks that the release impact a pull request declares covers the changes to published units since its base. See Impact mode.

flowpact impact --base origin/main --title "fix: tidy the test job"

It runs only the impact rules (FP810–FP814), so its exit code reflects only the verdict. flowpact lint --impact and flowpact check --impact add the verdict to everything else they report. Options: --base, --expect, --title, --labels and the output options of lint.

flowpact explainCopy Anchor Link

flowpact explain FP401
flowpact explain empty-binding-for-matrix-combo

flowpact rulesCopy Anchor Link

Lists every built-in rule with its effective severity (after your config). --format json for tooling.

flowpact lspCopy Anchor Link

Starts the language server, which speaks the Language Server Protocol over stdin/stdout (--node-ipc and --socket <port> are also accepted). Editors start it themselves; you do not run it by hand. It serves diagnostics as you type, hover traces, go to definition across workflow calls, and references. See Editors for its settings and how to set it up in Neovim and other editors; the VS Code extension bundles it.

Debug mode and loggingCopy Anchor Link

flowpact logs every stage of the analysis: config resolution, file discovery, parsing per file, graph construction, matrix expansion per job (combinations, keys, exactness), each rule with its finding count and timing, and the final summary.

Logs go to stderr, so --format json output stays parseable.

Exit codesCopy Anchor Link

flowpact graph, flowpact trace, flowpact explain and flowpact rules exit 0 on success. flowpact generate exits 0 too, or 1 when a file with YAML syntax errors could not be regenerated (its committed contract is kept).

Environment variablesCopy Anchor Link