Metadata-Version: 2.4
Name: fed-debt
Version: 0.1.0
Summary: Check the current US federal debt to the penny
Author-email: xorn the first <x0rn@gitlab.com>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/x0rn/fed-debt
Project-URL: Repository, https://gitlab.com/x0rn/fed-debt
Project-URL: Bug Tracker, https://gitlab.com/x0rn/fed-debt/-/issues
Keywords: treasury,debt,us-debt,finance
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business :: Financial
Classifier: Intended Audience :: End Users/Desktop
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx
Requires-Dist: rich
Provides-Extra: ticker
Requires-Dist: windows-curses; sys_platform == "win32" and extra == "ticker"
Dynamic: license-file

# fed-debt 🇺🇸

Check the current US federal debt, to the penny.

```
$ fed-debt
$39,828,435,390,891.55

$ fed-debt --verbose
               US Federal Debt — 2026-08-04
┌──────────────────────────────┬──────────────────────┐
│ Metric                       │              Amount   │
├──────────────────────────────┼──────────────────────┤
│ Total Public Debt Outstanding │ $39,828,435,390,891.55 │
│ Debt Held by the Public       │ $32,100,703,256,953.12 │
│ Intragovernmental Holdings    │  $7,727,732,133,938.43 │
│ Debt per US Citizen           │            $118,890.85 │
└──────────────────────────────┴──────────────────────┘
```

## Install

### From PyPI (recommended)

```bash
pip install fed-debt
```

Or with ticker support (requires `windows-curses` on Windows):

```bash
pip install "fed-debt[ticker]"
```

### From source

```bash
git clone https://gitlab.com/x0rn/fed-debt.git
cd fed-debt
py -m pip install -e .
```

Or for the ticker:

```bash
py -m pip install -e ".[ticker]"
```

## Usage

| Command                | What it does                                    |
|------------------------|-------------------------------------------------|
| `fed-debt`             | Prints the latest total debt to the penny       |
| `fed-debt --verbose`   | Detailed breakdown table with per-citizen debt  |
| `fed-debt --ticker`    | Opens a small live-updating ticker window       |
| `fed-debt --version`   | Prints version number                           |
| `fed-debt --help`      | Shows usage                                     |

### Ticker

The `--ticker` flag opens a thin, 3-line curses window that shows a
**continuously incrementing** debt counter. Instead of polling the API
every few seconds (wasteful — the data only updates once a day at
3:00 PM ET), it:

1. Fetches the latest official reading on startup
2. Estimates the per-second growth from recent history (~$1.3B/day)
3. Interpolates the current value in real-time

Press `q` to quit, `r` to force a re-sync with the Treasury API.

## Data Source

U.S. Treasury Fiscal Data — [Debt to the Penny](https://fiscaldata.treasury.gov/datasets/debt-to-the-penny)
endpoint, updated daily at 3:00 PM ET.

## Future

- `--chart` — terminal-based historical charts (via `plotext`)
- `--since` — see the debt on a specific past date
- GUI/web backend using the same `api.py` module
