> ## Documentation Index
> Fetch the complete documentation index at: https://doc.prometheus.services/llms.txt
> Use this file to discover all available pages before exploring further.
# Command line
> prom — Prometheus from the terminal, with a citation on every number.
`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.
```bash theme={null}
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](https://www.prometheus.services/developers), then:
```bash theme={null}
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`.
```bash theme={null}
prom financials NVDA
```
```text theme={null}
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:
```bash theme={null}
prom fact-source NVDA std:revenue 2025-01-26
```
```text theme={null}
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
```bash theme={null}
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 --help` shows its flags and examples.
## Identifiers
`` 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 `
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](https://www.prometheus.services/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 ` (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
```bash theme={null}
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.