Skip to content
Fallow home
All docs pages

Docs home

JSON output

Find the JSON output of each fallow command for scripts and agents, with the envelope, the stability rules and the fields of each kind.

This page lists the JSON output of each fallow command for scripts, CI jobs and agents. Findings explains findings, rules and gates.

Get JSON output

Add --format json to a command. Add --quiet to remove the progress lines from stderr:

fallow dead-code --format json --quiet
Option or variableEffect
--prettyIndents the JSON. Without it, the output is one line.
--explainAdds the definitions of the metrics, the rules and the fields to _meta.
--leanLeaves out empty arrays and zero counts. Only fallow dead-code, fallow health and the bare fallow run accept it. Other commands exit with code 2 (Lean JSON).
--output-file <PATH>Writes the report to a file.
FALLOW_FORMAT=jsonSets JSON as the default format.
FALLOW_SUGGESTIONS=offLeaves out next_steps.

The samples on this page come from a small demo project. They are shortened: whole lines are removed.

Stability rules

  • Paths. Each path is relative to the project root and uses /.
  • kind. Each envelope has a kind field that names its shape. Branch on kind, not on the fields that you find.
  • schema_version. Each envelope has its own schema_version, which is independent of the fallow version and of the other envelopes. It changes when a field gets a new name or type, or when fallow removes a field. It also changes when a required enum field gets a new value, or a finding gets a new required field.
  • New fields. A new optional field does not change schema_version. Ignore the fields that you do not know.
  • Open sets. The names in gate_outcomes and the kind of a workspace_diagnostics entry are open sets. A new name can appear without a new schema_version.
  • Same input, same output. Two runs on one commit give the same bytes, except elapsed_ms, head_sha and _meta.telemetry.analysis_run_id.

The envelope

Most envelopes share these top-level fields:

FieldContent
kindThe name of the envelope, for example "dead-code".
schema_versionThe version of this envelope. A number or a string, as in the samples.
versionThe fallow version that wrote the output.
elapsed_msThe time of the analysis in milliseconds.
gate_outcomesOne entry for each gate that the run checked. See Gate outcomes.
request_outcomesOne entry for each request that narrows the run, for example --changed-since, with status: applied or not.
workspace_diagnosticsProblems with the project that are not findings. See Workspace diagnostics.
next_stepsRead-only commands to run next: id, command, reason. At most 3 entries, the most important first. Absent when it is empty.
_metatelemetry.analysis_run_id in each run. With --explain, also docs, field_definitions, metrics and rules.

Findings and actions

Each finding is an object in an array of its issue type, for example unused_exports. Most findings have these fields:

FieldContent
path, line, colThe place of the finding.
finding_idA stable id of the finding, for example dc1:unused-export:b650995c7b5b87c1.
effective_severityThe severity of the rule for this file: error or warn.
actionsThe fixes and suppressions for this finding.

Each entry of actions has a type, an auto_fixable boolean and a description. auto_fixable applies to this finding only: one type can be fixable on one finding and not on another. A suppression action has the comment to add in comment. fallow fix applies the actions with auto_fixable: true.

Gate outcomes

gate_outcomes holds one entry for each gate, keyed by the gate name, for example error-severity-findings:

FieldContent
statuspass, warn, fail or skipped.
enforcedtrue when a fail sets exit code 1.
observedThe measured value, when the gate has one.
threshold, threshold_labelThe limit of the gate.

A gate fails the run when status is fail and enforced is true. The bare fallow run in a JSON format reports a failed gate with enforced: false, unless you pass --fail-on-issues.

Workspace diagnostics

Each workspace_diagnostics entry has path, kind and message. message ends with a step to take. degrades_analysis: true marks a problem that can make the result incomplete, for example a file that fallow cannot parse. A diagnostic never changes the exit code. Warnings about the config explains the kinds about config entries.

{
  "path": ".",
  "kind": "rule-packs-not-configured",
  "message": "No rule packs are configured, so the policy detector did not run and its violation counts are zero because nothing was measured. Add `rulePacks` to the config, or set `policy-violation` to off to state that the check is not wanted."
}

Some kinds have more fields:

