pegel-online-cli

Website: English · Deutsch — command reference, guides and API docs

Check live water levels and gauge readings for any German federal waterway station from your terminal. pegel is a command-line tool over the open PEGELONLINE REST API v2 (pegelonline.wsv.de) operated by the WSV — find stations, query current readings, pull measurement histories, and get the full picture on any gauge — as clean JSON you can pipe straight into jq.

• Works out of the box — no account, no API key, no configuration. Install and query.
• Clean JSON output — pretty-printed by default, --compact for one-line/scripting.
• Covers the full hierarchy — bodies of water, stations, timeseries, current readings, measurement windows, and gauge marks.
• Live data — readings update continuously from hundreds of federal gauges across Germany's rivers and canals.

Want to use this as a TypeScript library or understand how it's built? See DEVELOPING.md.

Install

npm i -g @maschinenlesbar.org/pegel-online-cli
Copy

This installs the pegel command. Requires Node.js 20+.

Check it works:

pegel --help
Copy

Quickstart

No setup needed — the API is public and requires no key. Your first command:

pegel waters
Copy

This lists every body of water (Gewässer) in the network. Grab just the shortnames with jq:

pegel waters | jq -r '.[].shortname'
Copy

Pick one — say RHEIN — and get the current water level at Bonn:

pegel current BONN
Copy

Pull just the value and timestamp:

pegel current BONN | jq '{value, timestamp}'
Copy

Commands

stations list  [filters…]                 list / filter stations
stations get   <station> [includes…]      full details for one station
timeseries     <station> [timeseries]     metadata for a timeseries
current        <station> [timeseries]     the current measurement
measurements   <station> [timeseries]     a window of measurements
waters                                    list all bodies of water (Gewässer)
Copy

A <station> may be a uuid, number, shortname or longname — e.g. BONN, 6302010, or a full UUID. A [timeseries] defaults to W (water level); other codes include Q (flow/discharge), WT (water temperature), and LT (air temperature) depending on the station.

stations list filters

Flag	Meaning
--ids <id>	station id (uuid/number/shortname/longname); repeatable
--waters <shortname>	filter by water shortname (see waters)
--fuzzy-id <id>	fuzzy match against short/long name
--include-timeseries	embed each station's timeseries list
--include-current	embed the current measurement
--include-characteristic	embed characteristic (gauge-mark) values

stations get options

Flag	Meaning
--include-timeseries	embed the station's timeseries list
--include-current	embed the current measurement
--include-characteristic	embed characteristic (gauge-mark) values

measurements options

Flag	Meaning
--start <iso>	window start — ISO-8601 instant or a period like P7D
--end <iso>	window end — ISO-8601 instant

The Glossary explains every domain term and timeseries code.

Common tasks

A few recipes to get going — see Usage.md for the full, use-case-driven set.

# All stations on the Rhine, with their current water level
pegel stations list --waters RHEIN --include-current

# One station — metadata + timeseries list + current reading
pegel stations get BONN --include-timeseries --include-current

# Current water level at Bonn (default timeseries W)
pegel current BONN

# Current flow at Bonn (timeseries Q)
pegel current BONN Q

# Last 7 days of measurements
pegel measurements BONN W --start P7D

# Explicit date window
pegel measurements BONN W --start 2026-06-01T00:00:00Z --end 2026-06-07T00:00:00Z

# Gauge marks (MNW/MHW/NSW/HSW) for Cologne
pegel stations get KÖLN --include-timeseries --include-characteristic

# Timeseries metadata — discover which series a station exposes
pegel timeseries BONN

# Multiple specific stations in one call
pegel stations list --ids BONN --ids KÖLN --ids EMMERICH --include-current
Copy

Output & scripting

Every command prints pretty JSON to stdout. Errors and diagnostics go to stderr, so piping stdout into jq stays clean.

# Water shortnames, one per line
pegel waters | jq -r '.[].shortname'

# Reshape a current measurement
pegel current BONN | jq '{value, timestamp}'

# CSV-ish series for a spreadsheet
pegel measurements BONN W --start P3D | jq -r '.[] | [.timestamp, .value] | @csv'

# Station names and coordinates on the Rhine (tab-separated)
pegel stations list --waters RHEIN | jq -r '.[] | [.shortname, .longitude, .latitude] | @tsv'

# Gauge marks for the W series at Cologne
pegel stations get KÖLN --include-timeseries --include-characteristic \
  | jq '.timeseries[] | select(.shortname == "W") | .characteristicValues'
Copy

Use --compact for single-line JSON in pipelines and logs:

pegel --compact current BONN | jq '.value'
Copy

--compact (and every global option) works before or after the command — both pegel --compact waters and pegel waters --compact do the same thing.

Exit codes make the CLI easy to use in scripts:

Code	Meaning
0	success (also --help / --version)
2	bad usage / invalid argument (nothing was sent)
4	station or resource not found (404)
1	any other error (network, timeout, unexpected response)

Troubleshooting

• command not found: pegel — the global npm bin directory isn't on your PATH. Run npm bin -g to find it and add it, or run via npx @maschinenlesbar.org/pegel-online-cli ….
• Exit 2 / "invalid argument" — check the command syntax: a <station> argument is required, and --start / --end must be valid ISO-8601 instants or periods (e.g. P7D). Run pegel <command> --help for the exact signature.
• Exit 4 / "not found" — the station shortname or id doesn't exist. Run pegel stations list --fuzzy-id <name> or pegel waters to find the right shortname.
• Exit 1 / network error — connectivity, DNS, or a timeout. Try again, or raise the limit with --timeout 60000.
• Empty timeseries array — the station doesn't publish the requested series. Run pegel timeseries <station> to see which codes it actually exposes.

Global options

These apply to every command and may be given before or after it:

Option	Description
-V, --version	Print the version number
-h, --help	Show help for the program or a command
--compact	Print JSON on a single line instead of pretty-printed
--base-url <url>	API base URL (default https://www.pegelonline.wsv.de)
--timeout <ms>	Time limit per request in milliseconds, reading the whole response included (default 30000; at most 2147483647)
--user-agent <ua>	User-Agent header value
--max-retries <n>	Retries for transient 429/503 responses (default 2)
--max-response-bytes <n>	Cap response body size in bytes (0 = unlimited; default 100 MiB)

Learn more

• SKILLS.md — Claude Code Agent Skills that drive this CLI for live water-level questions.
• Usage.md — full use-case-driven cookbook.
• GLOSSARY.md — every domain term, timeseries code, and state classification explained.
• DEVELOPING.md — TypeScript library usage, architecture, testing, CI.

Data license

This CLI is a client — it accesses data it does not own or redistribute. The upstream data is © its provider and licensed separately from this tool's code. See DATA_LICENSE.md.

Wasserstraßen- und Schifffahrtsverwaltung des Bundes (WSV) — Datenlizenz Deutschland Zero 2.0 (≈ CC0): no attribution required, commercial use and modification allowed. Raw, unchecked data — no warranty.

License

Dual-licensed — use it under either:

• AGPL-3.0-or-later (default, free). Note the AGPL's §13 network clause: if you run a modified version as a network service, you must offer that modified source to the service's users.
• Commercial license (paid), for closed-source / proprietary or SaaS use without the AGPL's obligations.

See LICENSING.md for details, and CONTRIBUTING.md for the contribution policy (this project does not accept external code contributions). Commercial enquiries: sebs@2xs.org.