fredq 0.3.0

LLM-friendly CLI for raw FRED (Federal Reserve Economic Data) API JSON.

fredq

FRED Query — Federal Reserve Economic Data on the command line.

fredq brings the FRED (Federal Reserve Economic Data) HTTP endpoints to the command line. It is built for scripts, agents, and quick terminal work that needs the JSON returned by the FRED API.

The project stays deliberately close to the source. It does not reshape FRED responses, define economic domain models, or add a discovery API beyond CLI help.

Features

• Raw FRED JSON on stdout, with no pretty-printing or interpretation.
• Endpoint-specific commands for every public FRED API endpoint.
• Generated help that includes examples, parameters, and known value sets.
• Typed Parquet output for series observations when a long time series is more useful as a columnar table than as JSON.
• ALFRED point-in-time support (--realtime-start, --realtime-end, series vintage-dates).
• GeoFRED / Maps regional data (geofred subcommands): regional time series, all-region snapshots, series-group metadata, and GeoJSON shape files.

Install

fredq is a Python 3.10+ project. Install it as a tool with uv or with pip:

uv tool install fredq
# or
pip install fredq

Then run:

fredq --help

From Source

To run from a local checkout (development):

uv sync --all-groups
uv run fredq --help

Or install the checkout as a tool:

uv tool install .
fredq --help

API Key

The FRED API requires a free API key. Request one at https://fred.stlouisfed.org/docs/api/api_key.html.

fredq reads the key from, in order:

1. The FRED_API_KEY environment variable.
2. The first non-empty line of ~/.fredq/api_key.
3. The --api-key flag (visible in process listings; prefer the env var).

On POSIX systems, restrict the key file so only your user can read it:

chmod 600 ~/.fredq/api_key

fredq emits a warning if the file is readable by group or world. To disable the file fallback entirely (for hermetic runs), set FREDQ_DISABLE_KEY_FILE=1 or pass --no-key-file.

fredq never prints, logs, or echoes the API key. The key is also redacted from URLs in error messages and from any httpx debug logs emitted under --verbose.

Quick Start

Show metadata for a series:

uv run fredq series show GNPCA

Fetch a series' observations:

uv run fredq series observations CPIAUCSL

Apply a unit transformation and frequency aggregation:

uv run fredq series observations CPIAUCSL --units pch --frequency m

Search for a series by keyword:

uv run fredq series search "10-year treasury" --limit 10

Browse the FRED category tree from the root:

uv run fredq category children 0

List recent economic releases:

uv run fredq release list --limit 10

List recent release publication dates across all releases:

uv run fredq release calendar --limit 20

Show metadata for a specific release (53 = GDP):

uv run fredq release show 53

Find all series tagged with a set of FRED tags:

uv run fredq tag series "usa;monthly;cpi" --limit 25

ALFRED point-in-time: see what GDP looked like on a past date:

uv run fredq series vintage-dates GNPCA
uv run fredq series observations GNPCA --realtime-start 2024-09-25

Fetch GeoFRED regional data — per-capita income by state for one year:

uv run fredq geofred series-group WIPCPI
uv run fredq geofred series-data WIPCPI --start-date 2022-01-01

Parquet Output

series observations can write a typed Parquet table instead of raw JSON. Parquet output is included in a plain install — no extra required. Pass --format parquet --out PATH:

uv run fredq series observations CPIAUCSL --units pch --frequency m \
  --format parquet --out cpi_yoy.parquet

On success a single JSON descriptor line goes to stdout (the file format, out path, row count, byte size). The Parquet schema is date (date32), value (float64), realtime_start (date32), realtime_end (date32). FRED's missing-value sentinel . is written as NaN. The full response envelope (count, offset, limit, observation range, units, sort order) and the request context (units, frequency, realtime range) are stored as schema key-value metadata so the table is self-describing.

Parquet writes are scoped to series observations only; every other command stays JSON-only, and rejects --format parquet with a usage error. Parquet output assumes FRED's default observation layout (one row per observation); fredq does not expose FRED's alternative output_type modes.

Discovering IDs

Most commands take an ID as a positional argument. If you don't know one yet, start with the commands that need no ID, then chain:

# Find a series ID by keyword
uv run fredq series search "unemployment rate" --limit 10

# List the catalogs
uv run fredq release list --limit 1000  # release IDs
uv run fredq source list                # source IDs
uv run fredq tag list --limit 50        # tag names

# Walk the category tree from the root (0 = root)
uv run fredq category children 0

Then use the ID with the matching command:

uv run fredq series observations DGS10
uv run fredq category series 106
uv run fredq release series 10

Commands

Use root help to see the command list:

