@fiale-plus/bls-cli

Unofficial CLI and TypeScript client for the BLS Public Data API v2 (Bureau of Labor Statistics) — designed for AI agents.

Features

• Time series data, surveys, and popular series via CLI commands
• Zero runtime dependencies — Node 18+ native fetch and parseArgs
• JSON output by default — structured, agent-friendly, pipe to jq
• CSV and table formats — --format csv or --format table for human workflows
• Built-in shortcuts — bls cpi, bls unemployment, bls jobs for common series
• TypeScript library — import BlsClient for programmatic use with full type safety
• v2 features — catalog metadata, calculations, annual averages, aspects

Quick Start

npm install -g @fiale-plus/bls-cli
export BLS_API_KEY=your-key-here

bls cpi --start-year 2020 --end-year 2024
bls series CUUR0000SA0 LNS14000000
bls unemployment --calculations

Get a free API key at: https://www.bls.gov/developers/home.htm

Installation

# Global (CLI usage)
npm install -g @fiale-plus/bls-cli

# Local (library usage)
npm install @fiale-plus/bls-cli

Requires Node.js >= 18.0.0.

CLI Usage

Series Command

bls series <id> [<id2>...]                     # Get time series data

Shortcut Commands

bls cpi                                        # CPI-U All Items (CUUR0000SA0)
bls unemployment                               # Unemployment Rate (LNS14000000)
bls jobs                                       # Total Nonfarm Employment (CEU0000000001)

Discovery Commands

bls popular                                    # 25 most popular series
bls surveys                                    # List all surveys
bls survey <id>                                # Survey metadata
bls search <text>                              # Help finding series IDs

Series Options

| Flag | Description | |------|-------------| | --start-year <YYYY> | Start year for data | | --end-year <YYYY> | End year for data | | --catalog | Include catalog metadata (v2 only) | | --calculations | Include net/percent changes (v2 only) | | --annual-average | Include annual averages (v2 only) |

Common Options

| Flag | Description | |------|-------------| | --api-key <key> | API key (or set BLS_API_KEY env var) | | -f, --format <json\|csv\|table> | Output format (default: json) | | --help | Show help | | --version | Show version |

API Key

The BLS API works without a key (v1 mode, limited), but v2 features require registration.

• Without key: 25 queries/day, 10 years max, no catalog/calculations
• With key: 500 queries/day, 20 years max, full v2 features

Get a free key at: https://www.bls.gov/developers/home.htm

Set it as an environment variable:

export BLS_API_KEY=your-key-here

Or pass it per-command:

bls cpi --api-key your-key-here

Library Usage

import { BlsClient } from "@fiale-plus/bls-cli";

const bls = new BlsClient(process.env.BLS_API_KEY);

// Get CPI data
const data = await bls.getSeriesData(
  ["CUUR0000SA0"],
  { startYear: "2020", endYear: "2024", calculations: true },
);
console.log(data.Results.series);

// Get popular series
const popular = await bls.getPopularSeries();
console.log(popular);

// List surveys
const surveys = await bls.getSurveys();
console.log(surveys);

Development

git clone https://github.com/fiale-plus/bls-cli.git
cd bls-cli
npm install
npm run build
npm test

# Dev mode (runs TypeScript directly)
npm run dev -- cpi --start-year 2023 --end-year 2024
npm run dev -- series CUUR0000SA0 LNS14000000

# Integration tests (requires BLS_API_KEY)
BLS_API_KEY=your-key npm run test:integration

Disclaimer

This is an unofficial, community-maintained tool. It is not affiliated with, endorsed by, or connected to the Bureau of Labor Statistics, the U.S. Department of Labor, or any government entity.

This tool accesses the publicly available BLS Public Data API. Data retrieved through this tool is sourced from BLS and is provided for informational purposes only. It should not be used as the sole basis for financial or policy decisions. Always verify data against official sources.

This software is provided "AS IS" under the MIT License, without warranty of any kind.

Links

• BLS API Documentation
• API Key Registration
• GitHub Repository
• npm Package

License

MIT