cninvestcli

Command-line access to A-share and Hong Kong quotes, history, fundamentals, disclosures, valuation, and news. Live public sources, declared fallback chains, and provenance on JSON output.

This is a data CLI, not a trading or research-opinion product.

uv tool install cninvestcli
# or from a clone
uv sync && uv run cninvest --help

Best path (use this)

The registry in src/cninvestcli/providers.py is the source of truth. Commands walk it; they do not silently merge vendors.

Job	Command	What actually works
Latest quote (A / HK)	cninvest market quote 600519 --format json	Tencent → Sina → East Money. JSON includes source, fetched_at, providers_tried.
Stock history, 后复权	cninvest market history 600519 --adjust backward --format csv	Tencent hfqday. Sina daily is the stock fallback.
Full index history	cninvest market history 399989 --from 2010-01-01 --count 10000 --format csv	Tencent only keeps a recent window (~2000 bars) and rejects --from. The next source is CSI official daily (中证医疗 399989: 4041 bars from 2010-01-01). Then Sina index daily. Use CSV, not JSON.
Fundamentals	cninvest fundamentals 600519 --years 5 --format json	East Money → Sina → 同花顺. A 9501 on East Money fails over instead of returning empty.
Dividends	cninvest dividend 600519 --format json	East Money → Sina → CNINFO.
Announcements	cninvest announcements 600519 --format json	East Money list → CNINFO official list. Links only; PDF download is not in this release.
Index valuation	cninvest valuation 000300 --format json	乐咕乐股 PE/PB + CSI dividend yield. Unsupported indexes return honest empty, not mock data.

Indexes are not 后复权. --adjust backward on 399989 still yields official index levels.

# Full 中证医疗 daily (CSI official via fallback)
uv run cninvest market history 399989 --from 2010-01-01 --count 10000 --format csv > 中证医疗.csv

# Tencent 00700 / 贵州茅台
uv run cninvest market quote 00700 --format json
uv run cninvest market history 600519 --adjust backward --count 320 --format csv

Commands

Area	Commands
Discovery	search, price, info
Market	market quote, market history
Research	fundamentals, dividend, shareholder(s), management, announcement(s), revenue, peers, valuation
Disclosure	listing, unlock, holdings-change, fund-holdings, holders-trend
News	news (needs BRAVE_API_KEY)
Watchlist	investment add|get|list|update|delete (top-level add/get/… still work)
Position	position set|get|list|add|returns|export|clear
Alerts	alert, near, stats
Cache	init, refresh, list-cache, clear-cache

cninvest --help
cninvest market history --help
cninvest search 茅台 --format json

Prefer long options (--format json, --limit, --top). search --format json writes status on stderr so stdout stays parseable.

Data sources

Category	Free chain (in order)
Quote	Tencent → Sina → East Money
History (stocks)	Tencent kline → Sina stock_zh_a_daily
History (indexes)	Tencent recent window → CSI official hist → Sina index daily
Fundamentals	East Money → Sina → 同花顺
Dividend	East Money → Sina → CNINFO
Shareholders	East Money → Sina
Announcements	East Money aggregator → CNINFO
Valuation	乐咕乐股 + CSI
News	Brave Search (BRAVE_API_KEY)

Failures are typed (timeout / not_found / schema / rate_limited). East Money 9501 报表配置不存在 is a schema error and the next source is tried. JSON may include provider_errors. Paid terminals (Wind, iFinD, Tushare, …) are documented in the registry and never called without an env key.

See docs/data-sources.md for symbols, limits, and env vars.

Codes

Kind	Examples
A-share	600519, 000001 (平安银行, Shenzhen by default)
ETF	510300, 159915
Index	000300, 399006, 399989 (中证医疗)
HK	00700, 700, 0700.HK
Convertible	113044

000001 is ambiguous (平安银行 vs 上证指数). This CLI defaults to the Shenzhen stock. Pass an explicit sh/sz prefix when you mean the other listing.

Development

uv sync
uv run pytest            # network tests deselected; coverage fail_under=85
uv run pytest -m network tests/test_contract.py
uv run cninvest --help

Python 3.12+. Agent notes: AGENTS.md. Internal backlog: DEV_PLAN_NEXT.md.

Disclaimer

Market data comes from public web APIs that can change or rate-limit. Always check source / fetched_at on JSON. This project is not investment advice and not an official CSI / exchange product.