Command line

prom is the official command-line client. It wraps the API — statements, segments, filings and sections, decks, transcripts, guidance, events, news, ownership, people, macro, markets, intelligence and analytics — 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. The data catalog lists the command for every dataset.

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

Seventeen things to try

prom coverage                                   # what is covered, market by market — no key needed
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 filer's own XBRL presentation instead of the standardized template
prom as-filed NVDA -s cf -q -p 8                # the cash-flow statement exactly as filed — every caption ever printed, one column per quarter
prom segments XSAU000001                        # Almarai's revenue by product, cited to the deck slide it came from
prom sections NVDA && prom section NVDA 277126  # the parsed 10-Q sections, then the MD&A text
prom note-tables NVDA -f DEBT_SCHEDULE          # the debt note's tables across the filing history, each with its gate verdicts
prom note-series NVDA DEBT_SCHEDULE -p 8        # the same note as a time series, every point citing its filing
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 news -c XDFM000002 --follow                # DEWA's news tape, live
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), a numeric SEC CIK (1045810), or a platform key for a non-SEC issuer (XSAU000001 for Almarai on Tadawul, XDFM000002 for DEWA on DFM); tickers are upper-cased for you. Accession numbers are accepted with or without dashes, and source document references (SAU-2280-2025FY-FS) work wherever an accession does. Country codes are ISO-2 (US, SA). See Coverage.

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 how to get more volume. 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.

MCP server

prom mcp serves the Prometheus MCP tool set over stdio — the same 18 read-only tools as the hosted https://www.prometheus.services/api/mcp endpoint, with each call going through the CLI’s key resolution and retry behaviour:

claude mcp add prometheus --env PROMETHEUS_API_KEY=pk_live_... -- prom mcp

stdout carries the protocol, so run it from an MCP client, not by hand. See the MCP page for the tool list and other clients.

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 contract in the same repository, so the CLI never silently drifts from the API it ships with.

Getting started

Coverage

Data

Concepts

Guides

For AI agents

Seventeen things to try

Identifiers

Two conveniences the raw API does not give you

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

MCP server

Analytics descriptors

Configuration

Shell completion

Versioning

​Seventeen things to try

​Identifiers

​Two conveniences the raw API does not give you

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

​MCP server

​Analytics descriptors

​Configuration

​Shell completion

​Versioning

Seventeen things to try

Identifiers

Two conveniences the raw API does not give you

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

MCP server

Analytics descriptors

Configuration

Shell completion

Versioning