Unofficial CLI and TypeScript client for the FRED API (Federal Reserve Economic Data) — designed for AI agents.
- 31 FRED API endpoints mapped 1:1 to CLI commands
- Zero runtime dependencies — Node 18+ native
fetchandparseArgs - JSON output by default — structured, agent-friendly, pipe to
jq - CSV and table formats —
--format csvor--format tablefor human workflows - Truncation detection — auto-adds
_truncatedand_next_offsetto JSON when results are paginated - TypeScript library — import
FredClientfor programmatic use with full type safety - All FRED features — realtime periods, vintage dates, data transformations, frequency aggregation
npm install -g @fiale-plus/fred-cli
export FRED_API_KEY=your-key-here
fred series search "consumer price index" --limit 5
fred series observations CPIAUCSL --units pch --limit 12
fred series GDPGet a free API key at: https://fred.stlouisfed.org/docs/api/api_key.html
# Global (CLI usage)
npm install -g @fiale-plus/fred-cli
# Local (library usage)
npm install @fiale-plus/fred-cliRequires Node.js >= 18.0.0.
fred series <series_id> # Get series metadata
fred series observations <series_id> # Get data observations
fred series search <search_text> # Search for series
fred series categories <series_id> # Get series categories
fred series release <series_id> # Get series release
fred series tags <series_id> # Get series tags
fred series updates # Recently updated series
fred series vintagedates <series_id> # Get vintage dates
fred series search-tags <search_text> # Tags for a search
fred series search-related-tags <search_text> # Related tags for a search| Flag | Values | Description |
|---|---|---|
--units |
lin chg ch1 pch pc1 pca cch cca log |
Data value transformation |
--frequency |
d w bw m q sa a |
Aggregation frequency |
--aggregation-method |
avg sum eop |
How to aggregate |
--output-type |
1 2 3 4 |
Observation output type |
--observation-start |
YYYY-MM-DD |
Start date filter |
--observation-end |
YYYY-MM-DD |
End date filter |
--vintage-dates |
YYYY-MM-DD,... |
Comma-separated vintage dates |
fred category [category_id] # Get category (default: root)
fred category children [category_id] # Get child categories
fred category related <category_id> # Get related categories
fred category series <category_id> # Get series in category
fred category tags <category_id> # Get category tags
fred category related-tags <category_id> # Get related tagsfred releases # Get all releases
fred releases dates # Get all release dates
fred release <release_id> # Get release metadata
fred release dates <release_id> # Get release dates
fred release series <release_id> # Get series on release
fred release sources <release_id> # Get release sources
fred release tags <release_id> # Get release tags
fred release related-tags <release_id> # Get related tags
fred release tables <release_id> # Get release tablesfred sources # Get all sources
fred source <source_id> # Get source metadata
fred source releases <source_id> # Get releases for sourcefred tags # Get all/search tags
fred tags series # Get series matching tags
fred related-tags # Get related tagsTag options: --tag-names, --tag-group-id, --search-text, --exclude-tag-names
| Flag | Description |
|---|---|
--api-key <key> |
API key (or set FRED_API_KEY env var) |
-f, --format <json|csv|table> |
Output format (default: json) |
--realtime-start <YYYY-MM-DD> |
Realtime period start |
--realtime-end <YYYY-MM-DD> |
Realtime period end |
--limit <n> |
Max results (API defaults vary by endpoint) |
--offset <n> |
Result offset for pagination |
--sort-order <asc|desc> |
Sort order |
--order-by <field> |
Sort field (varies by endpoint) |
The CLI respects FRED API defaults per endpoint. When results are paginated:
- JSON: Adds
_truncated: trueand_next_offsetfields - Table: Shows footer:
Showing N of M results. Use --limit and --offset to paginate. - CSV: Adds comment header with count info
| Endpoint | Default Limit |
|---|---|
series/observations |
100,000 |
series/search |
1,000 |
series/updates |
100 |
releases, sources, tags |
1,000 |
series/vintagedates |
10,000 |
import { FredClient } from "@fiale-plus/fred-cli";
const fred = new FredClient(process.env.FRED_API_KEY!);
// Get GDP observations as percent change
const obs = await fred.getObservations("GDP", {
units: "pch",
frequency: "a",
limit: 10,
});
console.log(obs.observations);
// Search for series
const results = await fred.searchSeries("unemployment rate", { limit: 5 });
console.log(results.seriess);
// Browse categories
const children = await fred.getCategoryChildren(0);
console.log(children.categories);All 31 endpoints are available as typed methods on FredClient.
Get a free API key at: https://fred.stlouisfed.org/docs/api/api_key.html
Set it as an environment variable:
export FRED_API_KEY=your-key-hereOr pass it per-command:
fred series GDP --api-key your-key-heregit clone https://github.com/fiale-plus/fred-cli.git
cd @fiale-plus/fred-cli
npm install
npm run build
npm test
# Dev mode (runs TypeScript directly)
npm run dev -- series GDP
npm run dev -- series observations CPIAUCSL --units pch --limit 5
# Integration tests (requires FRED_API_KEY)
FRED_API_KEY=your-key npm run test:integrationThis is an unofficial, community-maintained tool. It is not affiliated with, endorsed by, or connected to the Federal Reserve Bank of St. Louis, the Federal Reserve System, or any government entity.
This tool accesses the publicly available FRED API. FRED is a registered trademark of the Federal Reserve Bank of St. Louis.
Data retrieved through this tool is sourced from FRED and is provided for informational purposes only. It should not be used as the sole basis for financial decisions. Always verify data against official sources.
This software is provided "AS IS" under the MIT License, without warranty of any kind.