Webull CLI
A command-line trading tool for AI agents, quantitative developers, and individual developers. It provides structured access to US stock and ETF market data, stock trading, account information, and order management.
Source code: webull-inc/webull-openapi-cli
What is Webull CLI
Webull CLI (webull) is a single-binary Go application that exposes Webull OpenAPI through a consistent command-line interface. It signs REST requests with App Key and App Secret credentials, sends them to Webull OpenAPI, and writes structured results to standard output.
The CLI is suitable for interactive use, shell scripts, CI jobs, quantitative workflows, and AI coding assistants that can execute terminal commands.
Capabilities
| Area | Available capabilities |
|---|---|
| Products | US stocks and ETFs |
| Trading | Preview, place, replace, cancel, and query stock orders |
| Market data | Snapshot, historical bars, batch bars, quotes, tick data, and footprint data |
| Accounts | Account list, balance, buying power, cash, and positions |
| Instruments | Stock and ETF instrument lookup |
| Automation | JSON output, CSV export, structured errors, and explicit exit codes |
The market data and trading scope follows the current Trading API overview and Market Data API overview.
Architecture Overview
Prerequisites
- App Key and App Secret obtained through the OpenAPI application process
- Webull App access when 2FA approval is required
- An active OpenAPI market data subscription for real-time and historical US stock/ETF data. Note that subscriptions purchased through the Webull App or desktop platform are separate and do not cover OpenAPI access
- Go 1.26.2 or later when installing from source (pre-built binaries do not require Go)
Installation
Pre-built Binary
Download the binary for your platform from GitHub Releases, extract it, and add it to your PATH.
Go Install
go install github.com/webull-inc/webull-openapi-cli/cmd/webull@latest
export PATH="$PATH:$(go env GOPATH)/bin"
Build from Source
git clone https://github.com/webull-inc/webull-openapi-cli.git
cd webull-openapi-cli
go build ./cmd/webull/
Verify the installation:
webull version
Setup
1. Authenticate
webull auth login --region sg
Enter the App Key and App Secret when prompted. If 2FA is enabled, approve the request in the Webull App. Sensitive credentials and tokens are stored in the operating system keychain; non-sensitive profile settings are stored in the local profile configuration.
For UAT, provide the assigned API endpoint explicitly:
webull auth login --region sg --env uat \
--api-endpoint <uat-api-host> \
--name uat
2. Verify Configuration
webull auth status
webull doctor
3. Verify Account Access
webull account list
Use the returned account ID with account and order commands.
Usage Examples
Market Data
# Real-time snapshots for one or more symbols
webull data stock snapshot --symbol AAPL,TSLA --category US_STOCK
# Daily bars for a single symbol
webull data stock bars --symbol AAPL --category US_STOCK \
--timespan D --count 200
# Batch bars for multiple symbols
webull data stock batch-bars --symbol AAPL,TSLA --category US_STOCK \
--timespan M5 --count 100
# Bid/ask order book
webull data stock quotes --symbol AAPL --category US_STOCK --depth 10
# Tick-by-tick trades
webull data stock tick --symbol AAPL --category US_STOCK --count 100
# Order-flow footprint
webull data stock footprint --symbol AAPL --category US_STOCK \
--timespan M1 --count 200
Stock snapshots can request extended-hours and overnight information:
webull data stock snapshot --symbol AAPL --category US_STOCK \
--extend-hour --overnight
Supported bar intervals include minute, hourly, daily, weekly, monthly, and yearly granularities. Exact availability depends on the endpoint and the account's market data permissions.
Stock Trading
Preview an order before submission:
webull order stock preview --account-id <account-id> --symbol AAPL \
--side BUY --qty 10 --type LIMIT --limit-price 185.00 \
--market US --time-in-force DAY
Place a limit order:
webull order stock submit --account-id <account-id> --symbol AAPL \
--side BUY --qty 10 --type LIMIT --limit-price 185.00 \
--market US --time-in-force DAY
The current stock order workflow supports:
- Order types:
MARKET,LIMIT,STOP_LOSS, andSTOP_LOSS_LIMIT - Time in force:
DAYandGTC - Trading sessions:
CORE,ALL,NIGHT, andALL_DAY - Quantity-based orders with optional custom client order IDs
- Interactive confirmation before order submission (skip with
-y) - Dry-run output for inspecting a stock order request without sending it
Dry-run example:
webull order stock submit --account-id <account-id> --symbol AAPL \
--side BUY --qty 10 --type LIMIT --limit-price 185.00 \
--market US --dry-run
Order Management
# View open orders
webull order open --account-id <account-id>
# View one order
webull order detail --account-id <account-id> \
--client-order-id cli_stock_123456
# Query order history
webull order history --account-id <account-id> \
--start 2026-01-01 --end 2026-01-31
# Replace an open order
webull order stock replace --account-id <account-id> \
--client-order-id cli_stock_123456 --limit-price 190.00
# Cancel an order
webull order cancel --account-id <account-id> \
--client-order-id cli_stock_123456
Open orders and history support cursor-based pagination.
Account Information
webull account list
webull account balance --account-id <account-id>
webull account positions --account-id <account-id>
Instrument Lookup
webull instrument stock --symbol AAPL,TSLA \
--category US_STOCK --page-size 100
Instrument lookup can filter by symbol and trading status and supports cursor-based pagination.
Available Commands
Trading and Orders
| Command | Description |
|---|---|
order stock preview | Estimate a stock order before submission |
order stock submit | Place a stock order |
order stock replace | Modify an existing open stock order |
order cancel | Cancel an open or pending order |
order open | List current open orders |
order detail | Retrieve details for one order |
order history | Query historical orders |
Market Data
| Command | Description |
|---|---|
data stock snapshot | Retrieve real-time stock/ETF snapshots |
data stock bars | Retrieve OHLCV bars for one symbol |
data stock batch-bars | Retrieve OHLCV bars for multiple symbols |
data stock quotes | Retrieve bid/ask depth data |
data stock tick | Retrieve tick-by-tick trades |
data stock footprint | Retrieve order-flow and volume-profile data |
Accounts and Instruments
| Command | Description |
|---|---|
account list | List trading accounts |
account balance | Retrieve equity, buying power, cash, and P&L information |
account positions | Retrieve current positions |
instrument stock | Query stock and ETF instruments |
Authentication, Profiles, and Utilities
| Command | Description |
|---|---|
auth login | Authenticate with App Key, App Secret, and optional 2FA |
auth status | Show the active authentication status |
profile list | List configured profiles |
profile switch <name> | Change the active profile |
profile logout [name] | Remove a profile and its stored credentials |
profile set-endpoint | Set a custom API endpoint for the active profile |
doctor | Diagnose profile, credentials, endpoint, and environment settings |
version | Print version and build information |
Run any command with --help to inspect its complete flags:
webull order stock submit --help
webull data stock bars --help
Output and Automation
JSON is the default output format. API data is written to stdout so scripts and agents can consume it directly:
webull account positions --account-id <account-id>
Use --csv for commands that support tabular export:
webull account positions --account-id <account-id> --csv
webull data stock bars --symbol AAPL --category US_STOCK --csv
Errors are written to stderr as JSON where possible and include an error_code and message. The process exits with code 0 on success and 1 on error.
Credentials can be supplied through environment variables after a profile has been configured:
export WEBULL_APP_KEY=<your-app-key>
export WEBULL_APP_SECRET=<your-app-secret>
webull account list
Global Flags
| Flag | Description |
|---|---|
--profile | Select a configured profile by name |
--region | Override the profile's region |
--env | Select prod or uat |
--csv | Request CSV output where supported |
-q, --quiet | Suppress non-data output and confirmation prompts |
--verbose | Write request summaries to stderr |
--debug | Write full request/response diagnostics to stderr |
--timeout | Set the HTTP timeout in seconds; default is 30 |
-y, --yes | Skip confirmation prompts |
Security and Safety
- Never paste an App Key, App Secret, or token into chat, source code, or command history.
- Use
order stock previewto review estimated order details before submission. - Use
--dry-runto inspect the generated stock order request without sending it. - Stock submit, replace, and cancel operations prompt for confirmation by default.
--yesand--quietbypass confirmation prompts. Use them only in controlled automation after validating all order parameters.- Use separate named profiles for production and UAT.
- Real-time and historical data availability depends on OpenAPI market data permissions. See the market data getting-started guide.
Disclosure
Trading securities involves risk of loss. Verify the account, symbol, side, quantity, order type, price, time in force, and trading session before submitting an order. This software is provided as is without warranty and does not provide investment advice.