CLI 参数¶

完整 flag 列表。也可以跑 --help 查看：

futu-opend --help
futu-mcp --help
futucli --help

`futu-opend`¶

Flag	默认	说明
`--login-account <id>`	—	牛牛号（必填之一）
`--login-pwd <pwd>`	—	登录密码明文（v1.4.18+ 会打 deprecation WARN，推荐走 keychain）
`--login-pwd-md5 <hex>`	—	登录密码 MD5（同样 argv 暴露，会 WARN）
`--login-pwd-file <path>`	—	v1.4.18+：从文件读密码（Docker secrets / systemd LoadCredential 友好）
`--login-region <gz/sh/hk>`	—	后端连接区域（v1.4+）
`--config <path>`	—	TOML 配置文件（v1.4.2+），字段和 CLI 参数一致，CLI 覆盖
`--cfg-file <path>`	—	XML 配置文件，兼容 C++ `FutuOpenD.xml` 格式
`--ip <addr>`	`0.0.0.0`	监听 IP
`--port <n>`	`11111`	FTAPI TCP 端口
`--rest-port <n>`	—	REST 端口（含 `/ws`）
`--rest-keys-file <path>`	—	REST Bearer Token keys.json
`--grpc-port <n>`	—	gRPC 端口
`--grpc-keys-file <path>`	—	gRPC Bearer Token keys.json
`--websocket-port <n>`	—	核心 WS 端口（Futu SDK）
`--ws-keys-file <path>`	—	核心 WS 握手鉴权 keys.json（v1.0+）
`--telnet-port <n>`	—	管理 telnet
`--telnet-ip <addr>`	`127.0.0.1`	管理 telnet 监听 IP，仅在 `--telnet-port` 启用时生效
`--lang <chs/cht/en>`	auto	界面语言；不传时跟随系统语言，未知语言回退英文
`--log-level <level>`	`info`	`trace/debug/info/warn/error`
`--json-log`	false	stdout JSON 日志
`--audit-log <path>`	—	审计 JSONL 文件或目录 (v1.4.87+ dir 0700 / file 0600 on Unix)
`--tz <IANA>`	—	v1.4.87+：时区覆盖 (如 `Asia/Hong_Kong` / `America/New_York`)，影响 hours_window 限额检查
`--client-sig-proactive-refresh`	false	v1.4.122+：长跑 daemon 在 `client_sig` 到期前 1h 主动刷新；默认关闭，可用 TOML 同名字段或 env 兼容入口打开
`--client-sig-reactive-refresh`	false	v1.4.122+：reconnect 连续 TCP 登录失败时尝试刷新 `client_sig`；默认关闭，可用 TOML 同名字段或 env 兼容入口打开
`--rsa-private-key <path>`	—	RSA 私钥 PEM（给客户端用 RSA 加密）
`--platform <futunn/moomoo>`	`futunn`	账号平台（v1.4.14+）。`futunn`=牛牛（CN/HK），`moomoo`（US/SG/AU/JP/CA）
`--auth-server <url>`	根据 `--platform` 推导	自定义认证服务器 URL，覆盖 `--platform`
`--device-id <hex>`	自动派生	设备 ID（16 位 hex，v1.4.16+）。显式指定并更新 `~/.futu-opend-rs/device-<hash>.dat`
`--reset-device`	false	v1.4.17+：启动前清空 device + credentials 文件，下次 login 走完整首登（SMS）
`--setup-only`	false	v1.4.17+：只完成首登 + 凭据缓存就退出，不启动 server（systemd/Docker 场景）

`futu-mcp`¶

Flag	默认	说明
`--gateway <addr>`	`127.0.0.1:11111`	网关 TCP 地址
`--keys-file <path>`	—	keys.json（scope 模式）
`--api-key <plaintext>` / env `FUTU_MCP_API_KEY`	—	启动时绑定的 key 明文
`--enable-trading`	false	(legacy) 允许交易写工具；配 keys-file 时忽略
`--allow-real-trading`	false	(legacy) 允许 real 环境；配 keys-file 时忽略
`--audit-log <path>`	—	审计 JSONL
`--http-listen <addr>`	—	HTTP transport（v1.0+），不传则 stdio
`-v, --verbose`	false	debug 日志

`futucli`¶