uv run fredq --help

Current commands, grouped by how often they're reached for:

Daily-driver fetches

Command	FRED data
series show	Show metadata for one FRED series (title, units, frequency, observation range).
series observations	Fetch the observation values for one FRED series.

Series discovery

Command	FRED data
series search	Search FRED series by keyword.
series search-tags	List tags for a series full-text search.
series search-related-tags	List tags related to a search and existing tag filter.
tag series	List series matching a set of FRED tags.
tag list	List all FRED tags.
tag related	List tags related to an existing tag filter.

Series-bound analysis

Command	FRED data
series vintage-dates	List vintage dates (revision dates) for one FRED series.
series categories	List categories that contain a given series.
series tags	List tags assigned to a FRED series.
series release	Show the release that a FRED series belongs to.
series updates	List recently updated FRED series.

Category browse

Command	FRED data
category show	Show metadata for one FRED category.
category children	List child categories of a FRED category.
category related	List categories related to a given FRED category.
category series	List series belonging to one FRED category.
category tags	List tags for series in one FRED category.
category related-tags	List tags related to a category and existing tag filter.

Releases and calendar

Command	FRED data
release list	List all FRED economic data releases.
release calendar	List release dates across all FRED releases.
release show	Show metadata for one FRED release.
release dates	List publication dates for one FRED release.
release series	List series belonging to one FRED release.
release sources	List sources for one FRED release.
release tags	List tags for one FRED release.
release related-tags	List tags related to a release and existing tag filter.
release tables	Fetch the hierarchical data table for one FRED release.

Sources

Command	FRED data
source list	List all FRED data sources.
source show	Show metadata for one FRED source.
source releases	List releases published by one FRED source.

GeoFRED / Maps (geofred subcommands)

Command	FRED data
geofred series-group	Show GeoFRED series-group metadata (region type, season, frequency, units).
geofred series-data	Fetch the regional time series for one FRED series.
geofred regional-data	Fetch a regional snapshot — all regions for a single date.
geofred shapes	Download a GeoJSON shape file for a region type, to --out.

The GeoFRED endpoints use a different base URL and return regional data keyed by FIPS code. geofred shapes returns Highcharts-format GeoJSON whose coordinates are in a Lambert Conformal Conic projection (not WGS84); reproject before mixing with lat/lon basemaps. See fredq geofred --help for the full subcommand list.

A bare group prints its list of subcommands; each leaf command has its own adaptive help:

uv run fredq series --help              # group: lists the series subcommands
uv run fredq series observations --help # leaf: full endpoint help
uv run fredq series search --help
uv run fredq release calendar --help

Leaf-command help is the primary documentation surface. It shows the FRED target endpoint, accepted parameters, allowed value sets, defaults, and examples.

Dates, Booleans, and Tag Lists

Date parameters accept:

• YYYY-MM-DD calendar dates.
• ISO 8601 datetimes (the time component is dropped; UTC assumed for naive values).
• Unix timestamps in seconds (≥10 digits).

Boolean parameters accept common true and false forms such as true, false, 1, 0, yes, and no.

Tag lists (--tag-names, --exclude-tag-names) use semicolons as separators, matching FRED's wire format:

uv run fredq tag series "usa;annual"

ALFRED Point-in-Time

Most endpoints accept --realtime-start and --realtime-end to view data as of a historical date (the ALFRED archival API). Combined with series vintage-dates, this lets you replay what an analyst would have seen on a specific past date — useful for backtests and for distinguishing data revisions from real-time signals.

# When were GNP revisions published?
uv run fredq series vintage-dates GNPCA

# What did GNP look like on 2024-09-25?
uv run fredq series observations GNPCA \
  --realtime-start 2024-09-25 --realtime-end 2024-09-25

Output Contract

fredq writes the FRED response body to stdout exactly as returned. This makes it easy to pipe into tools that expect JSON:

uv run fredq series show GNPCA | jq .
uv run fredq release list --limit 25 | jq '.releases[].name'

Diagnostics, warnings, and errors are written to stderr. The exit code is 0 on success, 1 on a FRED request failure, and 2 on a usage or configuration error.

Development

Install development dependencies:

uv sync --all-groups

Run the test suite:

uv run pytest

Run checks locally:

uv run black --check .
uv run ruff format --check --diff .
uv run ruff check .
uv run pyright
uv run pytest -n auto

Run the full project check, including Python checks across supported versions and spelling:

uv run tox

When adding or changing command metadata, update validation, adaptive help, and tests together. Then verify the relevant command against FRED with its help, minimal required parameters, and representative optional parameters.

License

fredq is released under the MIT License. See LICENSE.