KindFields
production-excluded-file-importedIn production mode, a built-in production pattern excluded a source file that a production file imports. pattern is the built-in pattern, verbatim. file_count is the exact number of such files for that pattern. files lists the first five files in path order, relative to the project root. path is the first file. Fallow writes one entry for each pattern, with degrades_analysis: true.
inert-flagA flag has no effect on this run. flag names the flag, analysis names the analysis, and reason gives the cause. When a config key turns the analysis off, key names that key, for example duplicates.enabled for --dupes-baseline.
env-value-ignoredAn environment variable, such as a FALLOW_PRODUCTION* variable, has a value that fallow cannot read, so the run ignores it. name names the variable. The entry never holds the value.
config-file-shadowedTwo config files exist in one directory. used names the file that fallow loaded, and ignored names the other file.
config-load-fell-backThe editor could not load the config, so the language server analyzed with the default config. error gives the cause.
unknown-security-categorysecurity.categories names a category that fallow does not know. id names it.

The human output prints a flag without effect and an ignored variable as one Note: line, and --quiet hides that line. fallow audit --format json has a root workspace_diagnostics array when a notice exists. The MCP tools show these notices in warnings, and the language server writes them to its log. To see each setting of a run and its cause, run fallow config --resolved.

Errors

When a command fails with --format json, stdout holds an error document, and the exit code is 2. The document has no kind. This sample comes from fallow mutation with uncommitted changes:

{
  "error": true,
  "message": "the git worktree has 1 uncommitted path: package-lock.json",
  "exit_code": 2,
  "code": "FALLOW_MUTATION_DIRTY_WORKTREE",
  "help": "commit or stash the changes, or pass --allow-dirty"
}

error, message and exit_code are always present. code, a stable name of the error, and help, the step to take, are optional. Exit codes lists each code.

Kinds

kindCommand
dead-codefallow dead-code. See Dead code.
dead-code-groupedfallow dead-code --group-by <mode>
dupesfallow dupes. See Duplication.
healthfallow health. See Health.
combinedfallow without a command. See Combined run.
auditfallow audit. See Audit.
audit-brieffallow audit --brief and fallow review
architecturefallow architecture. See Architecture.
architecture-groupedfallow architecture --group-by <mode>
securityfallow security. See Security.
security-survivors, security-blind-spotsfallow security survivors, fallow security blind-spots
feature-flagsfallow flags. See Feature flags.
mutationfallow mutation. See Mutation testing.
mutation-plan, mutation-inspect, mutation-tasksfallow mutation --plan, fallow mutation inspect, fallow mutation tasks
similar-code, similar-code-inspect, similar-code-review, similar-code-status, similar-code-cache-clearfallow similar-code and its subcommands
list-boundariesfallow list --boundaries. See List.
list-workspacesfallow workspaces
explainfallow explain <issue-type>. See Explain.
inspect_targetfallow inspect
tracefallow dead-code --trace and the other trace options
trace-errorfallow trace-error
impact, impact-cross-repofallow impact, fallow impact --all
decision-surfacefallow decision-surface
suppression-inventoryfallow suppressions
doctorfallow doctor
type-aware-statusfallow type-aware status
coverage-setup, coverage-analyzefallow coverage setup, fallow coverage analyze
review-envelope--format review-github and --format review-gitlab
review-reconcilefallow ci reconcile-review
review-walkthrough-guide, review-walkthrough-validationfallow review --walkthrough-guide, fallow review --walkthrough-file

--format codeclimate writes a JSON array, as the Code Climate format requires, without an envelope.

Dead code

fallow dead-code --format json:

