Reports¶

Agronomist can produce JSON and Markdown reports. By default, no report files are generated unless the corresponding flags are provided.

Reporting Behavior¶

To generate report files, you must explicitly provide the output paths:

• Use --json <path> for a structured JSON report.
• Use --markdown <path> for a human-readable summary.

If these flags are omitted, Agronomist will only print a summary of discovered updates to the terminal.

JSON report¶

The JSON report is optional and only generated if --json is provided.

Example structure:

{
  "generated_at": "2026-02-17T12:34:56Z",
  "root": ".",
  "updates": [
    {
      "repo": "owner/repo",
      "repo_host": "github.com",
      "repo_url": "https://github.com/owner/repo",
      "module": "modules/vpc@infra/prod/vpc/terragrunt.hcl",
      "base_module": "modules/vpc",
      "file": "infra/prod/vpc/terragrunt.hcl",
      "current_ref": "v1.2.0",
      "latest_ref": "v1.4.1",
      "strategy": "latest",
      "category": "aws",
      "files": ["infra/prod/vpc/terragrunt.hcl"],
      "replacements": [
        {"from": "source = ...", "to": "source = ..."}
      ]
    }
  ]
}

Markdown report¶

Use --markdown to generate a human readable summary.

Example:

poetry run agronomist report --root . --markdown report.md --json report.json

Example output:

# Agronomist Report

**Generated at:** 2026-02-17T12:34:56Z
**Root:** `.`

## Summary

- **Total updates:** 2
- **Affected repositories:** 2
- **Affected modules:** 2

## Updates by Repository

### terraform-aws/vpc (github.com)

#### Module: `vpc`

**v1.2.0 → v1.4.1**
- Category: `aws`
- Affected files: 1
  - `infra/prod/vpc/terragrunt.hcl`

### terraform-aws/rds (github.com)

#### Module: `rds`

**v3.0.0 → v3.1.0**
- Category: `database`
- Affected files: 1
  - `infra/prod/db/terragrunt.hcl`