@maschinenlesbar.org/dwd-cli
    Preparing search index...

    @maschinenlesbar.org/dwd-cli

    dwd-cli

    CI Release npm

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

    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.

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

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

    Check it works:

    dwd --help

    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

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

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

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

    No flags beyond the global options.

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

    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.

    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"

    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
    • 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.

    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> Time limit per request, reading the whole response included (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).

    • 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.

    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.

    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.

    Settings
    Member Visibility

    On This Page
    dwd-cli