Installation & sign-in

Install the CLI, authorize your account, and verify your first query. Supports macOS, Linux, Windows, and SSH sessions.

Installation

The macOS, Linux, and Windows installation scripts below require OpenSSL to verify release signatures. On Windows, ensure openssl is on your PATH.

macOS / Linux

The recommended installation script does not require Node.js:

curl -fsSL https://raw.githubusercontent.com/FutunnOpen/futu-cli/main/scripts/install.sh | sh

Supports x86_64 and ARM64 on macOS and Linux. The script selects the release archive, verifies its signature and checksum, and installs the executable to ~/.futu/bin.

After installation, open a new terminal and check the version:

futu version

If the current terminal cannot find futu, add its directory to PATH for this session:

export PATH="$HOME/.futu/bin:$PATH"
futu version

The script adds PATH to supported shell configuration files. Fish users need to configure this path themselves.

Windows

Run in PowerShell:

iwr -UseBasicParsing https://raw.githubusercontent.com/FutunnOpen/futu-cli/main/scripts/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1

The current release supports Windows x86_64. The script installs to %LOCALAPPDATA%\FutuCLI\bin and adds it to the user PATH. Open a new terminal, then run:

futu version

npm

Requires Node.js 18 or later, npm 9 or later, and access to GitHub. Install from GitHub:

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

--install-links=true tells npm to copy the packaged files instead of linking to a temporary Git checkout.

@futunn/futu-cli is not currently published to the npm registry. Use the GitHub command above. The npm wrapper downloads the CLI binary for your platform.

Initialize and sign in

For first-time setup, run:

futu config init

This initializes the configuration and starts OAuth sign-in:

1. The CLI registers the required OAuth client and opens the browser authorization page.
2. Sign in to your Futu account and review the requested authorization.
3. After authorization, a local callback returns control to the CLI, which saves the token.

Subsequent commands reuse the token and attempt to refresh it when it expires. Sign in again if refresh fails.

The default configuration file is ~/.futu/config.json; the default token file is ~/.futu/token.json. To use another token file, set token_file or pass the global --token-file option.

auth login

Start sign-in separately, or authorize again after your session expires:

futu auth login

An existing valid token is reused. Set the authorization client's display name with --client-name:

futu auth login --client-name "My Research Agent"

Changing this option does not trigger authorization when a valid token already exists. To authorize again with a new name, run futu auth logout first.

SSH or headless environments

In SSH or headless environments, you can run the following command for first-time setup. The CLI creates the default configuration and registers the required OAuth client; futu config init is not needed first:

futu auth login --no-browser

--no-browser prints the authorization URL without opening a browser automatically.

Open the printed URL in an available browser and authorize access. If that browser cannot reach the local callback port on the machine running the CLI, copy the complete callback URL from the browser address bar, paste it into the waiting terminal, and press Enter.

TIP

A browser is still required to authorize access. Paste the complete callback URL into the terminal only when the automatic callback cannot complete.

auth status

Inspect the locally stored token's status, expiration, account information, and permissions:

futu auth status
futu auth status --format json

This reads local state. It does not verify current permissions for every business API.

auth logout

Delete the locally saved OAuth token:

futu auth logout

Sign in again before the next command that requires authentication. This clears only the local token; it does not send a server-side authorization revocation request.

Run your first query

Query a stock to confirm access to the quote API:

futu quote US.AAPL

A successful query displays the symbol, trading session, price, and change. These values are illustrative, not live market data:

Code	Session	Last	Change%
US.AAPL	REGULAR	180.000	+1.12%

Data for the requested symbol confirms this query worked. Timeliness and available markets depend on account permissions; verify other APIs separately. See Market data for fields and trading sessions, or Troubleshooting if the query fails.

Connection checks

futu check
futu check --format json

check inspects the local token and cached permissions, attempts token refresh if needed, and measures HTTP connectivity and latency to the API address.

WARNING

The exit status of check alone does not establish API connectivity: it may exit with 0 when the token is valid even if the API is unreachable. Scripts should also inspect connectivity.api.ok in the JSON. HTTP reachability does not establish authorization for a specific business API.

For connectivity or permission issues, see Authorization and connectivity.

Configuration

# List configuration
futu config list

# Read a configuration value
futu config get default_account

# Set the default securities account
futu config set default_account "YOUR_ACCOUNT_ID"

Common settings:

Setting	Description
api_base	REST API address; defaults to https://webapi.futunn.com
client_id	OAuth client ID registered by the sign-in flow
redirect_uri	Local OAuth callback address configured by the sign-in flow
token_file	OAuth token file path
default_account	Default securities trading account ID
auto_update	Whether to check for updates and show prompts automatically; enabled by default

Normally, keep the default API address and let the sign-in flow manage the client and callback settings.