FieldContent
total_issuesThe number of findings in all arrays.
entry_pointsThe number of entry points from each source.
summaryThe number of findings of each issue type.
unused_files, unused_exports, unused_dependencies and the other arraysOne array for each issue type, with one object for each finding.
stale_suppressionsSuppressions that hide no finding. origin describes the comment or the tag. origin.kind_known: false marks a token that is not an issue type.
cascade_hiddenThe number of findings in unused files that the report leaves out. Absent when it is 0. See showCascade.
baseline, baseline_deltas, baseline_stalenessOnly in a run with --baseline.
{
  "kind": "dead-code",
  "schema_version": 11,
  "version": "3.45.0",
  "elapsed_ms": 186,
  "total_issues": 6,
  "unused_exports": [
    {
      "path": "src/lib/format.ts",
      "export_name": "formatPercent",
      "is_type_only": false,
      "line": 3,
      "col": 13,
      "span_start": 103,
      "is_re_export": false,
      "finding_id": "dc1:unused-export:b650995c7b5b87c1",
      "actions": [
        {
          "type": "remove-export",
          "auto_fixable": true,
          "description": "Remove the unused export from the public API"
        },
        {
          "type": "suppress-line",
          "auto_fixable": false,
          "description": "Suppress with an inline comment above the line",
          "comment": "// fallow-ignore-next-line unused-export"
        }
      ],
      "effective_severity": "error"
    },
  "gate_outcomes": {
    "error-severity-findings": {
      "status": "fail",
      "enforced": true,
      "observed": 6.0,
      "threshold_label": "error"
    }
  },
  "next_steps": [
    {
      "id": "trace-unused-export",
      "command": "fallow dead-code --trace src/lib/format.ts:formatPercent",
      "reason": "verify an export is truly unused before deleting"
    },
  ],
  "_meta": {
    "telemetry": {
      "analysis_run_id": "run_d7b2f098153aa420"
    }
  }
}

SARIF has the same number in runs[].properties.cascadeHidden. The human and Markdown formats print it in a note.

With --group-by, the kind is dead-code-grouped, and groups holds the findings of each group.

Duplication

fallow dupes --format json:

FieldContent
clone_groupsOne object for each clone group: instances, token_count, line_count, fingerprint, spread, actions.
clone_familiesOne object for each set of files that share clone groups: files, groups, suggestions, actions.
statsThe totals of all compared code, also when --top limits the list.
clone_groups_shown, clone_groups_omittedThe number of groups in clone_groups, and the number that --top left out.
clone_families_shown, clone_families_omittedThe same numbers for clone_families.
range_marker_problemsRange markers with a problem.

fingerprint holds the handle of the group, for example dup:f42424e8. Each instance has a fragment field with the source text. --no-fragments leaves it out.

{
  "kind": "dupes",
  "schema_version": 10,
  "version": "3.45.0",
  "elapsed_ms": 28,
  "clone_groups": [
    {
      "instances": [
        {
          "file": "src/reports/export.ts",
          "start_line": 3,
          "end_line": 19,
          "start_col": 31,
          "end_col": 1,
        },
        {
          "file": "src/utils/summary.ts",
          "start_line": 7,
          "end_line": 23,
          "start_col": 27,
          "end_col": 1,
        }
      ],
      "token_count": 210,
      "line_count": 17,
      "fingerprint": "dup:f42424e8",
      "spread": 2,
  "stats": {
    "total_files": 8,
    "files_with_clones": 2,
    "total_lines": 170,
    "duplicated_lines": 34,
    "total_tokens": 1334,
    "duplicated_tokens": 210,
    "clone_groups": 1,
    "clone_families": 1,
    "clone_instances": 2,
    "duplication_percentage": 20.0
  },
  "clone_groups_shown": 1,
  "clone_groups_omitted": 0,
  "clone_families_shown": 1,
  "clone_families_omitted": 0,

Health

fallow health --format json:

FieldContent
findingsOne object for each function above a complexity limit: cyclomatic, cognitive, crap, severity (the band), effective_severity (the rule), actions.
summaryThe numbers of files and functions, the limits, and the number of findings in each band.
health_scoreThe health score, its grade and its penalties.
vital_signsThe metrics of the whole project.
file_scoresThe maintainability index and other scores of each file.
hotspot_summary, hotspotsFiles that change often and are complex.
targetsRanked refactoring targets.
sectionsThe sections that the run produced, in a fixed order.
{
  "kind": "health",
  "schema_version": 13,
  "version": "3.45.0",
  "elapsed_ms": 56,
  "findings": [
    {
      "path": "src/services/customers.ts",
      "name": "classifyCustomer",
      "line": 9,
      "col": 32,
      "cyclomatic": 23,
      "cognitive": 32,
      "line_count": 39,
      "param_count": 1,
      "exceeded": "all",
      "severity": "critical",
  "summary": {
    "files_analyzed": 16,
    "functions_analyzed": 24,
    "functions_above_threshold": 1,
  "health_score": {
    "formula_version": 3,
    "score": 60.8,
    "grade": "C",
  "gate_outcomes": {
    "health-findings": {
      "status": "fail",
      "enforced": true,
      "observed": 1.0,
      "threshold_label": "error"
    }
  },

Combined run

fallow --format json runs dead code, duplication and health in one envelope:

FieldContent
checkThe dead code section, with the fields of Dead code and its own schema_version.
dupesThe duplication section, with the fields of Duplication.
healthThe health section, with the fields of Health.
skippedEach analysis that the run left out, with the reason.
gate_outcomesThe gates of all sections.
{
  "kind": "combined",
  "schema_version": 15,
  "version": "3.45.0",
  "elapsed_ms": 199,
  "gate_outcomes": {
    "error-severity-findings": {
      "status": "fail",
      "enforced": false,
      "observed": 6.0,
      "threshold_label": "error"
    },
    "health-findings": {
      "status": "fail",
      "enforced": false,
      "observed": 1.0,
      "threshold_label": "error"
    }
  },
  "check": {
    "schema_version": 11,
    "version": "3.45.0",
    "elapsed_ms": 169,
    "total_issues": 6,
  "dupes": {
    "clone_groups": [
  "health": {
    "findings": [

Audit

fallow audit --format json reports the changed-code check:

FieldContent
commandAlways "audit".
verdictpass, warn or fail.
changed_files_countThe number of changed files in scope.
base_ref, base_description, head_shaThe base of the comparison and the commit of the head.
summaryThe number of findings in each analysis.
attributionThe findings that the change introduced and the findings that it inherited, for each analysis.
dead_code, duplication, complexityThe findings of each analysis in the changed files.
diff_riskFindings about the change itself, for example weakened tests. Absent when there are none.
{
  "kind": "audit",
  "schema_version": 14,
  "version": "3.45.0",
  "command": "audit",
  "verdict": "warn",
  "changed_files_count": 2,
  "base_ref": "main",
  "base_description": "local main",
  "head_sha": "87067c4",
  "elapsed_ms": 224,
  "attribution": {
    "gate": "new-only",
    "worsened": "warn",
    "dead_code_introduced": 0,
    "duplication_introduced": 1,
    "duplication_inherited": 0,
    "styling_introduced": 0,
    "styling_inherited": 0,
    "duplication_demoted": 0,
    "diff_risk_introduced": 0
  },
  "gate_outcomes": {
    "audit-verdict": {
      "status": "warn",
      "enforced": true
    }
  },
  "duplication": {
    "clone_groups": [
  "complexity": {
    "findings": [],

Architecture

fallow architecture --format json has the fields of Dead code. The architecture arrays hold the findings: circular_dependencies, re_export_cycles, package_cycles, boundary_violations, boundary_coverage_violations, boundary_call_violations and policy_violations. With --shared-state, shared_state holds the shared-state report.

A boundary_violations entry has from_path, to_path, from_zone, to_zone and import_specifier. An import through a barrel file has via_path. An import of a file that is not public has reason: "internal_file" and public_files. See Boundary configuration.

{
  "kind": "architecture",
  "schema_version": 2,
  "version": "3.45.0",
  "elapsed_ms": 59,
  "total_issues": 2,
  "boundary_violations": [
    {
      "from_path": "src/reports/invoice.ts",
      "to_path": "src/services/orders.ts",
      "from_zone": "reports",
      "to_zone": "services",
      "import_specifier": "src/services/orders.ts",
      "line": 1,
      "col": 14,
      "finding_id": "dc1:boundary-violation:48f7879d0efd6aba",
      "actions": [
        {
          "type": "refactor-boundary",
          "auto_fixable": false,
          "description": "Move the import through an allowed zone or restructure the dependency",
          "note": "This import crosses an architecture boundary that is not permitted by the configured rules"
        },
        {
          "type": "suppress-line",
          "auto_fixable": false,
          "description": "Suppress with an inline comment above the line",
          "comment": "// fallow-ignore-next-line boundary-violation"
        }
      ],
      "effective_severity": "error"
    },

Security

fallow security --format json:

FieldContent
configThe configured and the effective severity of each security rule, and the selected categories.
security_findingsOne object for each candidate: kind, category, cwe, path, line, evidence, severity, trace, reachability, actions.
unresolved_edge_files, unresolved_callee_sitesThe number of places that fallow could not follow.

With --summary, the output has summary and no arrays of findings. Each finding is a candidate that a person must check. See Security.

{
  "kind": "security",
  "schema_version": "8",
  "version": "3.45.0",
  "elapsed_ms": 73,
  "security_findings": [
    {
      "finding_id": "016ae89b0e96180f",
      "stable_finding_id": "sec1:f6797a2384c0b3fc",
      "kind": "tainted-sink",
      "category": "dangerous-html",
      "cwe": 79,
      "path": "src/services/render.ts",
      "line": 2,
      "col": 2,
      "evidence": "Non-literal value assigned to el.innerHTML. Candidate for verification: confirm the value is not attacker-controlled, or is sanitized, before it reaches the DOM.",
      "severity": "medium",
  "unresolved_edge_files": 0,
  "unresolved_callee_sites": 9,

Feature flags

fallow flags --format json:

FieldContent
feature_flagsOne object for each flag: path, flag_name, kind, confidence, line, col, actions.
total_flagsThe number of entries in feature_flags.
retirementThe flags that you can remove, with the reasons.
{
  "kind": "feature-flags",
  "schema_version": 8,
  "version": "3.45.0",
  "elapsed_ms": 57,
  "feature_flags": [
    {
      "path": "src/services/checkout.ts",
      "flag_name": "FEATURE_NEW_CHECKOUT",
      "kind": "environment_variable",
      "confidence": "high",
      "line": 1,
      "col": 45,

Mutation testing

fallow mutation --format json:

FieldContent
completionstatus and reasons. A partial run stopped before it tested each mutant, for example at --max-mutants.
scopeThe code that the run changed.
runner, cacheThe test runner and the result cache.
summaryThe number of mutants with each status, the score and the coverage.
mutantsOne object for each mutant: the place, the operator, the change, the status and the tests.
functionsThe results of each function.
filesThe changed files with their SHA-256 digest.
gate_outcomesThe mutation-min-score gate, when --min-score or mutation.minScore sets it.
{
  "kind": "mutation",
  "schema_version": "2",
  "version": "3.45.0",
  "elapsed_ms": 371,
  "completion": {
    "status": "partial",
    "reasons": [
      "mutant-limit"
    ]
  },
  "summary": {
    "counts": {
      "total": 222,
      "killed": 4,
      "timeout": 0,
      "survived": 0,
      "no_coverage": 213,
      "runtime_error": 0,
      "flaky": 0,
      "pruned": 4,
      "pending": 1,
      "equivalent": 0,
      "compile_error": 0,
      "not_killed_by_target": 0
    },
    "score": 1.0,
    "coverage": 0.022935779816513763,
    "sampled_out": 0
  },
  "mutants": [
    {
      "mutant_id": "1c5c16bb5be77fce",
      "file": "src/lib/parse.ts",
      "line": 1,
      "column": 53,
      "operator": "return-value",
      "function": "parseAmount",
      "status": "killed",
      "killed_by": "src/math.test.ts::parseAmount > parses 1.00",

List

fallow list --boundaries --format json has the kind list-boundaries. boundaries holds the zones after preset expansion, with file_count for each zone, and the rules:

{
  "kind": "list-boundaries",
  "boundaries": {
    "configured": true,
    "zone_count": 3,
    "zones": [
      {
        "name": "services",
        "patterns": [
          "src/services/**"
        ],
        "file_count": 3
      },
    "rule_count": 3,
    "rules": [
      {
        "from": "services",
        "allow": [
          "shared"
        ]
      },

The other fallow list options give an object without kind and schema_version. It has the fields of the requested lists: plugins, files, file_count, entry_points, entry_point_count, workspaces, workspace_count and workspace_diagnostics. Each entry point has path and source.

Explain

fallow explain <issue-type> --format json describes one issue type. The output has no schema_version:

{
  "kind": "explain",
  "id": "fallow/unused-export",
  "name": "Unused Exports",
  "summary": "Export is never imported",
  "rationale": "Named exports that are never imported by any other module in the project. Includes both direct exports and re-exports through barrel files. The export may still be used locally within the same file.",
  "example": "export const formatPrice = ... exists in src/money.ts, but no module imports formatPrice.",
  "how_to_fix": "Remove the export or make it file-local. If it is public API, import it from an entry point or add an intentional suppression with context. To treat exported Effect schemas as type contracts, set effect.schemaExportsAsTypes: fallow then reports them as unused types.",
  "docs": "https://fallow.tools/docs/explanations/dead-code/#unused-exports",

JSON Schema

The JSON Schema of each envelope is docs/output-schema.json in the fallow repository. Validate against the schema of the fallow version that you run: an older copy can reject a new workspace_diagnostics kind.

  • Findings: findings, rules and gates.
  • Exit codes: the exit code of each command.
  • Agents: use the JSON output in an agent.