CLI vs REST/MCP 参数命名对照（v1.4.84 加）¶

CLI 的 9 个命令原本用位置参数（<OWNER> / <SYMBOLS> / <GROUP> 等），和 REST/MCP 的命名参数习惯（--code / --owner / --acc-id）不一致。 v1.4.84 起 CLI 加了 REST/MCP 风格 alias，位置参数依旧 work（向后兼容）。

命令	位置参数	v1.4.84+ alias	示例
`option-chain`	`<OWNER>`	`--owner` / `--code`	`futucli option-chain --owner US.AAPL --begin 2026-05-15 --end 2026-06-20`
`option-expiration-date`	`<OWNER>`	`--owner`	`futucli option-expiration-date --owner HK.800000`
`suspend`	`<SYMBOLS>`	`--code` / `--symbols`	`futucli suspend --code HK.00700 --begin 2026-04-01 --end 2026-04-15`
`margin-ratio`	`<SYMBOLS>`	`--code` / `--symbols`	`futucli margin-ratio --code HK.00700 --market HK --acc-id <acc>`
`user-security`	`<GROUP>`	`--group`	`futucli user-security --group MyList`
`plate-stocks`	`<PLATE>`	`--plate`	`futucli plate-stocks --plate HK.BK1001`
`acc-cash-flow`	`<ACC_ID>`	`--acc-id`	`futucli acc-cash-flow --acc-id <acc> --date 2026-04-15`
`plate-list`	`--set <SET>`	`--plate-type`	`futucli plate-list -m HK --plate-type industry`
`daemon-status`	`--rest-url <URL>`	`--rest-port <PORT>`	`futucli daemon-status --rest-port 22222`

两种风格可任选。位置参数适合 shell 速查，--owner/--code 适合脚本 / 从 REST/MCP API 文档复制命名。

全局¶

Flag	默认	说明
`-g, --gateway <addr>` / env `FUTU_GATEWAY`	`127.0.0.1:11111`	网关地址
`-o, --output <format>`	`table`	`table` / `json` / `jsonl`（jsonl 每行一个 JSON，适合管道）
`-v, --verbose`	false	debug 日志
`--audit-log <path>`	—	审计 JSONL（v1.2+）

按分类浏览命令¶

futucli 的根命令保持平铺、向后兼容；commands 只是发现入口，用来按分类浏览或搜索现有命令，不改变脚本里的 canonical 命令名。

futucli commands
futucli commands --group quote
futucli commands --search calendar
futucli -o json commands --group system

可用分类：common、quote、trade、account、key、system、research、advanced。

版本更新检查¶

futucli version 默认只打印本地版本，不访问网络：

futucli version

需要检查是否有新版时显式加 --check：

futucli version --check

检查请求优先访问公开的 https://futuapi.com/version.json，不携带账号、持仓、设备或交易信息；默认入口不可用、返回非 2xx 或使用不兼容的 schema_version 时会 fail closed，不给出升级建议。doctor 默认会用短超时做同样的检查，并在有新版时生成一条诊断 finding；离线环境可以加 --no-update-check：

futucli doctor --no-update-check

测试镜像站或 staging 时可用 --url / FUTU_UPDATE_CHECK_URL 覆盖检查入口。

子命令¶

