Command line

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 lists the command for every dataset.

Install

npm install -g astreus-cli

Node 22.12 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. Run astreus login once: the old ~/.config/prometheus file and PROMETHEUS_BASE_URL are no longer read (PROMETHEUS_API_KEY still is).

Create a key on astreus.ai/developers, then:

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.

Pull real data

astreus financials NVDA

Illustrative terminal layout; query the API for current figures and retain the returned filing reference and period.

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 · 6 periods returned  cite a cell: astreus fact-source NVDA std:revenue 2026-01-25

And the filing behind one cell:

astreus 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

Things to try

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 --filer-lines -s bs        # the filer's own XBRL lines instead of the standardized template
astreus financials NVDA -q --ytd                   # year-to-date columns (3M, 6M, 9M, FY) as the 10-Qs print them
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                     # the most recent call on file, 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-26-000078            # the text of an 8-K item (the API picks the substantive item)
astreus filing DFM-EMAAR-2025FY-FS --company XDFM000001   # Emaar's annual statements as text, paged
astreus ownership NVDA --transactions --filter Purchases
astreus macro AE --catalog --search eibor          # find a series key (keys are never cut)
astreus macro US UNEMPLOYMENT_RATE -n 12           # one macro series (current vintage)
astreus officials US --changes                     # arrivals, departures and pending nominations
astreus news -c XDFM000002 --follow                # DEWA's news tape, live
astreus calendars earnings --country AE            # the earnings calendar, one market
astreus calendars earnings --live                  # the earnings calls being streamed now
astreus earnings NVDA --statements --type guidance # what the speakers said, verified, newest call first
astreus observation 742816                         # one quote with the sentence before and after it
astreus transcript NVDA --timeline                 # when each speaker turn starts in the recording
astreus ownership XSAU000001 --foreign-history     # actual, permitted and available foreign ownership over time
astreus macro AE --regions --region AE-DU          # Dubai's own series (then: astreus macro AE-DU <KEY>)
astreus government AE --entity AE.DU.RTA --series  # the series Dubai's RTA publishes (then: astreus macro-series <ID>)
astreus government US --bills --stage law          # bills that became law; --vote 119/house/1/1 for one roll call
astreus regulation XDFM000003 --central-bank       # Central Bank of the UAE documents that bear on Emirates NBD
astreus debt --issuers --currency USD              # the bond screener, one row per issuer
astreus fed-financials --source --line total_assets --period-end 2025-12-31   # the evidence for one Fed figure
astreus fed-financials --document 290 -o fed-2025.pdf                       # the Board's document itself
astreus crypto bitcoin --prices --range 3M         # daily CoinGecko reference closes
astreus private openai                             # a private company: rounds, KPIs, fund marks, the filings that name it
astreus research filing_diff AAPL                  # the latest 10-K / 10-Q sections against the previous filing
astreus topic-trends tariffs --countries AE,SA     # one topic on calls, by quarter, and who raises it most

astreus --help lists every command; astreus <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 (DFM-EMAAR-2025FY-FS, EMAARIR-2026Q2-PRES) work wherever an accession does (filing then needs --company <id>). People are a CIK or a registry key (XDFMP00001). Country codes are ISO-2 (US, AE). See Coverage.

Conveniences

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.
Paging in one flag. Long text (filing, section, event) prints one window and names the next --offset on stderr; --all reads every window. Lists print the next --offset (or --before for news).

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 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 shared Astreus MCP tool set over stdio. The tool set follows the installed CLI release; hosted and npm releases are separate, so use tools/list to discover each server’s actual capabilities. Each call going through the CLI’s key resolution and retry behaviour:

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 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 (https; http only for localhost)	`--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 <seconds>` (default 60)	—	—

Flags win over the environment, which wins over the config file. Avoid --api-key in shared shells — it lands in history. The key is sent only to the configured origin: on a redirect to another host the CLI drops it. --verbose logs each request (never the key).

Shell completion

eval "$(astreus completion bash)"     # bash
eval "$(astreus completion zsh)"      # zsh
astreus completion fish | source      # fish
astreus completion powershell | Out-String | Invoke-Expression   # PowerShell (add it to $PROFILE)

Versioning

astreus --version prints the CLI version and the SHA-256 of the OpenAPI contract it was built against. The build verifies that the bundled contract matches its source. A server deployment and an npm publication are separate operations; the same API version label does not prove that they contain the same endpoints. Compare the contract hash and use the connected MCP server’s tools/list.

Every data operation from the contract

The operation explorer reaches every endpoint in the contract, including those without a dedicated formatting command:

This page describes CLI 0.6.0. Check astreus --version and npm view astreus-cli version; if npm still serves an earlier release, some commands and flags here are not in it yet.

astreus --json api list --search calendar
astreus api describe get-fx-reference-rates
astreus --json api call get-fx-reference-rates \
  --query base=USD --query codes=AED,SAR

Copy an operation ID from api list or the tool reference. Supply path parameters with repeated --path name=value, filters with repeated --query name=value, and calculation bodies with --body '{...}' or --body @request.json. Missing, unknown and invalid parameters fail before fetching. api describe includes the body schema. Binary/media endpoints require --output filename; text can be returned in a single JSON document with --json. Data reads keep their normal authorization, publication gates and quotas. For an array filter, repeat its query flag, for example --query company=XDFM000002 --query company=0001045810 on the bond screener. Every operation in the contract also has a formatted command or flag, except media a browser plays (call audio and video), page-layout helpers (sparklines, tab presence) and routes under licence review; those stay reachable here. The news stream uses astreus news --follow; the browser-only recording-state POST is excluded from data calls.

Getting started

Coverage

Data

Concepts

Guides

For AI agents

Things to try

Identifiers

Conveniences

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

MCP server

Analytics descriptors

Configuration

Shell completion

Versioning

Every data operation from the contract

​Things to try

​Identifiers

​Conveniences

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

​MCP server

​Analytics descriptors

​Configuration

​Shell completion

​Versioning

​Every data operation from the contract

Things to try

Identifiers

Conveniences

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

MCP server

Analytics descriptors

Configuration

Shell completion

Versioning

Every data operation from the contract