airq — CLI Air Quality Checker

Check air quality for any city from the terminal. Merges model data (Open-Meteo) with real citizen science sensors (Sensor.Community). No API keys needed.

Installation

First check if airq is already installed:

airq --version

If not installed, detect the user's platform:

macOS (Homebrew)

brew tap fortunto2/tap && brew install airq

Linux (prebuilt binary)

curl -LO https://github.com/fortunto2/airq/releases/latest/download/airq-linux-x86_64.tar.gz
tar xzf airq-linux-x86_64.tar.gz
sudo mv airq /usr/local/bin/

Any platform (Rust/cargo)

cargo install airq

Configuration (recommended)

If the user mostly checks the same city, set up a config — then just type airq without flags:

airq init --city <city-name>

This creates ~/.config/airq/config.toml. Can also add a favorites list to check multiple cities at once:

default_city = "berlin"
cities = ["berlin", "tokyo", "istanbul", "new york"]

airq       # checks berlin (default)
airq --all # checks all 4 cities, ranked by pollution

Commands

Current air quality

airq                              # uses default city from config
airq --city tokyo                 # specific city
airq --lat 55.75 --lon 37.62     # by coordinates

Output shows PM2.5, PM10, CO, NO2, O3, SO2, UV index with color-coded AQI.

History (sparkline trend)

airq history --city berlin --days 7

Shows daily AQI with sparkline bars for the past N days.

Rank cities by pollution

airq top --country germany            # top 5 cities
airq top --country turkey --count 10  # top 10

Any country in the world — 10,000+ cities built-in. Use --list to see all countries.

Compare data sources

airq compare --city berlin                     # model vs area sensors
airq compare --city berlin --sensor-id 72203   # model vs specific sensor

Side-by-side table showing Open-Meteo model vs Sensor.Community readings.

Find nearby sensors

airq nearby --city paris --radius 10

Lists Sensor.Community sensor IDs within the given radius (km).

Single data source

airq --city berlin --provider open-meteo           # model only
airq --city berlin --provider sensor-community --sensor-id 72203  # sensor only

Pollution front detection

airq front --city gazipasa --radius 150 --days 3

Detects pollution fronts moving between cities. Uses Z-score spike detection and cross-correlation.

HTML/PDF report with map

airq report --city hamburg --pdf

Generates HTML report with Leaflet.js map, front arrows, spikes and fronts tables. --pdf exports via Chrome headless.

JSON output

All commands support --json for scripting and piping:

airq --city tokyo --json
airq history --city berlin --days 7 --json
airq top --country usa --json

AQI scale

How it works

By default airq fetches both sources concurrently and averages PM2.5/PM10:

• Open-Meteo — atmospheric model (~11km grid, global coverage)
• Sensor.Community — median of real sensors within 5km (filters outliers)

If no sensors are nearby, falls back to model only.