子命令	说明
`commands [--group <group>] [--search <text>]`	按分类浏览或搜索 futucli 命令；仅用于发现，不改变现有命令名
`version [--check] [--url <URL>] [--timeout-ms <MS>]`	显示本地版本；加 `--check` 才请求公开 `version.json` 检查新版本。默认检查 `https://futuapi.com/version.json`；入口不可用、非 2xx 或 schema 不兼容时 fail closed；可用 `--url` 或 `FUTU_UPDATE_CHECK_URL` 覆盖
`lang-pack status/import/update`	管理 StringID 语言包 cache；CLI `update` 只在显式指定 `--endpoint <HTTPS>` 时联网。daemon 默认开启后台检查，但未配置 endpoint 时状态为 `enabled_no_endpoint`，不发起网络请求
`ping`	ping 网关
`quote <symbols...>`	实时报价
`snapshot <symbols...>`	快照
`kline <symbol> [--type day] [--count 100]`	K 线
`orderbook <symbol> [--depth 10]`	买卖盘
`ticker <symbol> [--count 100]`	逐笔
`rt <symbol>`	分时
`static <symbols...>`	静态信息
`static-status [--rest-url/--rest-port]`	v1.4.122+：查看 daemon 静态证券缓存与 stock-list 同步状态
`static-warmup <symbols...>`	v1.4.122+：显式 warmup 指定证券的静态信息缓存
`broker <symbol>`	经纪商队列
`plate-list <market>`	板块集合列表
`plate-stocks <plate-id>`	列出板块内股票
`sub <symbols...> -t <types>`	订阅（types: basic/orderbook/ticker/broker/rt/kline）
`account`	账户列表
`funds <acc-id> --market HK`	资金
`position <acc-id> --market HK`	持仓
`order <acc-id> --market HK`	当日订单
`deal <acc-id> --market HK`	当日成交
`unlock-trade --env real [--trade-pwd-account <LOGIN_ACCOUNT>] [--otp <code>] [--security-firm <FIRM>] [--acc-ids <CSV>]`	解锁交易；密码来源优先级为 `--from-stdin` > `FUTU_TRADE_PWD` > OS keychain > 交互式 prompt。`--trade-pwd-account` 读取 `set-trade-pwd --account` 写入的账号级 keychain 条目；未传时可用 `FUTU_TRADE_PWD_ACCOUNT` / `FUTU_ACCOUNT` 作为账号 hint。v1.4.31+ `--otp` 传令牌动态密码；v1.4.33+ `--security-firm` 只解锁该券商；v1.4.34+ `--acc-ids` 只解锁指定账户
`set-trade-pwd`	把交易密码写入 OS keychain（供 `futucli unlock-trade` 与 futu-mcp 的 `futu_unlock_trade` 工具读；v1.4+）
`clear-trade-pwd`	从 OS keychain 删除交易密码（v1.4+）
`set-login-pwd --account <id>`	v1.4.18+：把某账号的登录密码存 OS keychain（opend 启动免 `--login-pwd`）
`clear-login-pwd --account <id>`	v1.4.18+：删除 keychain 里某账号的登录密码
`gen-key --id <n> --scopes <list>`	生成 key
`list-keys`	列所有 key
`revoke-key <id>`	吊销
`bind-key <id> --this-machine / --replace / --clear / --freeze`	就地改机器绑定
`machine-id [--for-key <id>]`	查本机机器指纹
`repl`	交互式 REPL（共享长连接 + 推送实时显示）
`history-orders / history-deals`	v1.4.25+：历史订单 / 成交查询
`max-qtys`	v1.4.25+：下单前算最大可买卖量
`trade-check --market <M> --code <CODE> --price <P>`	v1.4.122+：只读交易预检；先 warmup 静态信息，再做 `max-qtys` 试算，不下单
`place-order / modify-order / cancel-order`	v1.4.25+：下单 / 改单 / 撤单（real 必须 `--confirm`，默认 env=simulate）
`capital-flow <symbol>`	v1.4.26+：资金流时间序列
`capital-distribution <symbol>`	v1.4.26+：资金分布（超大/大/中/小单流入流出）
`market-state <symbols>`	v1.4.26+：市场状态（开盘/休市/午休/盘后）
`owner-plate <symbols>`	v1.4.26+：股票所属板块
`option-chain <owner> --begin --end [--delta-min/--iv-max/...]`	v1.4.26+：期权链（按到期日 call/put 列表；支持 Greek server-side filter）
`trading-days --market --begin --end`	v1.4.30+：交易日列表
`rehab <symbol>`	v1.4.30+：复权因子（长期 K 线对齐 / 回测必用）
`suspend <symbols> --begin --end`	v1.4.30+：停牌日查询
`user-security <group>`	v1.4.30+：自选股分组下的股票
`user-security-groups [--group-type]`	v1.4.30+：自选股分组列表
`warrant [--owner] [--num]`	v1.4.30+：涡轮列表（按成交量降序）
`ipo-list --market <HK/US/CN/SG/JP/MY>`	v1.4.30+：新股 IPO
`ipo-calendar --market <HK/US/CN/SG/JP/MY> [--event list] [--begin-date YYYYMMDD] [--end-date YYYYMMDD]`	v1.4.122+：把 IPO 列表投影为日历事件（上市 / 申购 / 中签 / 日本 IPO 询价等）
`financial-calendar --market <HK/US/...> --begin-date YYYYMMDD --end-date YYYYMMDD [--watchlist-only/--positions-only] [--custom-filter TYPE[:MIN[:MAX]]]`	v1.4.122+：财报日历全市场视图；自选 / 持仓过滤为移动端 calendar 后端的显式筛选开关，支持排序与自定义过滤
`financial-calendar-target --stock-id <id> --market <HK/US/...> [--size 20] [--start 0]`	v1.4.122+：按股票 ID 查询目标股票财报日历（mobile/moomoo CMD20426）
`future-info <symbols>`	v1.4.30+：期货合约资料
`stock-filter --market [--begin --num]`	v1.4.30+：条件选股最小版（高级过滤走 REST）
`cancel-all-order <acc-id> [--market] [--confirm]`	v1.4.30+：全部撤单（real 必须 `--confirm`）
`global-state`	v1.4.30+：网关全局状态（市场开闭/服务器版本/登录状态）
`user-info`	v1.4.30+：用户信息（昵称/权限/配额）
`delay-statistics`	v1.4.30+：延迟统计概要
`query-subscription [--all-conn]`	v1.4.30+：查询当前订阅状态
`used-quota`	v1.4.122+：查询当前已用订阅额度和历史 K 线额度
`unsubscribe [--symbols --sub-types] [--all]`	v1.4.30+：反订阅行情数据
`history-kl-quota [--detail]`	v1.4.30+：历史 K 线已用 / 剩余 / 总下载配额；CLI 额外显示额度来源说明
`holding-change <symbol> --category`	v1.4.30+：持股变动（高管 / 机构 / 基金）
`modify-user-security <group> --op <symbols>`	v1.4.30+：修改自选股分组
`code-change <symbols>`	v1.4.30+：股票代码变更 / 临时代码（目前港股）
`set-price-reminder <symbol> --op`	v1.4.30+：设置到价提醒
`price-reminder [--symbol/--market]`	v1.4.30+：查询到价提醒
`option-expiration-date <owner>`	v1.4.30+：期权到期日列表
`sub-acc-push <acc-ids>`	v1.4.30+：订阅账户推送（订单 / 成交变更）
`unsub-acc-push <acc-ids>`	v1.4.122+：按账号 ID 列表取消账户推送订阅
`acc-cash-flow <acc-id> --date / --date-range`	v1.4.30+：账户资金流水（v1.4.32+ 支持日期范围，31 天硬上限，自动跳周末）
`daemon-status [--rest-url --api-key]`	v1.4.32+：daemon 健康快照（登录 / broker 通道 / cipher 就绪度）
`doctor [--rest-url/--rest-port] [--symbol <SYMBOL>] [--bundle <DIR>] [--no-update-check]`	v1.4.122+：聚合 REST readiness / push / quota / metrics 诊断；提供 `--symbol` 时额外查询 market-state 与 quote-capability，用于区分闭市、开市断流、行情权限或静态缓存问题；默认短超时检查公开 `version.json` 并在有新版本时给出升级提示，离线环境可用 `--no-update-check` 跳过；`--bundle` 写出脱敏诊断目录
`surface [--gaps] [--checklist <ENDPOINT>]`	v1.4.122+：从 EndpointSpec 输出 REST / MCP / CLI / Gateway 覆盖视图；`--gaps` 只看显式未暴露项及原因；v1.4.122+ `--checklist` 按 canonical / REST path / MCP tool / CLI subcommand 输出新增或变更 endpoint 的防漏清单；配合 `--output markdown` 可生成适合 review / handoff 粘贴的 Markdown 清单
`daemon-reload [--rest-url --api-key]`	v1.4.32+：清 cipher 缓存 + v1.4.47 刷新磁盘凭据（remember-login）
`daemon-shutdown [--rest-url --api-key]`	v1.4.32+：请求 daemon 进入优雅退出路径，systemd / Docker 决定是否重启

