@fiale-plus/treasury-cli

Unofficial CLI and TypeScript client for the US Treasury Fiscal Data API — designed for AI agents.

Features

• 14 Treasury API endpoints mapped to intuitive CLI commands
• No API key required — Treasury Fiscal Data API is completely open
• 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
• Truncation detection — auto-adds _truncated and _next_page to JSON when results are paginated
• TypeScript library — import TreasuryClient for programmatic use with full type safety

Quick Start

npm install -g @fiale-plus/treasury-cli

treasury debt
treasury rates --limit 20
treasury exchange --filter "country_currency_desc:eq:Canada-Dollar"
treasury cash --limit 5

No API key needed.

Installation

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

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

Requires Node.js >= 18.0.0.

CLI Usage

Debt Commands

treasury debt                     # Latest total public debt
treasury debt history             # Debt with date range filter
treasury debt mspd                # Monthly statement of public debt
treasury rates                    # Average interest rates on Treasury securities

Daily Treasury Statement Commands

treasury cash                     # Operating cash balance
treasury deposits                 # Deposits & withdrawals of operating cash
treasury debt-transactions        # Public debt transactions
treasury debt-limit               # Debt subject to limit
treasury tax-deposits             # Federal tax deposits
treasury refunds                  # Income tax refunds issued

Monthly Treasury Statement Commands

treasury spending                 # Monthly receipts & outlays (MTS Table 1)
treasury revenue                  # Receipts by source (MTS Table 5)

Exchange Rates

treasury exchange                 # Foreign exchange rates

Raw Query

treasury query <endpoint>         # Query any Fiscal Data endpoint

Common Options

| Flag | Description | |------|-------------| | -f, --format <json\|csv\|table> | Output format (default: json) | | --limit <n> | Max results per page | | --sort <field> | Sort field (-field for descending) | | --filter <field:op:value> | Filter expression | | --fields <field1,field2> | Comma-separated fields to return | | --page <n> | Page number | | --page-size <n> | Page size (alias for --limit) |

Filter Operators

| Operator | Description | |----------|-------------| | eq | Equal to | | lt | Less than | | lte | Less than or equal to | | gt | Greater than | | gte | Greater than or equal to | | in | In list | | range | Within range |

Example: --filter "record_date:gte:2024-01-01"

Pagination and Truncation

The API uses page-based pagination. When results span multiple pages:

• JSON: Adds _truncated: true and _next_page fields
• Table: Shows footer with page info
• CSV: Adds comment header with page info

Library Usage

import { TreasuryClient } from "@fiale-plus/treasury-cli";

const treasury = new TreasuryClient();

// Get latest total public debt
const debt = await treasury.getDebtToPenny({ page_size: 1, sort: "-record_date" });
console.log(debt.data[0].tot_pub_debt_out_amt);

// Get exchange rates for Canada
const rates = await treasury.getExchangeRates({
  filter: "country_currency_desc:eq:Canada-Dollar",
  sort: "-record_date",
  page_size: 5,
});
console.log(rates.data);

// Query any endpoint
const custom = await treasury.query("v1/accounting/dts/operating_cash_balance", {
  page_size: 10,
});
console.log(custom.data);

All endpoints are available as typed methods on TreasuryClient.

Development

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

# Dev mode (runs TypeScript directly)
npm run dev -- debt
npm run dev -- exchange --limit 5

# Integration tests (no API key needed)
npm run test:integration

Disclaimer

This is an unofficial, community-maintained tool. It is not affiliated with, endorsed by, or connected to the US Department of the Treasury, the Bureau of the Fiscal Service, or any government entity.

This tool accesses the publicly available Treasury Fiscal Data API. Data retrieved through this tool is sourced from the US Treasury 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.

Links

• Treasury Fiscal Data API Documentation
• GitHub Repository
• npm Package

License

MIT