npm package: @fiale-plus/bls-cli
Description: Unofficial CLI and TypeScript client for the BLS API (Bureau of Labor Statistics) — designed for AI agents
Author: fiale-plus
Latest version: 0.1.0

# @fiale-plus/bls-cli

[![npm version](https://img.shields.io/npm/v/@fiale-plus/bls-cli.svg)](https://www.npmjs.com/package/@fiale-plus/bls-cli)
[![npm downloads](https://img.shields.io/npm/dm/@fiale-plus/bls-cli.svg)](https://www.npmjs.com/package/@fiale-plus/bls-cli)
[![Test](https://github.com/fiale-plus/bls-cli/actions/workflows/test.yml/badge.svg)](https://github.com/fiale-plus/bls-cli/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Unofficial** CLI and TypeScript client for the [BLS Public Data API v2](https://www.bls.gov/developers/) (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

```bash
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

```bash
# 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

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

### Shortcut Commands

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

### Discovery Commands

```bash
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:

```bash
export BLS_API_KEY=your-key-here
```

Or pass it per-command:

```bash
bls cpi --api-key your-key-here
```

## Library Usage

```typescript
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

```bash
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](https://www.bls.gov/developers/). 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](https://www.bls.gov/developers/)
- [API Key Registration](https://www.bls.gov/developers/home.htm)
- [GitHub Repository](https://github.com/fiale-plus/bls-cli)
- [npm Package](https://www.npmjs.com/package/@fiale-plus/bls-cli)

## License

[MIT](LICENSE)