The command line#

pyeconomics runs every registered model and reads every data source from a shell, so a script, R (system2) or Excel Power Query can use them. A model runs through the same path as the Python API, and --format json prints the same canonical result Result.to_json() gives, byte for byte, followed by one newline. The command line comes with the core package: no extra is needed.

Installation#

Install it as a tool, isolated from your projects, with pipx or uv:

pipx install --pre pyeconomics
uv tool install --prerelease allow pyeconomics

--pre and --prerelease allow are needed while 1.0 is in pre-release. To store providers’ keys in the OS keyring, install the extra too: pipx install --pre "pyeconomics[keyring]".

$ pyeconomics --version

The commands#

Command

What it does

models list [--domain D]

List the registered models

models search TEXT [--limit N]

Search models by id, title, tags, domain and summary

models describe ID [--format markdown|json]

Print a model’s card, or its full description

models run ID [OPTIONS]

Run a model; its inputs are options

models run ID --batch FILE

Run a model once per row of a CSV or JSON Lines file

models run ID [OPTIONS] --narrate

Also explain the result with the optional AI narrative (The AI narrative)

data search TEXT [--limit N]

Search catalog concepts, then providers’ series

data get TARGET [--start] [--end] [--as-of] [--vintage] [--provider] [--transform]

Get a concept’s or a series’ data, transformed if asked

data describe TARGET

Describe a concept, a series or a provider

data vintages TARGET

List the dates a series changed

data sources [--check-keys]

List the providers with their licences and keys

keys set PROVIDER [--stdin]

Store a provider’s key in the OS keyring

keys list

Name where each key would be read from

keys delete PROVIDER

Delete a key from the OS keyring

cache ls [--provider P], cache info, cache clear [--provider P], cache path

Inspect and clear the data cache

registry export --out DIR [--no-figures]

Write DIR/registry.json (The registry export), and DIR/openapi.json with the server extra

bundle check FILE

Verify a reproducibility bundle without running anything from it (Exports and reproducibility bundles)

serve [--host] [--port] [--workers] [--allow-remote]

Serve the REST API on this machine, with the server extra (The REST API), and the web app at / with the app extra

completion SHELL, --install-completion

Shell completion

Every command takes --help, and --debug (anywhere on the line) adds a traceback to a failure. A target is a catalog concept id (us.unemployment.rate) or a provider series (fred:UNRATE), never a URL.

$ pyeconomics --help
$ pyeconomics models list --domain fixed_income
$ pyeconomics models search "present value annuity" --limit 3
$ pyeconomics models describe fixed_income.bond_pricing

Running a model#

models run ID takes one option per input field of the model, its name written with hyphens (present_value is --present-value). A number, a date, a choice or text is written as it is, a boolean as true or false, and an array as a JSON literal. A model with several calculations needs --calculation. pyeconomics models run ID --help lists the model’s own options with their units, and the values each calculation takes.

$ pyeconomics models run foundations.time_value --calculation present_value --rate 0.05 --periods 10 --future-value 100
$ pyeconomics models run foundations.time_value --calculation irr --cash-flows "[-100, 30, 40, 50]" --format table
$ pyeconomics models run foundations.time_value --help

The first prints the result as canonical JSON (abridged here):

{"inputs":{"calculation":"present_value",...},"manifest":{...},"model_id":"foundations.time_value","model_version":2,"outputs":{"calculation":"present_value","present_value":61.391325354075946},"warnings":[]}

The inputs can also come as a JSON object, from a file or from standard input (-); options given beside them override the file’s values. The codec reads at most 16 MiB and refuses repeated keys, NaN and infinity:

pyeconomics models run foundations.time_value --inputs inputs.json --rate 0.06
cat inputs.json | pyeconomics models run foundations.time_value --inputs -

Binding data#

A model that declares data bindings reads its inputs from the data catalog when any of --as-of DATE, --vintage real_time|latest, --profile NAME, --concept FIELD=ID or --param NAME=VALUE is given. --as-of reads the data as published on that date; without it the latest data is read (--profile default binds the default profile so), which a binding that reads a window up to a date refuses. Options for its fields then override the values bound, and the result’s manifest records every series, vintage and retrieval time (Binding models to data):

$ pyeconomics models run macro.recession_probability --as-of 2024-06-28
$ pyeconomics models run macro.recession_probability --as-of 2024-06-28 --format table
$ pyeconomics models run macro.policy_rule --calculation taylor_1993 --profile default

The table prints the data’s sources and, below them, every attribution and notice the data requires.

Data, keys and the cache#

The data commands wrap the data API unchanged, with its modes, licences and keys. data get --format json prints the frame with its source records and the attributions its data must be shown with:

$ pyeconomics data search "unemployment rate" --limit 2
$ pyeconomics data describe us.unemployment.rate
$ pyeconomics data sources
$ pyeconomics data get us.treasury.nominal_10y --start 2024-01-01 --end 2024-01-31 --format table
$ pyeconomics data get us.unemployment.rate --start 2024-01-01 --transform "diff(periods=12)"
$ pyeconomics data vintages fred:UNRATE

