echopai

Command-line interface for the EchoPai Open Platform. Programmatic access to A-share stock-market data, news, analyst views, sentiment, financials, concepts, limit-up board, announcements, and digest fan-out over https://api.echopai.com, with automatic failover to the mirror domain https://api.huishengpai.com when the primary is unreachable.

AI-first: JSON envelope on stdout, JSON error envelope on stderr, three-state exit codes — suitable for scripts, CI pipelines, Claude Desktop / Cursor / Claude Code MCP integration, and agent loops.

Install

Two ways — pick whichever fits.

A. npm (Node.js 20+)

npm install -g echopai
echopai --version

Or run without installing:

npx -y echopai market status

B. Standalone binary (no Node required) — 一键安装

自带 Bun runtime，无需 Node。安装器自动判平台（AVX2→baseline / musl / Rosetta）并 强制 sha256 校验：

curl -fsSL https://downloads.echopai.com/echopai-cli-releases/install.sh | bash
# 指定版本：
curl -fsSL https://downloads.echopai.com/echopai-cli-releases/install.sh | bash -s -- 2.4.0

主域连不上（国内网络常见）时换镜像域，同一个 R2 桶，内容完全一样：

curl -fsSL https://downloads.huishengpai.com/echopai-cli-releases/install.sh | bash

脚本跑起来之后的下载会在两个域之间自动互备；但脚本本身也托管在 CDN 上， 主域拉不到 install.sh 时只能直接用上面这条镜像域命令。

默认装到 ~/.local/bin/echopai（可用 ECHOPAI_INSTALL_DIR 改）。装到临时目录做验证时 带上 ECHOPAI_SKIP_MCP=1，否则末尾的 MCP 自动注册会把全局 ~/.claude.json 指到那个 一次性路径。Windows 用户手动下载 echopai-windows-x64.exe。平台矩阵、CDN 布局与发布 流程见 docs/CLI_RELEASE_AND_DISTRIBUTION.md。

Auth

# Save key to ~/.config/echopai/config.toml (mode 0600)
echopai login --key eps_live_<lookup>_<secret>

# Or pass per-invocation via env (CI / agent)
ECHOPAI_KEY=eps_live_xxx echopai market status

Get a key at the EchoPai admin console.

Endpoints & failover

Two official API domains back each other up. They front the same origin and return byte-identical responses, so the CLI is free to switch between them:

| Domain | Role | |---|---| | https://api.echopai.com | primary (default) | | https://api.huishengpai.com | mirror — used when the primary is unreachable |

When a request fails at the transport layer (DNS, connection reset, TLS handshake, timeout) or hits a Cloudflare per-zone TLS edge error (525 / 526), the CLI retries it on the other domain. The working domain is remembered in ~/.config/echopai/endpoint_state.json for 24h so a blocked network costs you one failed attempt, not one per command. Failover is bidirectional — if the mirror goes down, requests fall back to the primary.

Ordinary HTTP errors (4xx, 5xx) are not retried on the other domain: same origin, same answer, and a pointless retry would burn credits twice.

echopai doctor                 # per-domain reachability + which one is in use
echopai --debug quote --codes SSE:600519   # prints `! failover <from> → <to>` when it happens

| Env var | Effect | |---|---| | ECHOPAI_BASE_URL | Entry domain. An official domain still gets failover; a custom one (staging / self-hosted) never does — it stays pinned so a network blip can't silently redirect you to production. | | ECHOPAI_NO_FAILOVER=1 | Pin to a single domain. For diagnosing one domain in isolation. |

Highlights

echopai lookup --text 贵州茅台                       # 中文名 → canonical_code
echopai digest --code SSE:600519                     # 一键研究摘要（A 股 6 桶 fan-out）
echopai digest --code HK:00700                        # 港股/中概 digest（仅 views+news）
echopai quote --codes SSE:600519,SZSE:000001         # 1-200 只实时报价
echopai market movers --sort speed --top 20          # 3-min 涨速榜
echopai sentiment overview --date 2026-05-20         # 任意历史日的情绪聚合
echopai concepts alerts                              # 概念异动 (big_move / limit_up_cluster)
echopai limit-up summary                             # 涨停数 / 炸板数 / 连板梯队
echopai financials quote-snapshot --code SSE:600519  # PE/PB/PS/换手率/股息率 14 字段估值快照

echopai init --key <eps_live_...> --all --all-agents # 一条命令全接入：密钥持久化 + skill×2 + 三家项目 MCP + AGENTS.md
echopai init                                         # 最小接入：装 base skill + Claude Code 项目 MCP + AGENTS.md
echopai mcp install --all-agents                     # 把 MCP 写进本机所有 agent 的全局配置
echopai mcp serve                                    # 起 MCP stdio 服务给 Claude/Cursor
echopai skill install                                # 装 agent skill 到 ~/.claude/skills（用法策略+坑）
echopai skill install --all                          # 另装 echopai-analyst（A股盘面研究策略层）

echopai welcome 显示完整命令面板 + 鉴权状态。

Documentation

📖 docs/CLI.md —— install / auth / persona / verb 总览 / MCP / I/O 约定 / pagination / write safety / 设计原则 / 版本号约定 全在这里。

📋 docs/partner-api/cli-reference.md —— 自动生成的完整 endpoint 参数表，每个 op 的 inputSchema / scopes / 示例 / 输出 schema。

📝 CHANGELOG.md —— 版本变更记录。

Self-update

echopai upgrade           # 读取 stable policy，显示当前/最新/最低支持版本
echopai upgrade --check   # 跳过本地 cache，强制刷新 R2 stable policy
echopai upgrade --exec    # 立即按当前安装方式升级

普通命令和 mcp serve 会在写任何结果/协议输出前检查更新（5 分钟 cache，失败同窗退避）； 发现已晋级版本时自动升级，成功后用原参数重跑一次。策略不可达或升级失败但版本仍 ≥ minimum_supported 时放行并提示手动升级；仅低于最低支持版本且过了 published_at + grace_period_hours 宽限窗才返回 cli_update_required 阻断。 Windows standalone 与项目内 node_modules 安装不做自动升级（只提示手动命令）。 可用 ECHOPAI_UPDATE_MODE=notify|off 降级，CI=1 默认关闭。 源码开发时建议显式设置 ECHOPAI_UPDATE_MODE=off。

Development

工具链是 Bun（install / test / build / compile 全用 bun； codegen 仍是 Python）。npm 包产物 dist/bin.js 仍 node ≥20 兼容。

bun install            # 装依赖（bun.lock）
bun run dev -- --help  # 直接跑 TS 源（含 codegen）
bun test               # 跑测试（bun:test）
bun run typecheck      # tsc --noEmit（仅 src）
bun run build          # 产 node 兼容 dist/bin.js（bun build --target=node）
bun run compile        # 产各平台 standalone 二进制到 dist/bin/

License

MIT