Finance CLI

Research a company. Keep the evidence.

Finance CLI helps you read company filings, inspect financial statements, and check calculations with traceable inputs. Run it in your terminal or let your research agent choose and combine commands.

Start with a question: choose a company research task, see worked examples, or follow the installation guide.

For example, ask what Apple does and what risks it discloses:

finance filings.read AAPL section=business max_chars=4000 --output md
finance filings.read AAPL section=risk_factors max_chars=4000 --output md

These commands return filing excerpts to inspect, with source information when available. Check filing dates and truncation before summarizing. They require SEC access and the current source version described below.

It is designed for repeatable public-company research: commands in, structured output out.

Why This Exists

You can already combine notebooks, yfinance, SEC downloads, PDF parsers, spreadsheet formulas, and backtesting libraries by hand. That works until every company or question needs a slightly different glue script.

Finance CLI packages those recurring research steps into terminal commands with consistent JSON output. The goal is not to hide the underlying sources. It is to make common research moves easy to repeat, inspect, diff, and automate.

Use it when you want to:

• pull a 10-K section without rewriting EDGAR retrieval code
• inspect filing tables without manually searching raw HTML
• scan a long filing and keep stable offsets for follow-up reading
• run finance formulas with explicit inputs and methods
• fetch market context from the same command surface as filings and documents
• run quick strategy checks without starting from a blank notebook

Install

python -m pip install -U finresearch-cli

From a local checkout:

The website and this README describe the current repository. The published package may lag behind; use the source installation below for current commands and output formats. The Quick Start includes an isolated environment and SEC contact setup.

git clone https://github.com/TempestShaw/FinanceCLI.git
cd FinanceCLI
python -m pip install -U .

Check the install:

finance --list
finance sources.status --output json

The base install includes SEC filing access, native PDF/HTML reading, Yahoo market data, and finance formulas. Starting with 0.1.0b1, install advanced capabilities only when needed:

python -m pip install -U "finresearch-cli[tables]"
python -m pip install -U "finresearch-cli[ocr]"
python -m pip install -U "finresearch-cli[backtest]"

Combine extras with "finresearch-cli[tables,ocr,backtest]". For a local checkout, use ".[tables,ocr,backtest]". OCR may download model files on first use.

First Minute

finance filings.recent AAPL forms=10-K,10-Q limit=3
finance filings.statement COST statement=balance query="Common Stock"
finance formula.margin numerator=11969 denominator=254453
finance market.quote AAPL
finance backtest.run sma_cross AAPL 2020-01-01 2024-12-31 fast=20 slow=100

Most commands return JSON by default:

{
  "ok": true,
  "data": {
    "margin": 0.04703815635893466,
    "margin_pct": 4.7038156358934655,
    "inputs": {
      "numerator": 11969.0,
      "denominator": 254453.0
    },
    "method": "numerator / denominator"
  },
  "error": null,
  "warnings": []
}

For output that is readable by both humans and LLMs, use --output md. It leads with a one-line headline answer, follows with humanized tables (percentages, thousands separators), and ends with a source line:

finance formula.margin numerator=11969 denominator=254453 --output md

**margin = 4.70%**

_Inputs_
| Field | Value |
| --- | --- |
| numerator | 11,969 |
| denominator | 254,453 |

method: numerator / denominator

--output table and --output report give rich terminal views; --output pretty-json is for debugging. To make a human format the default for interactive shells, configure it once:

finance config.set output.default md
finance config.set output.non_interactive_default json

Explicit --output flags still override the config. Non-interactive output can stay JSON so pipes, CI, and agents keep a stable parser contract.

Shell Completion

Install completion automatically for your current shell:

scripts/install_completion.sh zsh

When installed from a wheel, the same helper is available as install_completion.sh.

FinanceCLI can print shell completion scripts without modifying your shell files:

finance completion bash > ~/.local/share/bash-completion/completions/finance
finance completion zsh > ~/.zfunc/_finance
finance completion fish > ~/.config/fish/completions/finance.fish

Completions are generated from the live command registry and usage metadata, so command names, global options, and key=value argument enums stay aligned with the CLI.

Mental Model

flowchart LR
    A["finance command"] --> B["research service"]
    B --> C["SEC filings"]
    B --> D["document parsers"]
    B --> E["market data"]
    B --> F["formulas and backtests"]
    C --> G["structured JSON"]
    D --> G
    E --> G
    F --> G
    G --> H["terminal, notebooks, scripts, automation"]

Commands are grouped by research job:

Automation Workflows

Finance CLI works well in local scripts, notebooks, CI jobs, and research automation because commands are small, explicit, and machine-readable.

The document examples below assume a filing or report has been saved locally as ./filing.html.

finance document.scan ./filing.html format=html query="operating lease costs" window=1200
finance document.window ./filing.html format=html match_id=char_52000_52200 direction=next chars=4000
finance filings.statement COST statement=balance query="Common Stock"
finance formula.net_debt debt=11415 cash=11144 operating_cash=5089

A typical automated research workflow is:

1. discover the filing or presentation
2. scan for the relevant section, metric, table, or phrase
3. continue reading from a stable match id or character window
4. calculate the metric with explicit inputs
5. preserve the command and JSON output as audit trail

What You Can Do

More examples are in EXAMPLES.md.

Trust Model

Finance research needs traceable inputs. Finance CLI is built around a few practical rules:

• Source handles: filing commands return accessions, URLs, report names, sections, offsets, or provider names when available.
• Explicit calculations: formula commands include the inputs and method used.
• Scriptable results: commands return predictable JSON with ok, data, error, and warnings fields.
• Local credentials: API keys are read from environment variables at runtime and are not written by the CLI.
• No telemetry: the CLI does not track commands, symbols, queries, or usage.
• Freshness: provider-backed commands reflect the source response at runtime; there is no general stale-cache layer.

Why Not Just A Notebook?

Notebooks are still useful for exploration and visualization. Finance CLI is for the repeated research steps you want to make portable, auditable, and easy to run again.

Data Sources And Keys

Many commands work without a paid key. Some provider-backed commands use environment variables:

SEC filings, native document reading, formulas, and Yahoo market data are included in the base install. PDF tables, OCR, and local backtests use the optional installs above.

Help

finance help filings
finance filings.statement --help
finance document.scan --help

Disclaimer

Finance CLI is for research and automation workflows only. It is not financial advice, investment advice, tax advice, or a recommendation to buy or sell securities.