CLI flags

Full flag list. You can also run --help on each binary:

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

futu-opend

Flag	Default	Description
--login-account <id>	—	Futu account (one of account/pwd is required)
--login-pwd <pwd>	—	Plain-text login password (v1.4.18+ prints deprecation WARN; prefer keychain)
--login-pwd-md5 <hex>	—	MD5 (same argv exposure as plaintext; same WARN)
--login-pwd-file <path>	—	v1.4.18+: read password from file (friendly for Docker secrets / systemd LoadCredential)
--login-region <gz/sh/hk>	—	Backend region (v1.4+)
--config <path>	—	TOML config file (v1.4.2+); fields mirror CLI flags, CLI wins
--cfg-file <path>	—	XML config, compatible with C++ FutuOpenD.xml
--ip <addr>	0.0.0.0	Listen IP
--port <n>	11111	FTAPI TCP port
--rest-port <n>	—	REST port (also serves /ws)
--rest-keys-file <path>	—	REST Bearer Token keys.json
--grpc-port <n>	—	gRPC port
--grpc-keys-file <path>	—	gRPC Bearer Token keys.json
--websocket-port <n>	—	Core WS port (Futu SDK)
--ws-keys-file <path>	—	Core WS handshake auth keys.json (v1.0+)
--telnet-port <n>	—	Admin telnet
--telnet-ip <addr>	127.0.0.1	Admin telnet listen IP; only used when --telnet-port is enabled
--lang <chs/cht/en>	auto	UI language; omitted value follows the system locale, unknown languages fall back to English
--log-level <level>	info	trace/debug/info/warn/error
--json-log	false	stdout JSON logs
--audit-log <path>	—	Audit JSONL file or directory (v1.4.87+ dir 0700 / file 0600 on Unix)
--tz <IANA>	—	v1.4.87+: Timezone override (e.g. Asia/Hong_Kong / America/New_York), affects hours_window limit checks
--client-sig-proactive-refresh	false	v1.4.122+: long-running daemon proactively refreshes client_sig 1h before expiry; default off; TOML field and compatibility env are also supported
--client-sig-reactive-refresh	false	v1.4.122+: reconnect monitor refreshes client_sig after repeated TCP login failures; default off; TOML field and compatibility env are also supported
--rsa-private-key <path>	—	RSA private key PEM (for RSA-encrypted clients)
--platform <futunn/moomoo>	futunn	Account platform (v1.4.14+). futunn = Futubull (CN/HK), moomoo = US/SG/AU/JP/CA
--auth-server <url>	derived from --platform	Custom auth server URL; overrides --platform
--device-id <hex>	auto-generated	Device ID (16 hex chars, v1.4.16+). Overrides and updates ~/.futu-opend-rs/device-<hash>.dat
--reset-device	false	v1.4.17+: delete device + credentials files before starting, forces full first-login (SMS) on next run
--setup-only	false	v1.4.17+: finish auth + credentials cache, then exit without starting any server (systemd / Docker workflow)

futu-mcp

Flag	Default	Description
--gateway <addr>	127.0.0.1:11111	Gateway TCP address
--keys-file <path>	—	keys.json (scope mode)
--api-key <plaintext> / env FUTU_MCP_API_KEY	—	Plain-text key bound at startup
--enable-trading	false	(legacy) allow trade-write tools; ignored when keys-file is set
--allow-real-trading	false	(legacy) allow the real environment; ignored when keys-file is set
--audit-log <path>	—	Audit JSONL
--http-listen <addr>	—	HTTP transport (v1.0+); if unset, stdio is used
-v, --verbose	false	Debug logs

futucli

CLI vs REST/MCP flag naming (added in v1.4.84)

CLI historically used positional args (<OWNER> / <SYMBOLS> / <GROUP>) while REST/MCP users expect named flags (--code / --owner / --acc-id). As of v1.4.84, CLI adds REST/MCP-style aliases alongside the positional args (backward compatible).

Command	Positional	v1.4.84+ alias	Example
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

Either style works. Positionals are handy for quick shell use; --owner / --code flags feel natural when copy-pasting field names from REST/MCP docs.

Global

