@maschinenlesbar.org/dwd-cli

dwd-cli

Query Germany's official weather warnings, station forecasts, and crowd reports from your terminal. dwd is a small command-line tool over the open DWD Warnwetter app API operated by the Deutscher Wetterdienst — no account, no API key, just data.

• Works out of the box — no account, no API key, no configuration. Install and run.
• Clean JSON output — pretty-printed by default, --compact for one-line/scripting.
• Five commands — station-overview, warnings nowcast, warnings gemeinde, warnings coast, and crowd.
• Transparent gzip — the warning feeds are served compressed; the tool decompresses them silently.
• Read-only, open data — these endpoints are public and unauthenticated; dwd only reads.

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

Install

npm i -g @maschinenlesbar.org/dwd-cli

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

Check it works:

dwd --help

Quickstart

No setup needed. Your first command — current nationwide short-term warnings:

dwd warnings nowcast

The result is a JSON envelope with a time (publish timestamp) and a warnings array. Count the active entries with jq:

dwd --compact warnings nowcast | jq '.warnings | length'

Fetch forecast and observation data for a DWD station (München-Stadt = 10865):

dwd station-overview --id 10865

Commands

station-overview --id <stationId> [--id …]   forecasts/observations for one or more stations
warnings nowcast  [--lang de|en]             short-term (nowcast) warnings
warnings gemeinde [--lang de|en]             municipality-level warnings
warnings coast    [--lang de|en]             coastal warnings (by zone)
crowd                                        crowd-sourced reports overview

station-overview flags

Flag	Meaning
--id <stationId>	Required, repeatable. 5-digit DWD station id (e.g. 10865 for München-Stadt)

warnings flags

Applies to all three warnings subcommands (nowcast, gemeinde, coast):

Flag	Meaning
--lang <lang>	Feed language: de (default) or en

crowd flags

No flags beyond the global options.

The Glossary explains domain terms — station ids, feed envelopes, coastal zones, and the German/English equivalents.

Two hosts

The DWD app data lives on two hosts; dwd talks to both automatically:

• Live web service — https://app-prod-ws.warnwetter.de/v30 — used by station-overview.
• Static S3 bucket — https://s3.eu-central-1.amazonaws.com/app-prod-static.warnwetter.de/v16 — used by warnings and crowd.

Override them with --base-url (live) and --static-base-url (static) if you need to point at a proxy or staging host.

Common tasks

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

# Current nowcast warnings in English
dwd warnings nowcast --lang en

# Municipality-level warnings — find ones whose text mentions München
# (warnings have no `regionName`; search the headline/description text instead)
dwd --compact warnings gemeinde \
  | jq '.warnings[] | select(((.headLine // "") + " " + (.descriptionText // "")) | test("München"))'

# Coastal-warning zones that currently carry a warning
dwd --compact warnings coast | jq '.warnings | keys'

# Forecast for several stations at once
dwd station-overview --id 10865 --id 01766

# Address a single station from a multi-station response
dwd station-overview --id 10865 --id 10147 | jq '."10865"'

# Crowd-sourced reports — count how many were submitted
dwd --compact crowd | jq '.meldungen | length'

# Snapshot the nowcast feed to a timestamped file (cron-friendly)
dwd --compact warnings nowcast > "nowcast-$(date +%Y%m%dT%H%M).json"

Output & scripting

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

# Flatten nowcast warnings into an event/level/description TSV
# (the feed has no `headline`/`regionName`; in --lang en only event/description translate)
dwd warnings nowcast --lang en \
  | jq -r '.warnings[] | [.event, .level, .descriptionText] | @tsv'

# When was the Gemeinde feed last published? Read the time field.
dwd --compact warnings gemeinde | jq '.time'

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

dwd --compact warnings nowcast | jq -c '.warnings[]'

--compact (and every global option) works before or after the command — both dwd --compact warnings nowcast and dwd warnings nowcast --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	Resource not found (404)
5	API returned a non-404, non-success status
6	Network/transport failure (DNS, connection, timeout, oversized response, unsupported protocol, too many redirects)
7	Response body could not be parsed as JSON
1	Any other error

Troubleshooting

• command not found: dwd — 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/dwd-cli ….
• Exit 4 / "not found" — a requested feed or resource returned 404. Note that an unknown station id is not a 404: station-overview returns {} with exit 0 for an id the catalogue doesn't know (and silently drops unknown ids from a multi-id response), so empty {} there means a bad id, not a server error. Double-check the id against the DWD Warnwetter app; DWD station ids are typically 5-digit numeric codes.
• Exit 5 / API error — the upstream service returned an unexpected status. The service is public but may be temporarily unavailable; retry later.
• Exit 6 / network error — connectivity, DNS, or a timeout. Try again, or raise the limit with --timeout 60000. If a feed is large and getting cut off, try --max-response-bytes 0 (unlimited).
• Exit 7 / parse error — the response wasn't valid JSON (e.g. a captive-portal HTML page). Check your network path; captive portals often intercept HTTPS on public Wi-Fi.
• Empty warnings array — the feed is live but no warnings are currently active. That's the normal situation when the weather is calm.

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>	Live web-service base URL (default https://app-prod-ws.warnwetter.de)
--static-base-url <url>	Static S3 bucket base URL
--timeout <ms>	Per-request timeout (default 30000)
--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)

An option that takes a value consumes the next token as that value, so give a value-taking option its value explicitly: --user-agent "my-tool" --compact, not --user-agent --compact (which would treat the literal --compact as the User-Agent and silently drop the flag).

Learn more

• SKILLS.md — Claude Code Agent Skills that drive this CLI for real-world weather questions.
• Usage.md — full use-case-driven cookbook.
• GLOSSARY.md — domain terms, station ids, feed envelopes, and exit codes.
• 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.

Deutscher Wetterdienst — GeoNutzV / CC BY 4.0. Attribution required ("Quelle: Deutscher Wetterdienst"); commercial use allowed. Special rule: if you modify an official warning, the DWD source label must be removed.

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.