Usage

Real, use-case-driven examples for the nina CLI — a command-line client for the open NINA civil-protection warning API (warnung.bund.de), the BBK’s federal alerting system aggregating MoWaS, KATWARN, BIWAPP, DWD severe weather, flood (LHP) and police warnings.

Install

npm i -g @maschinenlesbar.org/nina-warnungen-cli

This installs a single bin named nina. (Without a global install you can run the same commands via node apps/cli/dist/src/cli/index.js ….)

All read commands print pretty JSON to stdout, so they pipe cleanly into jq. The API needs no key and is read-only.

Use cases

1. See what warning sources exist

Before querying, confirm the exact source identifiers the API accepts.

nina sources

Prints the valid source list (mowas, katwarn, biwapp, dwd, lhp, police) — the values you pass to map-data.

2. Current severe-weather warnings from the DWD

The single most common check: is the national weather service warning about anything right now?

nina map-data dwd

Returns the array of current warnings for that source. Pipe to jq to pull just the headlines and severities:

nina map-data dwd | jq '.[] | {id, severity: .severity, headline: .i18nTitle.de}'

3. Surface only the most serious alerts across a source

During an event you often only care about Severe/Extreme warnings, filtering out Minor/Moderate noise.

nina map-data mowas | jq '[.[] | select(.severity == "Severe" or .severity == "Extreme")]'

map-data works the same for any source — swap mowas for katwarn, biwapp, lhp or police.

4. Pull the full CAP detail for one warning

Once you have an id from a map-data entry, fetch the complete CAP payload (area descriptions, instructions, effective/expires times, web links).

nina warning get mow.DE-SL-SLS-W038-20260113-000

Prints the full warning object. The identifier comes straight from a map-data entry’s id field.

5. Save a warning’s geometry as GeoJSON for mapping

To draw the affected area on a map (Leaflet, QGIS, etc.), download the raw geometry instead of the metadata.

nina warning geojson mow.DE-SL-SLS-W038-20260113-000 -o warn.geojson

geojson writes the raw bytes — use -o/--output <file> to save them, or omit it to stream the GeoJSON to stdout (e.g. for piping into another tool). Piped or redirected, stdout gets the bytes exactly as the server sent them; on a terminal, control characters are escaped as \uXXXX so the body cannot send escape sequences to it. A body that isn’t GeoJSON (a gateway’s HTML page, an error object) is an error (exit 1), and nothing is written. -o - also means stdout.

6. Region dashboard: everything affecting a district

For a regional operations view, list all warnings currently affecting one district by its Amtlicher Regionalschlüssel (ARS). The API only accepts district-level keys: 12 digits with the last seven set to 0. The CLI checks that before sending: an 8-digit Gemeindeschlüssel (AGS), a municipality-level ARS, a key that lost its leading zero (11 digits) or one with a stray character is refused (exit 1, no request), with the district key to use where it is clear — take the first five digits and append 0000000. A state-level key (digits 3–5 000, e.g. 050000000000 for NRW, or 000000000000) is refused before any request: the API answers it with [] even while a district in that state has warnings, which would read as an all-clear. Hamburg (020000000000) and Berlin (110000000000) are their own district and are accepted. A well-formed key that names no district (a Regierungsbezirk key such as 051000000000, an unassigned number) gets HTTP 404 from the API: the CLI logs ERROR [nina.api] HTTP 404 for GET /api31/dashboard/<key>.json: no such district key "<key>": … and exits 4.

nina dashboard 055150000000

055150000000 is the regional key for Münster (a kreisfreie Stadt). The result aggregates warnings from every source for that area; combine with jq to count or group them. set -o pipefail keeps a failed run (exit 1 or 4, nothing on stdout) from reading as a count of 0; an HTTP 200 whose body isn’t a list of warnings (null, {}, an error object) is such a failure (exit 1), never an empty list. A Cancel entry is an all-clear for an earlier warning, so leave it out of a count:

set -o pipefail
nina dashboard 055150000000 | jq '[.[] | select(.payload.data.msgType != "Cancel")] | length'

7. Inspect the history of an archived MoWaS warning

