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

    @maschinenlesbar.org/smard-cli

    smard-cli

    CI Release npm

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

    Query Germany's open electricity-market data from your terminal. smard is a command-line tool over the SMARD chart-data API (smard.de), operated by the Bundesnetzagentur — fetch generation, consumption, residual load and wholesale prices as clean JSON you can pipe straight into jq.

    • Works out of the box — no account, no API key, no configuration. Install and query.
    • Clean JSON output — pretty-printed by default, --compact for one-line/scripting.
    • Seven commands — discover filters/regions, fetch the newest window in one call, or navigate timestamps manually.
    • No credentials to manage — the SMARD API is fully open; this tool only reads.

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

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

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

    Check it works:

    smard --help

    No setup needed — the API requires no key. Your first query:

    smard latest 410 DE week

    That fetches the newest week of total grid load for Germany. The result is a JSON object: time-series values live under series, metadata under meta_data. Pull out just the series with jq:

    smard latest 410 DE week | jq '.series'

    Show just the most recent data point (the window runs to the end of its period, so .series[-1] is usually [ts, null] — skip the nulls):

    smard --compact latest 410 DE week | jq -c '[.series[] | select(.[1] != null)][-1]'

    timestamps  <filter> <region> <resolution>              available window timestamps
series      <filter> <region> <resolution> <timestamp>  one window's data
latest      <filter> <region> <resolution>              newest window's data (one call)
table       <filter> <region> <timestamp>               quarter-hour table_data
filters     [--group generation|consumption|price|forecast]   filter catalogue
regions                                                  valid region codes
resolutions                                              valid resolution values
    Argument What it means
    <filter> Numeric series id — e.g. 410 (total grid load), 4068 (photovoltaics), 4169 (DE-LU wholesale price). Use smard filters to browse all documented ids.
    <region> Grid or bidding-zone code — e.g. DE, DE-LU, TenneT. Use smard regions for the full list.
    <resolution> Temporal granularity: hour, quarterhour, day, week, month, or year. Use smard resolutions to confirm.
    <timestamp> Epoch-millisecond window start from smard timestamps.
    Flag Meaning
    --group <group> Only show one group: generation, consumption, price, or forecast

    Note on table timestamps: table reads the separate table_data endpoint. Its valid window timestamps are not the same set returned by timestamps (which lists chart_data windows). In particular table_data lags chart_data: the newest timestamps windows usually have no table_data yet, so passing a recent timestamp will 404. Use an older window (e.g. a timestamp from earlier in the timestamps list) — those resolve fine.

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

    # What filter ids exist? Show just the consumption group
    smard filters --group consumption

    # Newest week of total grid load for Germany
    smard latest 410 DE week

    # Newest hourly wholesale price for the DE-LU bidding zone (EUR/MWh)
    smard latest 4169 DE-LU hour

    # Newest photovoltaic generation, compact output
    smard --compact latest 4068 DE hour

    # Latest wind onshore and wind offshore generation
    smard latest 4067 DE hour    # Wind Onshore
    smard latest 1225 DE hour    # Wind Offshore

    # Pick a specific window explicitly (available timestamps roll over — don't hard-code one)
    TS=$(smard --compact timestamps 4169 DE-LU hour | jq '.[-1]')
    smard series 4169 DE-LU hour "$TS"

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

    # Count data points in a series window
    smard --compact latest 4068 DE hour | jq '.series | length'

    # Sum all non-null values in a window (total MWh)
    smard --compact latest 4068 DE hour | jq '[.series[][1] | select(. != null)] | add'

    # Save a window to a file
    smard --compact latest 410 DE day > load.json

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

    smard --compact latest 410 DE week | jq -c '.series[-3:]'

    --compact (and every global option) works before or after the command — both smard --compact latest … and smard latest … --compact do the same thing.

    Exit codes make the CLI easy to use in scripts:

    Code Meaning
    0 success (also --help / --version)
    4 resource not found (404) — e.g. a stale timestamp or unknown filter/region combination
    1 any other error: network failure, timeout, parse error, non-404 API status
    non-zero usage / invalid argument (bad region, non-integer filter, etc.)
    • command not found: smard — 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/smard-cli ….
    • Exit 4 / "not found" — the timestamp or filter/region/resolution combination doesn't exist. Re-run smard timestamps <filter> <region> <resolution> to get a fresh list; available windows roll over time. For table, note that table_data timestamps differ from chart_data ones.
    • Exit 1 / network error — connectivity, DNS, or a timeout. Try again, or raise the limit with --timeout 60000.
    • smard timestamps returns an empty array — the API has no data for that filter/region/resolution combination. Verify with smard regions and smard filters that your values are valid.

    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> API base URL (default https://www.smard.de)
    --timeout <ms> Time limit per request in ms, reading the whole response included (0 = no timeout; default 30000; at most 2147483647)
    --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)
    • SKILLS.md — Claude Code Agent Skills that drive this CLI for energy-mix, price-watch and time-series-export tasks.
    • Usage.md — full use-case-driven cookbook.
    • GLOSSARY.md — every domain term, filter group, region code, and data shape explained.
    • 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.

    Bundesnetzagentur — CC BY 4.0. Attribution required, exact source string Bundesnetzagentur | SMARD.de; commercial use and modification allowed.

    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
    smard-cli