> ## Documentation Index
> Fetch the complete documentation index at: https://doc.astreus.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Command line
> astreus — Astreus from the terminal, with a citation on every number.
`astreus` 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 Astreus. The
[data catalog](/data-catalog) lists the command for every dataset.
```bash theme={null}
npm install -g astreus-cli
```
Node 18 or later. No native modules. `npx astreus-cli …` works without installing.
Coming from `prometheus-terminal`? Uninstall it (`npm uninstall -g prometheus-terminal`)
and install `astreus-cli`; the command is now `astreus` instead of `prom`. Your saved key
and any `PROMETHEUS_*` environment variables keep working.
Create a key on [astreus.ai/developers](https://astreus.ai/developers), then:
```bash theme={null}
astreus login
```
The prompt is hidden, the key is validated against the API before it is saved, and it is
stored in `~/.config/astreus/config.json` (mode `0600`). In CI or an agent, pipe it
instead: `echo "$KEY" | astreus login --with-key`, or just set `ASTREUS_API_KEY`.
```bash theme={null}
astreus 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: astreus fact-source NVDA std:revenue 2026-01-25
```
And the filing behind one cell:
```bash theme={null}
astreus 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
```
## Twenty things to try
```bash theme={null}
astreus coverage # what is covered, market by market — no key needed
astreus search "unemployment rate" # resolve companies, macro series, countries
astreus company NVDA # profile, quote, fundamentals
astreus financials NVDA -q -s cf -p 8 # 8 quarterly cash-flow columns
astreus financials NVDA --as-reported -s bs # the filer's own XBRL presentation instead of the standardized template
astreus as-filed NVDA -s cf -q -p 8 # the cash-flow statement exactly as filed — every caption ever printed, one column per quarter
astreus segments XSAU000001 # Almarai's revenue by product, cited to the deck slide it came from
astreus sections NVDA && astreus section NVDA 277126 # the parsed 10-Q sections, then the MD&A text
astreus note-tables NVDA -f DEBT_SCHEDULE # the debt note's tables across the filing history, each with its gate verdicts
astreus note-series NVDA DEBT_SCHEDULE -p 8 # the same note as a time series, every point citing its filing
astreus transcript NVDA | less # latest earnings call, streamed as text
astreus guidance NVDA # what management promised, and how past guidance resolved
astreus transcript-search "rate cut" --summary # who is saying it on calls, by quarter and company
astreus mentioned-by NVDA # where customers, suppliers and rivals name NVDA on their own calls
astreus event NVDA 0001045810-25-000023 # the text of an 8-K item (item code auto-resolved)
astreus ownership NVDA --transactions --filter Purchases
astreus macro US UNEMPLOYMENT_RATE -n 12 # point-in-time macro history
astreus officials US --changes # arrivals, departures and pending nominations
astreus news -c XDFM000002 --follow # DEWA's news tape, live
astreus correlate -a stock:NVDA -b macro:UNEMPLOYMENT_RATE --ta pct_change --tb first_difference
```
`astreus --help` lists every command; `astreus --help` shows its flags and examples.
## Identifiers
`` 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](/coverage).
## Two conveniences the raw API does not give you
* **Transcripts.** The API requires both a transcript id and its date. `astreus transcript NVDA`
streams the latest call; `astreus transcript NVDA 31919` looks the date up from the index.
* **8-K items.** `/events/{accession}` needs an `item` code. `astreus 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 `astreus --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 (`astreus 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, `astreus` 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.
* `astreus me` shows the plan, limits and live usage for the calling key; `astreus llms` prints
[llms.txt](https://astreus.ai/llms.txt) so an agent can read its own manual.
Agents: run `astreus llms --skill` once, then work in `--json` mode and branch on exit codes.
Every figure you relay should carry the accession from `astreus fact-source`.
## MCP server
`astreus mcp` serves the [Astreus MCP tool set](/mcp-server) over stdio — the same 18 read-only
tools as the hosted `https://astreus.ai/api/mcp` endpoint, with each call
going through the CLI's key resolution and retry behaviour:
```bash theme={null}
claude mcp add astreus --env ASTREUS_API_KEY=pk_live_... -- astreus mcp
```
stdout carries the protocol, so run it from an MCP client, not by hand. See the
[MCP page](/mcp-server) for the tool list and other clients.
## Analytics descriptors
`astreus correlate` and `astreus 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 `astreus catalog` (`--macro`, `--fundamentals`, `--search`).
## Configuration
| Setting | Flag | Environment | Config file |
| ---------------- | ---------------------------------- | -------------------------------------------------------------------------------- | ----------- |
| API key | `--api-key` | `ASTREUS_API_KEY` | `apiKey` |
| API origin | `--base-url` | `ASTREUS_BASE_URL` | `baseUrl` |
| Config directory | — | `ASTREUS_CONFIG_DIR` (else `$XDG_CONFIG_HOME/astreus`, else `~/.config/astreus`) | — |
| 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 "$(astreus completion bash)" # bash
eval "$(astreus completion zsh)" # zsh
astreus completion fish | source # fish
```
## Versioning
`astreus --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.