Usage

Practical, use-case-driven examples for the Tagesschau CLI — a read-only command-line client for ARD-aktuell’s open Tagesschau API (tagesschau.de). Every command prints JSON to stdout, so it pairs naturally with jq.

Install

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

This installs the tagesschau binary. To run from a checkout without a global install, use node dist/src/cli/index.js in place of tagesschau (after npm run build).

tagesschau --help

The API needs no key or token — it is fully open and read-only.

Use cases

1. Read the curated front page

Why: get the same editorially-selected top stories that lead tagesschau.de.

tagesschau homepage

The result has a news array (the main feed) and a regional array. To pull just the headlines:

tagesschau homepage | jq -r '.news[].title'

2. Skim headlines with their topline and timestamp

Why: a compact “what’s happening now” digest instead of the full JSON.

tagesschau homepage | jq -r '.news[] | "\(.date[0:10])  [\(.ressort)]  \(.title)"'

Each news item carries title, topline, firstSentence, date, ressort and shareURL, so you can shape the line however you like.

3. Filter the news feed by Ressort

Why: read only one department — e.g. business or sport.

# Economy
tagesschau news --ressort wirtschaft

# Sport
tagesschau news --ressort sport

Valid Ressorts: inland, ausland, wirtschaft, sport, video, investigativ, wissen. The news feed returns news, regional and (when there are more results) a nextPage cursor URL.

4. Get regional news for one Bundesland

Why: focus on a single federal state by its numeric region id (1–16). When you filter by --region, the matching items come back in the news array (each tagged with the requested regionId); the top-level regional array is only populated on the unfiltered homepage feed.

# Niedersachsen (region id 9)
tagesschau news --region 9 | jq -r '.news[].title'

5. Regional news across several Bundesländer

Why: watch a few states at once. --region is repeatable; the client joins the ids into a single comma-separated regions query (e.g. regions=5,9).

# Bremen (5) and Niedersachsen (9)
tagesschau news --region 5 --region 9

The feed returns one page per request, shared by all requested states, so each state gets fewer items than it would on its own.

6. A Ressort within a region

Why: e.g. domestic-politics news scoped to specific states. The API can’t do this server-side: when --ressort and --region are both given, it applies the Ressort and ignores the region (every item comes back with regionId: 0). Fetch the region feed and filter locally instead; regional items carry no ressort, so match on title, topline or tags.

tagesschau news --region 9 \
  | jq -r '.news[] | select((.title + " " + (.topline // "")) | test("Schule"; "i")) | .title'

7. Full-text search across articles

Why: find coverage of a topic by keyword.

tagesschau search "Bundestag"

The result includes searchResults, totalItemCount, and the echoed searchText/pageSize/resultPage. Count the hits and list titles:

tagesschau search "Bundestag" | jq '.totalItemCount'
tagesschau search "Bundestag" | jq -r '.searchResults[].title'

An empty search text is rejected by the CLI before any request is made.

8. Page through search results

Why: walk large result sets. --result-page is a 0-based page index (0, the default, is the first page); --page-size must be >= 1.

# 20 results per page, second page
tagesschau search "Wahl" --page-size 20 --result-page 1

9. List the live / broadcast channels

Why: discover the linear and streaming programme feeds and their stream URLs.

tagesschau channels | jq -r '.channels[].title'

Each channel exposes title, streams and image/copyright metadata.

10. Machine-friendly, single-line output

Why: feed downstream tooling or log a compact record.

tagesschau --compact homepage

--compact is a global option, so it goes before the command.

Global options

These apply to every command and must appear before the command name (e.g. tagesschau --compact news --ressort sport).

Exit codes: 0 success, 4 on a 404 from the API, 1 for any other error, and a non-zero usage error from the parser for invalid arguments.