Flag	Default	Description
-g, --gateway <addr> / env FUTU_GATEWAY	127.0.0.1:11111	Gateway address
-o, --output <format>	table	table / json / jsonl (jsonl = one JSON per line, pipe-friendly)
-v, --verbose	false	Debug logs
--audit-log <path>	—	Audit JSONL (v1.2+)

Browsing Commands By Category

futucli keeps its root commands flat and backward compatible. commands is a discovery helper for browsing or searching the existing commands; it does not introduce prefixed command names for scripts.

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

Available groups: common, quote, trade, account, key, system, research, advanced.

Version update check

futucli version only prints the local version and does not access the network:

futucli version

Add --check when you want to check for a newer release:

futucli version --check

The check first fetches the public https://futuapi.com/version.json; it does not send account, position, device, or trading data. If the default endpoint is unavailable, returns a non-2xx status, or uses an unsupported schema_version, futucli fails closed and does not produce upgrade advice. doctor performs the same short-timeout check by default and emits a diagnostic finding when a newer version is available. Offline deployments can disable it:

futucli doctor --no-update-check

Use --url / FUTU_UPDATE_CHECK_URL to test a mirror or staging endpoint.

Subcommands

Command	Description
commands [--group <group>] [--search <text>]	Browse or search futucli commands by category; discovery-only, existing command names stay canonical
version [--check] [--url <URL>] [--timeout-ms <MS>]	Show the local version; add --check to fetch the public version.json and check for updates. Defaults to https://futuapi.com/version.json; unavailable, non-2xx, or schema-incompatible manifests fail closed; override with --url or FUTU_UPDATE_CHECK_URL
lang-pack status/import/update	Manage the StringID language-pack cache. CLI update contacts the network only with an explicit --endpoint <HTTPS>. The daemon enables background checks by default, but with no endpoint it reports enabled_no_endpoint and makes no network request
ping	Ping the gateway
quote <symbols...>	Real-time quotes
snapshot <symbols...>	Snapshot
kline <symbol> [--type day] [--count 100]	Candles
orderbook <symbol> [--depth 10]	Level-2 book
ticker <symbol> [--count 100]	Tick-by-tick
rt <symbol>	Intraday time-series
static <symbols...>	Static security info
static-status [--rest-url/--rest-port]	v1.4.122+: show daemon static-security cache and stock-list sync status
static-warmup <symbols...>	v1.4.122+: explicitly warm up static info for selected securities
broker <symbol>	Broker queue
plate-list <market>	Plate/sector list
plate-stocks <plate-id>	Stocks in a plate
sub <symbols...> -t <types>	Subscribe (types: basic/orderbook/ticker/broker/rt/kline)
account	List accounts
funds <acc-id> --market HK	Funds
position <acc-id> --market HK	Positions
order <acc-id> --market HK	Orders of the day
deal <acc-id> --market HK	Fills of the day
unlock-trade --env real [--trade-pwd-account <LOGIN_ACCOUNT>] [--otp <code>] [--security-firm <FIRM>] [--acc-ids <CSV>]	Unlock trading. Password source priority is --from-stdin > FUTU_TRADE_PWD > OS keychain > prompt. --trade-pwd-account reads the account-scoped keychain entry written by set-trade-pwd --account; when omitted, FUTU_TRADE_PWD_ACCOUNT / FUTU_ACCOUNT can provide the account hint. v1.4.31+ --otp for 2FA token; v1.4.33+ --security-firm scopes to one broker; v1.4.34+ --acc-ids restricts per account
set-trade-pwd	Save trade password into the OS keychain (read by futucli unlock-trade and futu-mcp's futu_unlock_trade tool; v1.4+)
clear-trade-pwd	Remove trade password from the OS keychain (v1.4+)
set-login-pwd --account <id>	v1.4.18+: store an account's login password in the OS keychain (futu-opend reads it automatically)
clear-login-pwd --account <id>	v1.4.18+: remove the stored login password for an account
gen-key --id <n> --scopes <list>	Generate a key
list-keys	List all keys
revoke-key <id>	Revoke a key
bind-key <id> --this-machine / --replace / --clear / --freeze	Edit machine binding in place
machine-id [--for-key <id>]	Show this machine's fingerprint
repl	Interactive REPL (shared long connection + live push display)
history-orders / history-deals	v1.4.25+: historical orders / fills query
max-qtys	v1.4.25+: pre-trade max buy/sell qty
trade-check --market <M> --code <CODE> --price <P>	v1.4.122+: read-only trade preflight; warms static info, then runs a max-qtys check; never places an order
place-order / modify-order / cancel-order	v1.4.25+: place / modify / cancel (real env requires --confirm, default env=simulate)
capital-flow <symbol>	v1.4.26+: capital flow time series
capital-distribution <symbol>	v1.4.26+: capital distribution (super/large/medium/small order flow)
market-state <symbols>	v1.4.26+: market state (open / closed / lunch / after-hours)
owner-plate <symbols>	v1.4.26+: plates containing the stock
option-chain <owner> --begin --end [--delta-min/--iv-max/...]	v1.4.26+: option chain (call/put list by expiry; supports Greek server-side filters)
trading-days --market --begin --end	v1.4.30+: trading day list
rehab <symbol>	v1.4.30+: rehab factors (long-term K-line alignment / backtest)
suspend <symbols> --begin --end	v1.4.30+: suspension days
user-security <group>	v1.4.30+: securities in a watchlist group
user-security-groups [--group-type]	v1.4.30+: list watchlist groups
warrant [--owner] [--num]	v1.4.30+: warrant list (volume desc)
ipo-list --market <HK/US/CN/SG/JP/MY>	v1.4.30+: IPO list
ipo-calendar --market <HK/US/CN/SG/JP/MY> [--event list] [--begin-date YYYYMMDD] [--end-date YYYYMMDD]	v1.4.122+: calendar projection over the IPO list (listing / subscription / winning / JP inquiry events)
financial-calendar --market <HK/US/...> --begin-date YYYYMMDD --end-date YYYYMMDD [--watchlist-only/--positions-only] [--custom-filter TYPE[:MIN[:MAX]]]	v1.4.122+: all-market financial calendar view; watchlist / positions filters are explicit switches supported by the mobile calendar backend, with ranking and custom filters
financial-calendar-target --stock-id <id> --market <HK/US/...> [--size 20] [--start 0]	v1.4.122+: target-stock financial calendar lookup by stock id (mobile/moomoo CMD20426)
future-info <symbols>	v1.4.30+: futures contract info
stock-filter --market [--begin --num]	v1.4.30+: stock scanner (minimal; advanced filters via REST)
cancel-all-order <acc-id> [--market] [--confirm]	v1.4.30+: cancel all pending orders (real requires --confirm)
global-state	v1.4.30+: gateway global state (market open/close, server version, login status)
user-info	v1.4.30+: user info (nickname / permissions / quota)
delay-statistics	v1.4.30+: delay-statistics summary
query-subscription [--all-conn]	v1.4.30+: query current subscriptions
used-quota	v1.4.122+: query current used subscription and historical K-line quota
unsubscribe [--symbols --sub-types] [--all]	v1.4.30+: unsubscribe market data
history-kl-quota [--detail]	v1.4.30+: historical K-line used / remaining / total download quota, with a source note in CLI output
holding-change <symbol> --category	v1.4.30+: shareholder changes (executive / institution / fund)
modify-user-security <group> --op <symbols>	v1.4.30+: modify a watchlist group
code-change <symbols>	v1.4.30+: security code changes / temporary tickers (HK for now)
set-price-reminder <symbol> --op	v1.4.30+: set price reminder
price-reminder [--symbol/--market]	v1.4.30+: query price reminders
option-expiration-date <owner>	v1.4.30+: option expiry date list
sub-acc-push <acc-ids>	v1.4.30+: subscribe order/deal push for accounts
unsub-acc-push <acc-ids>	v1.4.122+: unsubscribe account push by account-id list
acc-cash-flow <acc-id> --date / --date-range	v1.4.30+: account cash flow statement (v1.4.32+ adds date range with 31-day cap, auto-skips weekends)
daemon-status [--rest-url --api-key]	v1.4.32+: daemon health snapshot (login / broker channels / cipher readiness)
doctor [--rest-url/--rest-port] [--symbol <SYMBOL>] [--bundle <DIR>] [--no-update-check]	v1.4.122+: aggregate REST readiness / push / quota / metrics diagnostics; with --symbol, doctor also queries market-state and quote-capability to distinguish closed-market/no-push, quote-right, and static-cache issues; by default it performs a short-timeout public version.json check and reports upgrade hints when a newer version is available; offline environments can pass --no-update-check; --bundle writes a redacted diagnostics directory
surface [--gaps] [--checklist <ENDPOINT>]	v1.4.122+: print REST / MCP / CLI / Gateway coverage from EndpointSpec; --gaps shows only explicitly non-exposed surfaces and reasons; v1.4.122+ --checklist prints the endpoint-addition / change checklist by canonical name, REST path, MCP tool, or CLI subcommand; use --output markdown for review / handoff-ready Markdown
daemon-reload [--rest-url --api-key]	v1.4.32+: drop cipher cache + v1.4.47 refresh on-disk credentials (remember-login)
daemon-shutdown [--rest-url --api-key]	v1.4.32+: request graceful daemon shutdown; systemd / Docker decides restart

3401+ proto-json commands

The read-only 3401+ family, including earnings-calendar, macro-indicator-*, fed-watch-*, dividend-*, economic-calendar, *-rank, hot-list, heat-map-data, institution-*, ark-*, industrial-*, rating-change, and rise-fall-distribution, uses --c2s-json to pass generated-proto C2S JSON through to the gateway.

These commands keep strict proto-json behavior: field names use the Rust generated proto snake_case form, and market is a numeric Qot_Common.QotMarket enum. String aliases such as "US" or "HK" are not accepted. Common values:

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

Minimal examples (the full list is shipped as 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}'

If the input uses {"market":"US"}, CLI fails closed and points to the numeric enum form, for example {"market":11}.

Do not guess ids for institution, industrial-chain, or plate detail endpoints. Run the discovery endpoint first, then pass the returned id to the detail endpoint:

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

futucli institution-profile \
  --c2s-json '{"market":11,"institution_id":<institution_id from previous output>}'

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

futucli industrial-chain-detail \
  --c2s-json '{"chain_id":<chain_id from previous output>}'

Release packages also include a read-only live smoke:

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

The script verifies list -> extract id -> detail so release checks and bug reports can prove that institution_id, chain_id, and plate_id discovery still work. If the backend returns ret=-1 or discovery is empty, errors carry qot3401.* diagnostic keys and ask for market, C2S JSON, daemon logs, and the smoke output.

static-status reads the daemon /api/admin/status payload and explains whether the static-security cache is ready for quote/static parity checks. Key fields:

• ready: true when the first stock-list sync has finished, reached zero-delta convergence, and has usable security rows.
• reason / action: stable diagnostic text explaining why the cache is not ready yet and whether to wait, run static-warmup, or include counters in a bug report.
• security_count: number of static security rows currently held in memory.
• stock_list_readiness: summarized bucket such as empty, bootstrap_only, sync_in_progress, recoverable_retrying, first_sync_ready, or converged.
• stock_list_*_total: started, finished, failed, recoverable retry, and zero-delta counters for stock-list sync.
• findings: human-readable diagnostics; doctor also folds these static-data states into a static-data finding. When the cache is still warming or retrying, wait for stock_list_readiness=converged before comparing static row counts or checksums.

doctor --symbol <MARKET.CODE> also queries market-state and quote-capability for that security. market-state helps distinguish closed, lunch-break, pre/post market, and active-session no-push cases. quote-capability folds orderbook, snapshot, basic quote, and related permission decisions into doctor findings with reason / action. For markets such as JP, if quote permission is missing, open the corresponding market quote permission in the official Futu/moomoo App, then recheck with futucli quote-rights and futucli quote-capability <SYMBOL>.

Some user-facing hints include [diag:<key>], for example [diag:quote.permission.open_market]. The key is a stable diagnostic code that lets CLI, REST, MCP, and log evidence point to the same troubleshooting action. It is not a backend error code, and wording/localization changes should not change the key.

K-line naming note: CLI users should call the kline subcommand; REST uses /api/history-kline, and MCP uses futu_get_history_kline. There is no CLI history-kline subcommand.

Diagnostics note: trade-check never calls place-order. In the default table output it executes two read-only steps, static-info and max-qtys. In json/jsonl output it only returns the preflight plan so scripts can inspect parameters first.