For after-action review, look at how a past MoWaS warning was revised over time, then fetch a specific archived revision.

nina archive mapping mow.DE-SL-SLS-W038-20260113-000
nina archive get     mow.DE-SL-SLS-W038-20250814-000_20250814172229

archive mapping returns the revision history — a history array whose entries each carry an identifier for one archived revision (the …_<timestamp> form). Pass one of those revision identifiers to archive get to fetch that specific archived warning; the .json suffix the mapping prints is optional (it is dropped, not doubled). The mapping’s msgType is upper case (ALERT, UPDATE), unlike the Alert/Update in a warning itself.

8. Watching a district for changes

To keep an eye on one district, re-run its dashboard a few minutes apart and compare the results: new ids are new warnings, missing ones have been cleared, and a changed payload.hash for the same id marks an updated entry.

nina --compact dashboard 055150000000 > dash.json

reference data-version is not a shortcut for this. Its only entry is labels, and it does not change when warnings change (checked on 2026-09-15: its file was last modified on 12 September, while the warning feeds had changed that day):

nina --compact reference data-version

The other reference datasets are also static:

nina reference notfalltipps   # emergency-preparedness tips (German)
nina reference event-codes    # the CAP event-code catalogue

9. Query a non-default host or tune timeouts/retries

For testing against a mirror, or for flaky-network resilience, override the base URL and transport behaviour.

nina --base-url https://warnung.bund.de --timeout 15000 --max-retries 3 map-data dwd

Global options may be placed before or after the command, so nina --compact map-data dwd and nina map-data dwd --compact are equivalent.

Global options

These flags apply to every command (real flags only):

Option	Description
`-V, --version`	Output the version number
`--base-url <url>`	API base URL (default `https://warnung.bund.de`; a path prefix for a mirror is fine; a query `?` or fragment `#`, whitespace or control characters are rejected). A remote plain `http:` URL works but logs one `WARN` record of `nina.http`, `… sent unencrypted …`, on stderr before the request (stdout and the exit code are unchanged; `localhost`, `127.0.0.0/8` and `::1` are exempt)
`--timeout <ms>`	Per-request timeout in ms (`0` disables; waits indefinitely)
`--user-agent <ua>`	`User-Agent` header value (a blank value, control characters or characters above U+00FF are rejected)
`--max-retries <n>`	Retries for transient `429`/`503` responses and reset connections (default `2`, max `10` — higher is rejected). A refused connection, a DNS failure and a timeout are not retried. Each retry waits a linear backoff (200 ms, 400 ms, …), or the server’s `Retry-After` (seconds or an HTTP date) when that is longer — never less, so `Retry-After: 0` still waits the backoff; a `Retry-After` above 30 s is not retried, and the error names the requested wait. Each retry logs one WARN record of `nina.http` before it waits (`HTTP 503 from host: retry 1 of 3 in 2 s`).
`--max-response-bytes <n>`	Cap response body size in bytes (`0` = unlimited; default 100 MiB)
`--compact`	Print JSON on a single line instead of pretty-printed
`--log-format <format>`	How errors, warnings and notes are written to stderr: `text` (default; log4j style, `2026-10-09T14:03:12.481Z WARN [nina.http] …`) or `jsonl` (one JSON object per line: `ts`, `level`, `topic`, `msg`). stdout is not affected
`-o, --output <file>`	Write the command’s output to a file instead of stdout (JSON commands and downloads alike); `-o -` means stdout. An existing file at that path is overwritten silently — there is no prompt or `--force`, so point `-o` at a fresh path or one you intend to replace
`-h, --help`	Display help for a command

Notes: numeric options accept only plain non-negative decimal integers. An identifier that starts with - must be passed after a -- separator, e.g. nina warning get -- -odd.identifier. Whitespace, invisible characters and quotes around an identifier and a .json/.geojson suffix are dropped before the request. Exit codes: 0 success, 4 on a 404 from the API or for a warning id that no live warning has (the API redirects it to its archive instead of answering 404, for an ended and a mistyped id alike), 1 for any other error, including usage errors and a body without the documented shape (see the “Exit codes” table in GLOSSARY.md).