The free, single-binary PVGIS CLI — JRC solar-radiation and PV-yield estimates with offline cache, multi-site batch, and agent-native JSON.
Estimates monthly and hourly PV production, downloads Typical Meteorological Year (TMY) weather, fetches DEM-derived horizon profiles, and finds optimal tilt for any point covered by PVGIS-SARAH3, PVGIS-NSRDB, or PVGIS-ERA5. Adds offline SQLite caching, multi-site fan-out (sites rank), and a local 2D tilt/azimuth heatmap (production sweep) that no PVGIS endpoint returns directly.
Printed by @robertobissanti (Roberto Bissanti).
Quick Start
# Confirm the JRC API is reachable from this machine.
pvgis-pp-cli doctor
# Monthly irradiance for a Milano-area site, fixed tilt 30 south.
pvgis-pp-cli radiation monthly --lat 45.0 --lon 9.0 --tilt 30 --azimuth 0 --json
# Annual yield for a 5 kWp crystSi system at the same spot.
pvgis-pp-cli production monthly --lat 45.0 --lon 9.0 --pnom 5 --system-loss 14 --tilt 30 --azimuth 0 --json
# Sweep tilt 0-60 to find the production peak for a south-facing system.
pvgis-pp-cli production optimal-tilt --lat 45.0 --lon 9.0 --azimuth 0 --json
# Pull the full 8760-hour TMY; pipe through jq or save for downstream tools.
pvgis-pp-cli weather tmy --lat 45.0 --lon 9.0 --json --select outputs.tmy_hourly
Unique Features
These capabilities aren't available in any other tool for this API.
Local state that compounds
-
sites rank — Rank a CSV of candidate sites by annual yield/kWp under the same system spec.
Use when an agent has a list of candidate roofs/sites and needs to recommend the highest-yield one without N round trips.
pvgis-pp-cli sites rank --input sites.csv --tilt 30 --pnom 5 --system-loss 14 --agent
-
production sweep — Compute a 2D grid of yields across tilt and azimuth, cache it, and serve future point queries from local interpolation.
Use before recommending a fixed-mount orientation when the user can choose tilt and azimuth independently.
pvgis-pp-cli production sweep --lat 45 --lon 9 --pnom 5 --system-loss 14 --tilt-min 0 --tilt-max 60 --azimuth-min -90 --azimuth-max 90 --agent
-
sites diff — Compare annual production at a baseline site against a target site under identical system specs.
Use to quantify how much a relocation or alternate roof loses or gains.
pvgis-pp-cli sites diff --baseline 45.0,9.0 --target 41.9,12.5 --pnom 5 --system-loss 14 --agent
Cross-database insight
-
production compare — Run the same site under PVGIS-SARAH3, PVGIS-NSRDB, and PVGIS-ERA5; report yield deltas.
Use when assessing confidence intervals: how much do different databases disagree at this location?
pvgis-pp-cli production compare --lat 45 --lon 9 --pnom 1 --system-loss 14 --tilt 30 --agent
-
weather similar — Rank cached TMYs by similarity to a target site's 12-month temperature and GHI signature.
Use to find analog climate sites for transfer-learning yield assumptions.
pvgis-pp-cli weather similar --to 45.0,9.0 --within sites.csv --top 5 --agent
Usage
Run pvgis-pp-cli --help for the full command reference and flag list.
Commands
horizon
DEM-derived terrain horizon profile — the angular height of distant terrain in 49 azimuth steps.
pvgis-pp-cli horizon - Terrain horizon profile (printhorizon) for a site. Returns the horizon height in degrees at 49 azimuth points from -180 to 180 (step 7.5 degrees), derived from the SRTM DEM. Also returns the sun path at winter and summer solstices for solar-availability analysis.
production
PV system production estimates — monthly summaries and full hourly time series for fixed mountings.
pvgis-pp-cli production hourly - Hourly PV production time series (seriescalc) for a fixed-mount system. Returns one row per hour over the requested year range with power P (W), in-plane irradiance G(i), sun height, air temperature, wind speed. Typical response is 8760 rows per year.pvgis-pp-cli production monthly - Monthly and annual PV production (PVcalc) for a fixed-mount system. Returns monthly energy E_m, daily energy E_d, and in-plane irradiation H(i)_m, plus yearly totals E_y. Accounts for module technology, system losses, and optional terrain horizon.
radiation
Solar radiation queries — monthly irradiance on horizontal, tilted, or optimally-tilted surfaces, with optional terrain horizon.
pvgis-pp-cli radiation - Monthly solar radiation (MRcalc) for a site. Returns 12 monthly values on the horizontal plane, the requested tilt, and/or the locally optimal tilt, plus monthly average air temperature. Uses PVGIS-SARAH3 for Europe/Africa/Asia, PVGIS-NSRDB for the Americas, PVGIS-ERA5 elsewhere.
weather
Typical Meteorological Year (TMY) weather data — 8760-hour synthetic year representative of long-term climate.
pvgis-pp-cli weather - Typical Meteorological Year for a site. Returns 8760 hourly rows with air temperature T2m, relative humidity, global horizontal irradiance G(h), beam normal Gb(n), diffuse Gd(h), longwave IR(h), wind speed WS10m, wind direction WD10m, surface pressure SP. Constructed from the long-term record so it represents climate, not a specific year.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
pvgis-pp-cli horizon --lat 42 --lon 42
# JSON for scripting and agents
pvgis-pp-cli horizon --lat 42 --lon 42 --json
# Filter to specific fields
pvgis-pp-cli horizon --lat 42 --lon 42 --json --select id,name,status
# Dry run — show the request without sending
pvgis-pp-cli horizon --lat 42 --lon 42 --dry-run
# Agent mode — JSON + compact + no prompts in one flag
pvgis-pp-cli horizon --lat 42 --lon 42 --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 5 API error, 7 rate limited, 10 config error.
Health Check
pvgis-pp-cli doctor
Verifies configuration and connectivity to the API.
Configuration
Config file: ~/.config/pvgis-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Troubleshooting
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- All commands hang or return network errors — PVGIS occasionally has maintenance windows. Run
pvgis-pp-cli doctor and retry. Use --base-url to pin to https://re.jrc.ec.europa.eu/api/v5_2 if v5_3 is degraded.
- Response shows
H(i)_m: 0.0 for every month — MRcalc requires --tilted=1 (or --selectrad=1) plus --tilt/--azimuth to compute the tilted plane. Without it only the horizontal plane is returned.
weather tmy response is huge — TMY returns 8760 hourly rows. Use --select outputs.tmy_hourly[0] to inspect one row, or pipe into the local SQLite store via pvgis weather sync --lat --lon.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press