3401+ proto-json 命令¶

earnings-calendar、macro-indicator-*、fed-watch-*、dividend-*、 economic-calendar、*-rank、hot-list、heat-map-data、institution-*、 ark-*、industrial-*、rating-change、rise-fall-distribution 等 3401+ 只读入口使用 --c2s-json 透传 generated proto 的 C2S JSON。

这些入口保持严格 proto-json 行为：字段名使用 Rust generated proto 的 snake_case，market 是 Qot_Common.QotMarket 数字枚举，不接受 "US" / "HK" 这类字符串。常用值：

市场	`market`
HK	1
US	11
SH	21
SZ	22
SG	31
JP	41
AU	51
MY	61
CA	71
FX	81
CC	91

最小示例（完整清单见发布包内 examples/qot-3401-plus-proto-json-examples.json）：

futucli earnings-calendar \
  --c2s-json '{"market":11,"begin_date":"2026-06-25","end_date":"2026-06-25"}'

futucli dividend-calendar \
  --c2s-json '{"market":11,"date":"2026-06-25","count":20}'

futucli macro-indicator-list \
  --c2s-json '{"region":1}'

futucli top-movers-rank \
  --c2s-json '{"market":11,"count":20}'

futucli heat-map-data \
  --c2s-json '{"market":11,"count":20}'

