efinance-cli

Turn efinance into a terminal interface that is easier for humans and agents to reuse

Explicit command tree, unified output layer, reusable watch workflow, and optional technical-indicator enrichment.

Installation · 30-second start · US stock examples · Command map · Indicator enrichment · Project architecture

English | 简体中文 | 繁體中文

Predictable Command names map directly to upstream functions, which makes discovery, scripting, and agent orchestration easier.

Consumable Every result lands in table / json / csv / tsv, so you do not need a different post-processing path for every shape.

Extensible Discovery, parameter reflection, execution, rendering, and enrichment stay separated so the CLI can evolve locally instead of turning monolithic.

Installation

Install from PyPI package the-efinance-cli. The published commands are efinance and efi.

uv add -U the-efinance-cli
efinance --help

pip install -U the-efinance-cli
efinance --help

Python 3.10+ is required.

What This Is

efinance-cli is not a loose script bundle. It is a command-line product layer built on top of efinance.

It compresses the upstream market-data API surface into an explicit command tree, while separating command discovery, parameter introspection, execution, rendering, and technical-indicator enrichment into distinct modules. The goal is not to replace the market library. The goal is to make the existing capability more stable and reusable from a terminal.

30-Second Start

1. Search first efinance search AAPL --market US_stock --result-count 5 --format json If you only know the ticker or company name, the search entrypoint is the safest place to start.

2. Resolve quote_id efinance utils get-quote-id AAPL Common US stocks resolve into a unified identifier such as 105.AAPL.

3. Query data efinance stock get-quote-history AAPL --market-type us_stock --beg 20250102 --end 20250501 --limit 20 You can keep going from there for history, latest quotes, exports, and downstream processing.

Why Not Call the Upstream API Directly

The issue is not missing capability The upstream function surface is large and not easy to browse from a terminal. Different return types need different presentation rules. Cross-cutting concerns like watch, export, transpose, and row limits get rewired repeatedly. Indicator enrichment only makes sense when the result shape is compatible enough.

The CLI solves for stable operational use It turns API capability into a navigable command tree. It centralizes output behavior in one rendering layer. It implements watch as a shared executor feature. It keeps enrichment conservative and shape-aware.

US Stock Examples

Discovery and identifier resolution

efinance search AAPL --market US_stock --result-count 5
efinance search NVDA --market US_stock --format json
efinance utils get-quote-id AAPL

History and export

efinance stock get-quote-history AAPL --market-type us_stock --beg 20250102 --end 20250501 --limit 20
efinance stock get-quote-history MSFT --market-type us_stock --beg 20250102 --end 20250501 --format csv --output msft-history.csv
efinance stock get-quote-history TSLA --market-type us_stock --beg 20250102 --end 20250501 --indicator-level advanced --full

Latest quote and watch loop

efinance common get-latest-quote 105.AAPL --format json
efinance watch --interval 5 common get-latest-quote 105.NVDA --format json
efinance common get-latest-quote 105.MSFT --format json --output msft-latest.json

Output controls

efinance stock get-quote-history AAPL --market-type us_stock --beg 20250102 --end 20250501 --transpose
efinance stock get-quote-history AAPL --market-type us_stock --beg 20250102 --end 20250501 --no-index
efinance stock get-quote-history AAPL --market-type us_stock --beg 20250102 --end 20250501 --format tsv --output aapl.tsv

Note: realtime quote stability depends on the upstream market-data source. The CLI keeps failure states visible instead of hiding network volatility.

Command Map

Top-level command	Role	Typical use
search	Search securities by keyword and optional market enum.	The first stop when you do not know the exact identifier yet.
watch	Wrap any supported subcommand with a refresh loop.	One polling policy across many commands.
stock	Stock-oriented queries.	History, snapshots, latest quote, flows, holder data.
fund	Fund-oriented queries.	Net value, estimated move, positions, report download.
bond	Bond-oriented queries.	Base info, quotes, historical trade and capital flow.
futures	Futures-oriented queries.	Base info, realtime quotes, K-line, trade detail.
common	Shared cross-asset query entrypoints.	Useful when you already know the quote_id.
utils	Search and identifier tooling.	search-quote, get-quote-id, add-market.

Module command groups

stock get-base-info get-latest-quote get-quote-history get-quote-snapshot get-realtime-quotes get-deal-detail get-history-bill get-today-bill get-top10-stock-holder-info get-all-company-performance

fund get-base-info get-fund-codes get-fund-manager get-industry-distribution get-invest-position get-pdf-reports get-period-change get-public-dates get-quote-history get-realtime-increase-rate

