Usage

Use-case-driven examples for reisewarnungen, a command-line client for the open Auswärtiges Amt travel-warning API — official German travel and safety advisories by country. It reads the open data (no auth) and prints unwrapped JSON you can pipe straight into jq.

Install

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

This installs the reisewarnungen bin. Without a global install you can run the built CLI directly with node dist/src/cli/index.js.

All three subcommands are: list, countries, and get.

Use cases

1. List every travel warning (raw response)

Why: get the full upstream response envelope, keyed by content id, for archiving or downstream processing.

reisewarnungen list

The output is the raw, pretty-printed response map (numeric content-id keys plus the lastModified and contentList envelope members). Add --compact for a single-line payload suited to logs or further piping.

2. Get a flattened overview of all countries

Why: the raw list mixes envelope scalars in with country entries; countries flattens it into a clean array where each item carries its own id.

reisewarnungen countries

Each entry has id, countryName, countryCode, iso3CountryCode, and the warning flags (warning, partialWarning, situationWarning, situationPartWarning).

3. Show only countries with an active warning

Why: skip the noise and see just the countries where a warning of any kind is in force.

reisewarnungen countries --warned-only

--warned-only keeps an entry if any of warning, partialWarning, situationWarning, or situationPartWarning is true.

4. Read the full warning text for one country

Why: the full HTML advisory text (content) is only returned by the single-warning endpoint, so use get with the country’s content id.

reisewarnungen get 226768

The <contentId> is the numeric key from list / the id field from countries. The returned entry includes the HTML content, title, and effective/lastChanges metadata.

5. Find a country’s content id by name, then fetch it

Why: you usually know the country, not its numeric id. Resolve the id from countries, then pass it to get.

# Look up the id for, e.g., Ukraine
reisewarnungen countries --compact | jq -r '.[] | select(.countryName == "Ukraine") | .id'

# Then fetch that warning (substitute the id printed above)
reisewarnungen get 201946

6. List active warnings as a tidy country/id table

Why: a quick human-readable shortlist of where warnings apply, without the HTML.

reisewarnungen countries --warned-only --compact \
  | jq -r '.[] | [.countryCode, .id, .countryName] | @tsv'

--compact keeps the JSON on one line so jq consumes it cleanly; @tsv produces tab-separated columns.

7. Look up by ISO country code

Why: filter by a stable code (countryCode like UA, or iso3CountryCode like UKR) instead of a display name.

reisewarnungen countries --compact \
  | jq '.[] | select(.iso3CountryCode == "UKR")'

8. Save output to a file

Why: snapshot the data for reporting, diffing over time, or sharing.

# Full raw list to a file
reisewarnungen list -o warnings-2026-06-08.json

# Just the active warnings, compact
reisewarnungen countries --warned-only --compact -o active.json

-o/--output writes the command output to the given path instead of stdout. It refuses to overwrite an existing file (exit 1); pass --force to overwrite.

9. Extract just the warning text from a single advisory

Why: pull the human-readable advisory out of the JSON for a report or email.

reisewarnungen get 226768 --compact | jq -r '.content'

10. Point at a mock or staging endpoint with a custom timeout

Why: test against a local fixture server, or tighten the per-request timeout in a flaky network.

reisewarnungen --base-url http://localhost:8080 --timeout 5000 countries

Global options may be given before or after the command, so reisewarnungen countries --compact and reisewarnungen --compact countries are equivalent.

Global options

Real flags only, from reisewarnungen --help:

Note: -o/--output is trusted input — the path is written verbatim with no traversal guard (you own your shell). An existing file is not overwritten unless you pass --force.

Exit codes: 0 success, 4 when a country is not found, 1 for any other error; usage errors use commander’s own non-zero code, while --help / --version exit 0.