A key is never an argument, which shell history would keep. keys set asks for it with a hidden prompt, or reads the first line of standard input with --stdin, checks it and stores it in the OS keyring (Keys and configuration):

pyeconomics keys set fred
my-secrets-tool read fred | pyeconomics keys set fred --stdin

keys list names where each key would be read from (environment, dotenv, keyring or none) and never its value:

$ pyeconomics keys list
$ pyeconomics data sources --check-keys

The cache commands show what is cached, never a payload, and create nothing (The cache and offline mode):

$ pyeconomics cache info
$ pyeconomics cache ls
$ pyeconomics cache path
$ pyeconomics cache clear

registry export writes the description of every model, the file the web app is built from, and with the server extra the REST API’s OpenAPI document:

$ pyeconomics registry export --out site --no-figures

Formats#

--format

Output

json

Canonical JSON (RFC 8785) followed by one newline; the default of models run and data get

table

Tables, drawn with borders on a terminal and as aligned plain text in a pipe or a file, with attributions and notices below; the default of the listing commands

markdown

The model card (models describe only, its default)

csv, xlsx, parquet, arrow

An export with its attributions, notices and manifest (models run and data get; Exports and reproducibility bundles)

--out PATH writes the same bytes to a file instead of standard output. Output is UTF-8 on every operating system, Windows included, whatever the console’s code page. A binary format (xlsx, parquet, arrow) goes to standard output only when it is not a terminal: name a file with --out, redirect it or pipe it. Parquet and Arrow need pyarrow, which pyeconomics never installs; without it they exit with code 8.

$ pyeconomics models run foundations.time_value --calculation present_value --rate 0.05 --periods 10 --future-value 100 --format csv
$ pyeconomics models run foundations.time_value --calculation present_value --rate 0.05 --periods 10 --future-value 100 --format xlsx --out pv.xlsx
$ pyeconomics models run foundations.time_value --calculation present_value --rate 0.05 --periods 10 --future-value 100 --bundle pv.zip

--bundle PATH also writes the run’s reproducibility bundle, a zip that pyeconomics bundle check PATH verifies and its own reproduce.py reruns (Exports and reproducibility bundles). --batch FILE runs the model once per row of a CSV file with a header row of field names, or a JSON Lines file (- reads standard input); it takes no field options, --inputs, --bundle or data options beside it:

pyeconomics models run foundations.time_value --batch rows.csv --format csv --out results.csv
pyeconomics bundle check pv.zip

--narrate also asks the optional AI narrative to explain the result, with your own key (The AI narrative). It follows a table on standard output, and goes to standard error with any other format or --out, so standard output stays the canonical bytes; it is never written into an export or a bundle.

Serving the REST API#

With the server extra, pyeconomics serve serves the REST API on 127.0.0.1 port 8000 until Ctrl+C, its runs in worker processes (The REST API):

pipx install --pre "pyeconomics[server]"
pyeconomics serve --port 8000 --workers 2

It reads every source this machine can access, with its keys, so a host that is not a loopback address is refused (exit code 2) unless --allow-remote is passed. Without the extra it exits with code 8.

With the app extra, which brings the server extra’s requirements and the pyeconomics-app wheel at the same version, the same command also serves the web app at /: every model page, calculator and the data explorer, as pyeconomics.dev serves them, with the same security headers.

pipx install --pre "pyeconomics[app]"
pyeconomics serve

Open http://127.0.0.1:8000. Served locally, the calculators offer live data from every source your installation reaches, library-only ones included, with your own keys where a source needs one, and the data explorer offers the whole catalog rather than the hosted snapshot. The local site loads no analytics and no error tracking and is never indexed, and the API keeps its routes (/v1, /mcp, /docs and the rest). Without the app, serve logs one line saying how to install it and serves the API alone. The site’s policy upgrades insecure requests, as production’s does; browsers exempt loopback addresses, but a browser on another machine (--allow-remote) needs the site behind HTTPS.

Exit codes#

A failure prints one line on standard error, the problem’s slug and a detail that never holds a key, a file path, a host or an upstream URL (Problem types), and exits with its code:

Code

Meaning

0

Success

1

Internal error, an invalid setting or an inconsistent registry

2

The command line does not parse (usage-error)

3

Invalid input

4

The inputs have no defined result, or the method found none

5

Not found: a model, a provider, a concept or a series

6

Not permitted: the source’s licence refuses this use

7

Data unavailable: a key, the source, offline mode or a rate limit

8

An optional extra is not installed

$ pyeconomics models run foundations.time_value --calculation present_value --rate 7
invalid-input: The inputs failed validation: present_value.rate: Input should be less than or equal to 1.

Shell completion#

pyeconomics --install-completion writes the completion script where the current shell looks for it. pyeconomics completion bash (or zsh, fish, powershell) prints the script instead, to install by hand:

$ pyeconomics completion bash

Completion covers the commands and their options; a model’s run options are generated when the command line names the model, so they are listed by pyeconomics models run ID --help.