bond / futures / common / utils bond.get-base-info bond.get-quote-history futures.get-futures-base-info futures.get-quote-history common.get-latest-quote common.get-quote-history utils.search-quote utils.search-quote-locally utils.get-quote-id utils.add-market

Output Model

Format	Best for	Behavior
table	Direct terminal reading	Default mode for DataFrame-like results.
json	Agent or script pipelines	Best when the next step expects structured data.
csv	Persistence and exchange	Useful for spreadsheets, scripts, and analysis workflows.
tsv	Spreadsheet-friendly export	Same model as CSV, but tab-delimited.

Shared runtime flags:

• --full
• --transpose
• --no-index
• --limit N
• --output PATH
• --encoding utf-8

These flags stay consistent across the entire command tree.

Watch Model

Inline watch efinance common get-latest-quote 105.AAPL --watch --interval 5

Top-level wrapper efinance watch --interval 5 common get-latest-quote 105.AAPL --format json

Shared watch flags:

• --watch
• --interval FLOAT
• --count INT
• --clear / --no-clear

Indicator Enrichment

enrichment/ adds indicator columns when the output shape is compatible enough for history, latest quotes, snapshots, and some realtime lists.

Level	Alias	History window	Realtime limit	Typical use
basic	1	60	50	Moving averages, RSI, KDJ, MACD, and other core observations.
advanced	2	120	80	Trend-strength, channel-style, and broader momentum indicators.
full	3	200	120	Broader coverage including Ichimoku, SAR, pivots, Fibonacci, and support/resistance.

The built-in set is broadly grouped as:

• Trend: MACD, Bollinger Bands, DMI / ADX, SuperTrend, Ichimoku, Donchian, Keltner, Aroon, Parabolic SAR
• Momentum: RSI, KDJ, ROC, CCI, PPO, TRIX, TSI, Williams %R
• Volume: OBV, MFI, CMF, PVT, VWAP, Force Index, Volume Ratio
• Volatility: ATR, NATR, Historical Volatility, Chaikin Volatility, Mass Index
• Price structure: Pivot Points, Fibonacci Retracement, Rolling Support / Resistance

Agent-Friendly Query Path

flowchart LR
  A["Natural-language intent"] --> B["search"]
  B --> C["utils get-quote-id"]
  C --> D["stock / common / futures"]
  D --> E["rendering.py"]
  E --> F["table / json / csv / tsv"]
  D --> G["enrichment/"]

Loading

The stable path is:

search -> get-quote-id -> module query -> structured output / file export

Project Architecture

Execution pipeline

flowchart LR
  API["Upstream efinance API"] --> REG["registry.py"]
  REG --> INT["introspection.py"]
  INT --> CMD["Click command tree"]
  CMD --> EXEC["executor.py"]
  EXEC --> ENR["enrichment/"]
  EXEC --> REN["rendering.py"]
  REN --> OUT["stdout / file output"]

Loading

File / package	Role
efinance_cli/main.py	Process entrypoint.
efinance_cli/app.py	Application assembly.
efinance_cli/commands.py	Root command, module groups, and top-level commands.
efinance_cli/registry.py	Whitelist and command metadata for exposed upstream capability.
efinance_cli/introspection.py	Signature-driven Click parameter synthesis.
efinance_cli/executor.py	Request execution, watch looping, and result emission.
efinance_cli/rendering.py	Output formatting and serialization.
efinance_cli/enrichment/	Technical-indicator enrichment on compatible results.
efinance_cli/indicators/	Reusable indicator math primitives.

Data-Source Boundaries

Outside direct CLI control Temporary network failures Upstream rate limiting Empty responses Market-source instability

CLI behavior It does not silently hide failures. It keeps the error path visible for retries and diagnosis. Retry cadence and query fallback stay in caller control.

How To Extend It

The safest extension path is:

1. Update the upstream function whitelist or help overrides in registry.py.
2. Extend introspection.py only when a new parameter type needs a coercion rule.
3. Extend rendering.py only when a new result shape appears.
4. Extend enrichment/ only when a command family should gain indicator augmentation.
5. Add or update smoke tests for the changed surface.

Quality Bar

The repository currently protects two minimal contracts:

• indicator exports and result shapes
• basic / advanced / full enrichment behavior

The goal is not to prove the trading semantics of every indicator. The goal is to reduce silent regressions in the command and enrichment layers.

Related Docs

Design notes CLI design and usage notes Architecture notes

Entrypoints efinance efi

License

See LICENSE.