CLI flags¶
Full flag list. You can also run --help on each binary:
futu-opend¶
| Flag | Default | Description |
|---|---|---|
--login-account <id> |
— | Futu account (one of account/pwd is required) |
--login-pwd <pwd> |
— | Plain-text login password (prints a deprecation WARN; prefer --login-pwd-file) |
--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 |
--rest-tls-cert <path> |
— | REST TLS certificate PEM; required with --rest-keys-file |
--rest-tls-key <path> |
— | REST TLS private-key PEM; required with --rest-keys-file |
--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 chs/cht/en; when unset: OS preferred UI language → POSIX locale → 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.5.3+: 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.5.3+: reconnect monitor refreshes client_sig after repeated TCP login failures; default off; TOML field and compatibility env are also supported |
--enable-v18-kline-patterns |
false | v1.8: enable Desktop K-line pattern reads (9000/9001/9003/9005); evidence is source-aligned + local-green and live backend behavior remains unverified |
--enable-v18-kline-pattern-performance |
false | v1.8: independently enable pattern-performance reads (9004); the pinned Desktop source has no business caller, so this remains default-off and requires an explicit success status |
--enable-moc-order |
false | v1.8: enable the guarded MOC write path; real US common stock only. Existing trade authorization/live-trading/unlock gates and a stable idempotency key still apply. Keep OFF until authorized live verification |
--enable-v18-stock-notes |
false | v1.8: enable private stock-note reads, the last-good cache, and multi-device push; API-key mode is required and callers need acc:read |
--enable-v18-stock-note-writes |
false | v1.8: independently enable stock-note create/update/delete; the read flag and qot:write are also required, and each request is sent once without automatic retry |
--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) |
Configuring --rest-keys-file enables REST scope mode and requires both
--rest-tls-cert and --rest-tls-key. The daemon validates the certificate
and private key before broker login. Use https:// for authenticated REST and
wss:// for /ws on the same listener. Legacy no-key compatibility may
continue to use HTTP/WS.
futucli place-order --order-type MOC requires --idempotency-key (or explicit FUTU_CLI_AUTO_IDEM=1) and must omit --price / --stop-price; the daemon must also enable --enable-moc-order.
Extended features¶
| Flag | Default | Description |
|---|---|---|
--extended-data-reads [BOOL] |
true |
Extended market, research and account reads; original permissions and live validation boundaries still apply |
--extended-data-writes [BOOL] |
true |
User settings, reminders, cloud data and explicit forex authentication; original permissions still apply |
--kline-patterns [BOOL] |
true |
K-line pattern reads; live backend validation remains pending |
--kline-pattern-performance [BOOL] |
true |
Pattern performance reads; live backend validation remains pending |
--stock-notes [BOOL] |
true |
Private stock note reads and pushes; requires an API key |
--stock-note-writes [BOOL] |
true |
Create, update and delete private stock notes; requires reads and qot:write |
These options default to ON. Pass false to disable; omitting the value means true. API-key permissions still apply.
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, news, watchlist, alerts.
Without filters, futucli commands lists every command with its category. futucli --help
lists root commands; futucli <command> --help shows all parameters for that command.
| Group | Contents |
|---|---|
common |
Connectivity, command catalog, REPL |
quote |
Quotes, subscriptions, screening, option data, indicators and K-line patterns |
account |
Accounts, funds, positions, order/fill queries, fee estimates and account pushes |
trade |
Trade unlock and write operations such as placing, modifying and cancelling orders |
news |
News, announcements, rating news and news search |
watchlist |
Watchlists and private stock notes |
alerts |
Price reminders and option event alerts |
research |
Company financials, calendars, macroeconomics, institutional holdings and market rankings |
advanced |
Option strategies, strategy analysis and spreads |
key |
Key and password management |
system |
Daemon operations, diagnostics, permission/quota status and read-only trade preflight |
Categories aid discovery. Consult each command's help for permissions, trade confirmation and parameters.
Version update check¶
futucli version only prints the local version and does not access the network:
Add --check when you want to check for a newer release:
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:
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>. Pass either an exact manifest URL or a directory URL ending in / (which appends manifest.json). 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.5.3+: show daemon static-security cache and stock-list sync status |
static-warmup <symbols...> |
v1.5.3+: 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 |
Linux / Windows: save to the OS credential store. Packaged macOS builds reject before reading the secret; use FUTU_TRADE_PWD / --from-stdin |
clear-trade-pwd |
Remove trade password from the OS keychain (v1.4+) |
set-login-pwd --account <id> |
Linux / Windows: save to the OS credential store. Packaged macOS builds reject before reading the secret; use a mode-0600 --login-pwd-file |
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.5.3+: 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.5.3+: 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.5.3+: 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.5.3+: target-stock financial calendar lookup by stock id (mobile/moomoo backend request) |
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.5.3+: 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.5.3+: 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.5.3+: 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.5.3+: print REST / MCP / CLI / Gateway coverage from EndpointSpec; --gaps shows only explicitly non-exposed surfaces and reasons; v1.5.3+ --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 |
Option snapshot JSON fields¶
futucli --output json snapshot <OPTION> and --output jsonl flatten all 22
option snapshot fields into the corresponding row. The core risk fields are
delta, gamma, theta, vega, rho, and implied_volatility. The other
fields are option_type, option_owner, strike_time, strike_price,
contract_size, open_interest, premium, strike_timestamp,
index_option_type, net_open_interest, expiry_date_distance,
contract_nominal_value, owner_lot_multiplier, option_area_type,
contract_multiplier, and contract_size_float.
Optional fields omitted by the server are absent from JSON; present zero values remain present. Non-option rows such as stocks and futures contain none of these option-only keys. The default table and Markdown output keep their compact basic columns instead of expanding all 22 fields.
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}.
Technical indicators¶
indicator-list is the synchronous 3259 query. indicator-calc keeps one raw
connection for the 3260 ACK and matching 3261 result; REST, MCP, and generic
gRPC cannot substitute for that connection-bound flow:
futucli indicator-list \
--c2s-json '{"search_key":"MA","lang_type":0,"search_mode":1}'
futucli indicator-calc --timeout-secs 10 \
--c2s-json '{"short_name":"MA","lang_type":1,"data":{"security":{"market":1,"code":"00700"},"kl_type":2,"k_line":[{"time":"2026-08-01 10:00:00","is_blank":false,"close_price":10}]}}'
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, runstatic-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 asempty,bootstrap_only,sync_in_progress,recoverable_retrying,first_sync_ready, orconverged.stock_list_*_total: started, finished, failed, recoverable retry, and zero-delta counters for stock-list sync.findings: human-readable diagnostics;doctoralso folds these static-data states into astatic-datafinding. When the cache is still warming or retrying, wait forstock_list_readiness=convergedbefore 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.
Since v1.8.4, kline --count N follows all pages in the selected date range, deduplicates by time and returns the latest N candles in ascending order. --page-size or --next-req-key explicitly selects single-page mode, preserving page results and continuation keys. In default mode, a later-page error or cursor cycle fails the request instead of returning partial data as a complete result.
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.
Tape reading: tape-reading-events, tape-reading-statistics, set-tape-reading-subscription use an explicit native --ws-url, caller --api-key, and --c2s-json. Subscription Add watches until Ctrl-C. Contract.
Forex order operations¶
Use caller-preserving --rest-url, --api-key and --c2s-json. See full contracts. All six endpoints are default OFF; writes do not retry automatically.
get-forex-ordersget-forex-order-detailcancel-forex-orderset-forex-position-stopsconfirm-forex-ordermodify-forex-order