Command line

prom is the official command-line client. It wraps every endpoint in the API reference, formats the result for a terminal, and prints the source filing under any financial figure. With --json it returns the API payload verbatim, which makes it the quickest way for scripts and AI agents to use Prometheus.

Install

npm install -g prometheus-terminal

Node 18 or later. No native modules. npx prometheus-terminal … works without installing.

Create a key on prometheus.services/developers, then:

prom login

The prompt is hidden, the key is validated against the API before it is saved, and it is stored in ~/.config/prometheus/config.json (mode 0600). In CI or an agent, pipe it instead: echo "$KEY" | prom login --with-key, or just set PROMETHEUS_API_KEY.

Pull real data

prom financials NVDA

INCOME STATEMENT                  FY2022   FY2023   FY2024   FY2025   FY2026      TTM
  Total Revenue                   26.91B   26.97B   60.92B  130.50B  253.49B  278.02B
  Cost of Revenue                  9.44B   11.62B   16.62B   32.64B   64.14B   ...
  ...
period ends: FY2022 → 2022-01-30 · FY2023 → 2023-01-29 · ...
source: SEC XBRL filings · latest restated · USD · 8 periods  cite a cell: prom fact-source NVDA std:revenue 2026-01-25

And the filing behind one cell:

prom fact-source NVDA std:revenue 2025-01-26

Provenance          filed
Standardized value  130,497,000,000  (130.50B)
Filing              10-K · accn 0001045810-25-000023 · filed 2025-02-26
...
source: 10-K · accn 0001045810-25-000023 · FY2025 · filed 2025-02-26 · provenance filed

Ten things to try

prom search "unemployment rate"                 # resolve companies, macro series, countries
prom company NVDA                               # profile, quote, fundamentals
prom financials NVDA -q -s cf -p 8              # 8 quarterly cash-flow columns
prom financials NVDA --as-reported -s bs        # the balance sheet exactly as filed
prom transcript NVDA | less                     # latest earnings call, streamed as text
prom guidance NVDA                              # what management promised, and how past guidance resolved
prom event NVDA 0001045810-25-000023            # the text of an 8-K item (item code auto-resolved)
prom ownership NVDA --transactions --filter Purchases
prom macro US UNEMPLOYMENT_RATE -n 12           # point-in-time macro history
prom correlate -a stock:NVDA -b macro:UNEMPLOYMENT_RATE --ta pct_change --tb first_difference

prom --help lists every command; prom <command> --help shows its flags and examples.

Identifiers

<id> is a ticker (NVDA) or a numeric SEC CIK (1045810); tickers are upper-cased for you. Accession numbers are accepted with or without dashes. Country codes are ISO-2 (US).

Two conveniences the raw API does not give you

Transcripts. The API requires both a transcript id and its date. prom transcript NVDA streams the latest call; prom transcript NVDA 31919 looks the date up from the index.
8-K items. /events/{accession} needs an item code. prom event NVDA <accession> resolves it when the filing has one coded item, and tells you the choices when it has more.

Machine use: `--json`, exit codes, streams

--json prints the API response verbatim as a single JSON document on stdout — nothing else is written to stdout, so prom --json financials NVDA | jq always parses.
stdout is data; stderr is everything else (progress, warnings, errors). Text endpoints (transcript, section, event, filing) stream plain text so they pipe into less, grep or a file.
Exit codes are stable (prom help exit-codes):

Code	Name	Meaning
0	ok	Success
1	unexpected	Network failure, timeout, or an unexpected error
2	usage	Bad arguments or flags — nothing was sent
3	auth	Missing, invalid or revoked key (HTTP 401)
4	payment	The plan does not include this data (HTTP 402)
5	not-found	Unknown company, filing, series or resource (HTTP 404)
6	rate-limited	Rate limit or monthly quota exhausted (HTTP 429)
7	server	The API returned 5xx

On a 429 with Retry-After of ten seconds or less, prom waits and retries once (--no-retry disables this). Quota exhaustion is never retried; the message carries the reset date and the upgrade link. When fewer than 5% of your monthly requests remain, a single warning is printed on stderr.
prom me shows the plan, limits and live usage for the calling key; prom llms prints llms.txt so an agent can read its own manual.

Agents: run prom llms --skill once, then work in --json mode and branch on exit codes. Every figure you relay should carry the accession from prom fact-source.

Analytics descriptors

prom correlate and prom chart take series descriptors:

Descriptor	Series
`stock:NVDA[:close\|adj_close\|volume]`	Daily stock price
`macro:UNEMPLOYMENT_RATE`	Macro indicator
`fundamental:NVDA:revenue[:quarterly\|annual]`	Standardized statement line
`index:SPY[:close\|adj_close\|volume]`	Benchmark index / ETF
`commodity:H100`	Commodity or compute instrument

The valid vocabularies come from prom catalog (--macro, --fundamentals, --search).

Configuration

Setting	Flag	Environment	Config file
API key	`--api-key`	`PROMETHEUS_API_KEY`	`apiKey`
API origin	`--base-url`	`PROMETHEUS_BASE_URL`	`baseUrl`
Config directory	—	`PROMETHEUS_CONFIG_DIR` (else `$XDG_CONFIG_HOME/prometheus`, else `~/.config/prometheus`)	—
Colour	`--no-color`	`NO_COLOR`, `FORCE_COLOR`	—
Timeout	`--timeout <seconds>` (default 60)	—	—

Flags win over the environment, which wins over the config file. Avoid --api-key in shared shells — it lands in history.

Shell completion

eval "$(prom completion bash)"     # bash
eval "$(prom completion zsh)"      # zsh
prom completion fish | source      # fish

Versioning

prom --version prints the CLI version and the SHA-256 of the OpenAPI contract it was built against. A release is only published when that hash matches the live spec, so the CLI can never silently drift from the API.

Getting started

Concepts

Guides

For AI agents

Ten things to try

Identifiers

Two conveniences the raw API does not give you

Machine use: `--json`, exit codes, streams

Analytics descriptors

Configuration

Shell completion

Versioning

​Ten things to try

​Identifiers

​Two conveniences the raw API does not give you

​Machine use: --json, exit codes, streams

​Analytics descriptors

​Configuration

​Shell completion

​Versioning

Ten things to try

Identifiers

Two conveniences the raw API does not give you

Machine use: `--json`, exit codes, streams

Analytics descriptors

Configuration

Shell completion

Versioning