Scripts & AI tools

Call the CLI from AI tools with terminal access, or read structured results in a script. This guide covers prompts, command calls, and JSON handling.

Complete Installation & sign-in before using this guide. This page covers terminal command calls; the current CLI has no ACP or MCP server startup command.

Ask AI to run a query

Give this prompt to an AI tool with terminal access:

Use Futu CLI to get quotes for Apple and NVIDIA in JSON format.
Summarize symbols, prices, percentage changes, and available data timestamps,
and identify the trading session. If authorization has expired, permissions
are missing, or data is incomplete, explain the issue without inventing data.

The AI tool can run:

futu quote US.AAPL US.NVDA --format json

A successful call returns quote data for the AI tool to summarize. For quote, calculate percentage change from last_price and prev_close_price. Do not calculate it when the previous close is missing or zero. Mark timestamps or timeliness information as unavailable when absent from the response.

Read JSON in a script

Most business commands print tables by default. Use --format json (or -f json) for JSON. This Bash example requires jq and saves the result and diagnostic text separately. Check CLI success before parsing:

if futu quote US.AAPL US.NVDA --format json > quotes.json 2> quotes.stderr.log; then
  jq -e 'type == "array"' quotes.json > /dev/null &&
    jq '.[] | {code, last_price, prev_close_price}' quotes.json
else
  futu_status=$?
  cat quotes.stderr.log >&2
  exit "$futu_status"
fi

This excerpt illustrates the quote structure with sample values:

[
  {
    "code": "US.AAPL",
    "last_price": 180,
    "prev_close_price": 178,
    "suspension": false
  }
]

JSON output conventions

Case	Current behavior and handling
Successful response	Structure varies by command. quote returns an array; some queries include data, pagination, or skipped fields when pagination or skipped-item information is present. Inspect the actual structure
Missing fields	Numeric zeros, empty strings, nulls, empty arrays, and empty objects are omitted from objects; false is retained. A missing field may be an omitted zero or data the API did not provide. Do not replace all missing fields with zero
Command failure	Commands that return errors use nonzero exit codes; error descriptions may be written to stderr. Do not assume errors are JSON
Partial results	Even after a successful exit, check returned symbols, pagination, and skipped information. The exit code alone does not establish completeness
Text output exceptions	version and update print text. Live securities order cancel also prints text after successful submission, although its preview can be JSON

For pipelines such as futu … | jq …, enable set -o pipefail in Bash to avoid seeing only the last command's exit status. Record futu version to help diagnose output differences between releases.

For failed calls, see Troubleshooting. For trade previews, confirmation, and order status, see Accounts & live trading.