Help & updates

Troubleshoot installation, authorization, data, and trading calls. Find CLI updates, shell completion, and request diagnostics here.

Troubleshooting

Find the stage where the issue occurs, then follow the linked instructions.

Installation and command discovery

Message or issue	Resolution
futu: command not found	Open a new terminal and check that the installation directory is on PATH
openssl is required to verify the release signature	Install OpenSSL and ensure openssl runs in your terminal
npm reports spawn sh ENOENT	On macOS / Linux, run npm config set script-shell /bin/sh and retry
npm reports uv_cwd or getcwd	Run cd ~, then install again from a valid directory
Command not found after installation with nvm	Check that node and npm come from the same Node.js installation and inspect the global installation path
Works in the terminal, but the AI tool cannot find it	Check where the AI tool actually executes commands and confirm the executable path; desktop apps may not inherit the terminal PATH

Find the executable with command -v futu on macOS / Linux or (Get-Command futu).Source in PowerShell. Use the full path in the AI tool if needed. Remote servers and containers need installation and sign-in in their own environments.

Authorization and connectivity

Issue	Next step
Missing client_id, not signed in, or token refresh fails	Follow Initialize and sign in for first-time setup; with an existing configuration, sign in again
Signed in, but connectivity.api.ok is false	Check the network, proxy, and API address; inspect the Connection checks result
HTTP is reachable, but a business query fails	Inspect the API error and the account's API and market permissions; local sign-in status does not establish all business permissions
Authorization callback fails in a headless environment	Follow the SSH sign-in instructions for the local callback or pasting the complete callback URL

Data and scripts

Issue	Next step
JSON parsing fails or error text appears in the result	Check the exit code first and handle stdout and stderr separately; see Read JSON in a script
Fields are missing, zeros are omitted, or results are incomplete	Check zero omission, skipped, and pagination in JSON output conventions; do not fill every missing value with zero
Only part of the historical data is returned	Follow Historical candlesticks and pagination, checking the date range and cursor
A stock screen returns no results	Inspect the conditions and response structure; see Run a stock screen

Trading calls

Issue	Next step
A preview was returned, but no order appears	A preview is not a submission; follow Preview and submit a trade
A trading command waits for y/n input	The broker may require additional confirmation; pass the prompt to the user and follow the confirmation workflow
Submission succeeded, but the order is absent from open orders	Check order details and history for the final status; successful submission does not mean a fill

Command help

futu --help
futu order buy --help
futu stock-screen --help

Update the CLI

Check the installed version first:

futu version

For a CLI installed with the script, check for and install the latest stable release:

futu update --check
futu update

futu update verifies the downloaded archive's signature and checksum. auto_update controls automatic checks and prompts; installation requires running futu update.

For a GitHub npm installation, rerun the installation command to update:

npm install -g github:FutunnOpen/futu-cli --install-links=true

Shell completion

Load command completion for your current shell session:

Bash:

source <(futu completion bash)

Zsh:

source <(futu completion zsh)

Fish:

futu completion fish | source

PowerShell:

futu completion powershell | Out-String | Invoke-Expression

Run futu completion --help for persistent completion setup.

Request diagnostics

The CLI reports API-call diagnostics to https://ai-report.futunn.com to help investigate failed or slow requests. Reports include the command name, API path, status code, duration, CLI version, platform, agent name, and processed requests and responses.

Token, password, and key fields are redacted. Securities trading, account, and crypto trading payloads are masked. Other requests, including market-data requests, retain the remaining business fields. Reporting uses the same OAuth access token to identify the current session. The current version has no setting to disable reporting.