Getting Started¶

This guide covers installing Agronomist and running your first scan against an infrastructure repository.

If you want to contribute to or develop Agronomist itself, see Development instead.

Requirements¶

• Python 3.10 or newer
• Git installed and available on your PATH (used by the default git resolver)
• A GitHub token is recommended when using --resolver github to avoid API rate limits (GITHUB_TOKEN environment variable or --github-token flag)
• A GitLab token is required for private GitLab repositories when using --resolver auto (GITLAB_TOKEN environment variable or --gitlab-token flag)

Install¶

Using pipx (recommended)¶

pipx installs Agronomist in an isolated environment and makes the agronomist command globally available.

From a release wheel¶

Download the latest .whl from the Releases page and install it:

pipx install agronomist-X.Y.Z-py3-none-any.whl

Build from source with Docker¶

The Docker build produces a wheel without requiring a specific local Python version:

git clone https://github.com/Ops-Talks/agronomist.git
cd agronomist
make build-docker
pipx install dist/agronomist-*-py3-none-any.whl

Build from source with Poetry¶

git clone https://github.com/Ops-Talks/agronomist.git
cd agronomist
poetry build
pipx install dist/agronomist-*-py3-none-any.whl

Verify the installation¶

agronomist --help

Run a report¶

The report command scans your infrastructure files and produces a JSON report of available module updates. No files are modified.

# Scan the current directory
agronomist report

# Scan a specific directory
agronomist report --root ./infrastructure

# Write the JSON report to a custom path
agronomist report --root ./infrastructure --json updates.json

# Also generate a human-readable Markdown summary
agronomist report --root ./infrastructure --json updates.json --markdown updates.md

Apply updates¶

The update command applies the identified version changes directly to your source files and also produces a JSON report.

# Apply updates in the current directory
agronomist update

# Apply updates in a specific directory
agronomist update --root ./infrastructure --json updates.json

Set up a configuration file¶

Place a .agronomist.yaml file in your repository root to configure category rules and blacklists. Agronomist loads it automatically.

See Configuration for the full file format and options.

Authenticate with GitHub or GitLab¶

Export your tokens as environment variables before running Agronomist:

export GITHUB_TOKEN="ghp_..."
export GITLAB_TOKEN="glpat-..."

Alternatively, pass them as flags:

agronomist report --github-token ghp_... --root ./infrastructure

Next steps¶

• CLI Reference — complete list of options and flags.
• Configuration — configure category tagging and blacklists.
• Resolvers — choose between Git, GitHub API, and GitLab API resolvers.
• Reports — understand the report output format.
• GitHub Action — run Agronomist automatically in GitHub Actions.
• GitLab CI — run Agronomist and create merge requests in GitLab CI.