如果误写成 {"market":"US"}，CLI 会直接报错并提示应使用数字枚举，例如 {"market":11}。

机构、产业链、板块详情接口不要手填猜测 ID。先跑发现入口，再把返回 ID 带入详情：

futucli institution-list \
  --c2s-json '{"market":11,"count":20}'

futucli institution-profile \
  --c2s-json '{"market":11,"institution_id":<上一步返回的 institution_id>}'

futucli industrial-chain-list \
  --c2s-json '{"market":11,"count":20}'

futucli industrial-chain-detail \
  --c2s-json '{"chain_id":<上一步返回的 chain_id>}'

发布包内还带有只读真机 smoke：

python3 scripts/qot_3401_plus_discovery_chain_smoke.py \
  --futucli ./futucli \
  --gateway 127.0.0.1:11111 \
  --chain all

该脚本验证 list -> extract id -> detail，用于发版前或排障时确认 institution_id、chain_id、plate_id 的发现链仍可用。若后端返回 ret=-1 或发现入口为空，错误文案会带 qot3401.* 诊断码，并提示需要回传 market、C2S JSON、daemon 日志和 smoke 输出。

static-status 读取 daemon 的 /api/admin/status，用于判断静态证券缓存是否适合做行情/静态信息 parity 复测。关键字段含义：

ready：静态缓存是否已经完成首轮同步、零差量收敛且有可用证券行。
reason / action：解释当前状态为什么未就绪，以及下一步应等待、运行 static-warmup，还是把 counters 附到 bug 报告里。
security_count：当前内存里的静态证券行数。
stock_list_readiness：综合状态桶，常见值包括 empty、bootstrap_only、 sync_in_progress、recoverable_retrying、first_sync_ready、converged。
stock_list_*_total：stock-list 同步的启动、完成、失败、可恢复重试与零差量计数。
findings：面向排障的可读提示；doctor 也会把这类静态数据状态汇总进 static-data finding。如果仍在 warming/retry，建议等到 stock_list_readiness=converged 后再做静态信息数量或校验值对比。

doctor --symbol <MARKET.CODE> 会额外查询该标的的 market-state 和 quote-capability。market-state 用于判断闭市 / 午休 / 盘前盘后导致的无 push； quote-capability 会把 orderbook、snapshot、basic quote 等权限判断中的 reason / action 汇总进诊断 finding。若日股等市场缺行情权限，优先在官方 Futu/moomoo App 开通对应市场行情权限，再用 futucli quote-rights 与 futucli quote-capability <SYMBOL> 复查。

部分用户可见提示会带 [diag:<key>]，例如 [diag:quote.permission.open_market]。这是稳定诊断码，便于把 CLI、REST、 MCP 或日志里的同类问题对应到同一类排障动作；它不是错误码，翻译或文案优化不会改变这个 key。

K 线命名说明：CLI 统一使用 kline 子命令；REST 路径使用 /api/history-kline，MCP 工具使用 futu_get_history_kline。CLI 没有 history-kline 子命令。

诊断命令说明：trade-check 不会调用下单接口；默认 table 输出会实际执行 static-info 与 max-qtys 两个只读步骤。json/jsonl 输出只返回预检计划，便于脚本先审阅参数。