ibkr-cli

A local-first CLI for Interactive Brokers built on top of ib_async, Typer, and Rich.

Use with AI agents

If you use Claude Code, OpenClaw, or other AI agents that support the skills ecosystem, you can install the ibkr-cli skill to let your agent handle the entire setup and trading workflow for you:

npx skills add uu-z/ibkr-cli-fork

Once installed, simply tell your agent what you want to do (e.g., "help me install ibkr-cli and check my IBKR account") and it will guide you through everything — from installing IB Gateway to placing your first trade.

Features

Gateway-first local connection management with Docker lifecycle commands
Auto-generated live and paper profiles from ibkr gateway up
Connectivity checks for TCP reachability and IBKR API handshake
Account queries for summary and positions
Order queries for open, completed, and executions
Safe stock order preview via IBKR what-if orders
Real stock order submission with explicit --submit
Order types: market, limit, stop, stop-limit, trailing stop, and bracket (take-profit + stop-loss)
Open order cancellation by order ID
Order modification (price, quantity, type, etc.) without cancel-and-resubmit
Market data snapshot quotes with live-to-delayed fallback
Finite quote watch mode for repeated quote updates
Historical bar retrieval
News headlines and article retrieval
Options chain lookup with expirations, strikes, and greeks
Market scanner for screening stocks by various criteria
Company fundamentals: snapshot, financial summary, full financials, ownership (requires Reuters Fundamentals subscription)
Historical trade records, P&L by symbol, fund transfers, dividends and cash transactions (via Flex Queries)
CLI configuration management (ibkr config set/show/path)
Automatic update check with ibkr update

Requirements

Python 3.10+
Either Docker or a local TWS / IB Gateway installation
Market data subscriptions as required by your IBKR account

Installation

Install from PyPI with pipx so the ibkr command is isolated from your main Python environment:

pipx install ibkr-cli

If you prefer to install into the current Python environment:

python -m pip install ibkr-cli

After installation:

ibkr --help
ibkr --version

Quick start

1. Preferred path: start a managed Gateway

Bring up a dedicated IB Gateway container and auto-create its profiles:

ibkr gateway up ib-a --userid YOUR_IBKR_USER --password YOUR_IBKR_PASSWORD --vnc-password dev --default

This creates:

ib-a-live -> 127.0.0.1:4001
ib-a-paper -> 127.0.0.1:4002

and stores the Gateway metadata plus generated profiles in the normal ibkr config file.

Inspect Gateway status:

ibkr gateway ps
ibkr gateway doctor ib-a
ibkr gateway logs ib-a --tail 100

2. Fallback path: use local TWS or IB Gateway

If Docker is not installed, you can still use the CLI with a local desktop app.

Built-in local profiles:

paper -> 127.0.0.1:7497 for TWS paper
live -> 127.0.0.1:7496 for TWS live
gateway-paper -> 127.0.0.1:4002 for IB Gateway paper
gateway-live -> 127.0.0.1:4001 for IB Gateway live

Start TWS or IB Gateway, enable API socket access, then test a built-in profile:

ibkr connect test --profile paper
ibkr connect test --profile gateway-paper

3. Inspect configuration

The CLI keeps profiles and gateway metadata in a config file. To see where it is located:

ibkr config path

The built-in fallback profiles are still available:

paper -> 127.0.0.1:7497
live -> 127.0.0.1:7496
gateway-paper -> 127.0.0.1:4002
gateway-live -> 127.0.0.1:4001

You can still edit the config file directly or reset it to defaults with ibkr profile init --force, but the recommended path is to create managed profiles through ibkr gateway up.

Inspect available profiles

ibkr profile list
ibkr profile show ib-a-paper
ibkr profile show ib-a-live

Check connectivity

ibkr doctor --profile ib-a-paper
ibkr connect test --profile ib-a-paper

Core commands

Account and positions

ibkr account summary --profile ib-a-paper
ibkr positions --profile ib-a-paper

Orders

ibkr orders open --profile ib-a-paper
ibkr orders completed --profile ib-a-paper
ibkr orders executions --profile ib-a-paper
ibkr orders cancel 12345 --profile ib-a-paper
ibkr orders modify 12345 --limit 150.50 --profile ib-a-paper

Trading

Preview first:

ibkr buy AAPL 10 --preview --profile ib-a-live
ibkr sell AAPL 10 --preview --profile ib-a-live

Submit only when you explicitly intend to place an order:

ibkr buy AAPL 10 --submit --profile ib-a-live
ibkr sell AAPL 10 --submit --profile ib-a-live

Order types

Limit order:

ibkr buy AAPL 10 --type LMT --limit 150.00 --preview --profile ib-a-live

Stop order:

ibkr sell AAPL 10 --type STP --stop 140.00 --preview --profile ib-a-live

Stop-limit order:

ibkr sell AAPL 10 --type "STP LMT" --stop 140.00 --limit 139.50 --preview --profile ib-a-live

Trailing stop (by dollar amount or percentage):

ibkr sell AAPL 10 --type TRAIL --trail-amount 2.00 --preview --profile ib-a-live
ibkr sell AAPL 10 --type TRAIL --trail-percent 5 --preview --profile ib-a-live

Bracket order (take-profit + stop-loss):

ibkr buy AAPL 10 --take-profit 160.00 --stop-loss 140.00 --preview --profile ib-a-live
ibkr buy AAPL 10 --type LMT --limit 150.00 --take-profit 160.00 --stop-loss 140.00 --preview --profile ib-a-live

Update

The CLI automatically checks for new versions once a day. To manually check and upgrade:

ibkr update

Market data

Snapshot quote:

ibkr quote AAPL --profile ib-a-paper
ibkr quote AAPL --profile ib-a-paper --json

Finite quote watch:

ibkr quote AAPL --watch --updates 5 --interval 2 --profile ib-a-paper

Historical bars:

ibkr bars AAPL --profile ib-a-paper
ibkr bars AAPL --profile ib-a-paper --duration "1 D" --bar-size "5 mins" --json

News

List available news providers:

ibkr news providers --profile gateway-paper

Fetch headlines for a symbol:

ibkr news headlines AAPL --profile gateway-paper
ibkr news headlines AAPL --limit 20 --providers "BRFG,DJNL" --profile gateway-paper
ibkr news headlines AAPL --start "20260101 00:00:00" --end "20260318 00:00:00" --profile gateway-paper

Read a full article (using provider code and article ID from the headlines output):

ibkr news article BRFG "BRFG$12345" --profile gateway-paper

Options

List available option chains (expirations and strikes) for a symbol:

ibkr options chain AAPL --profile gateway-paper

Fetch option quotes with greeks for a specific expiration (auto-selects strikes near the money):

ibkr options quotes AAPL 20260320 --profile gateway-paper

Filter by call/put and specific strikes:

ibkr options quotes AAPL 20260320 --right C --profile gateway-paper
ibkr options quotes AAPL 20260320 --strike 150 --strike 155 --strike 160 --profile gateway-paper

Scanner

List available scan codes, instruments, or locations:

ibkr scanner params codes --profile gateway-paper
ibkr scanner params instruments --profile gateway-paper
ibkr scanner params locations --profile gateway-paper

Run a market scan:

ibkr scanner run TOP_PERC_GAIN --profile gateway-paper
ibkr scanner run MOST_ACTIVE --limit 10 --profile gateway-paper
ibkr scanner run HOT_BY_VOLUME --above-price 10 --below-price 100 --above-volume 1000000 --profile gateway-paper
ibkr scanner run HIGH_DIVIDEND_YIELD --market-cap-above 1000000000 --profile gateway-paper

Fundamentals

Note: Fundamentals commands require a Reuters Fundamentals subscription (~$7/month). Subscribe via IBKR Account Management > Settings > Market Data Subscriptions (search for "Reuters Fundamentals" or "LSEG").

Company snapshot (overview, ratios, officers, forecasts):

ibkr fundamentals snapshot AAPL --profile gateway-live

Financial summary (key metrics across periods):

ibkr fundamentals summary AAPL --profile gateway-live

Full financial statements (income, balance sheet, cash flow):

ibkr fundamentals financials AAPL --profile gateway-live

Ownership structure (institutional and insider holders):

ibkr fundamentals ownership AAPL --profile gateway-live

Historical data (Flex Queries)

These commands fetch historical account data via IBKR Flex Queries over HTTPS. They do not require IB Gateway or TWS to be running, but data may be delayed up to T-1.

Setup:

# Token: Account Management > Settings > FlexWeb Service
ibkr config set flex.token YOUR_TOKEN

# Query ID: Account Management > Reports > Flex Queries
ibkr config set flex.query_id YOUR_QUERY_ID

Trade history:

ibkr trades
ibkr trades --days 7
ibkr trades --days 90 --json

P&L by symbol (realized + unrealized):

ibkr pnl
ibkr pnl --days 90

Fund deposits, withdrawals, and transfers:

ibkr transfers
ibkr transfers --days 180

Dividends, interest, withholding tax, and other cash transactions:

ibkr dividends
ibkr dividends --days 90

Configuration

ibkr config show               # View current config (token is masked)
ibkr config set <key> <value>  # Set a value (e.g. flex.token, flex.query_id, default_profile)
ibkr config path               # Show config file location

JSON output

Most read and trading commands support --json for machine-readable output.

Examples:

ibkr quote AAPL --profile gateway-paper --json
ibkr orders completed --profile gateway-paper --json
ibkr buy AAPL 10 --preview --profile gateway-paper --json

Error JSON shape

When a command fails in --json mode, the CLI returns a structured error payload and exits with a non-zero process code.

Shape:

{
  "ok": false,
  "error": {
    "code": "invalid_arguments",
    "message": "Choose exactly one of --preview or --submit.",
    "exit_code": 2,
    "details": {
      "preview": false,
      "submit": false
    }
  }
}

Current error code families include:

invalid_arguments
config_load_failed
config_already_exists
unknown_profile
connectivity_check_failed
account_query_failed
order_query_failed
order_operation_failed
market_data_request_failed
news_request_failed
options_request_failed
scanner_request_failed
fundamentals_request_failed
flex_request_failed

Operational notes

Prefer paper trading first

Use gateway-paper or paper while validating commands that submit or cancel real orders.

Submit is explicit

buy and sell require exactly one of:

--preview
--submit

This prevents accidental live order placement from a default command path.

Run same-profile validations serially

If multiple CLI processes connect to the same TWS or IB Gateway profile with the same fixed client_id, IBKR can reject or interfere with the second connection.

For validation and manual testing, prefer running commands sequentially per profile unless you intentionally assign unique client IDs.

Market data fallback

quote automatically falls back from live market data to delayed market data when live prices are unavailable.

Command name conflicts

This package installs the command ibkr.

If your machine already has another CLI exposing the same command name, uninstall the old tool or adjust your PATH so that this package's ibkr entrypoint is the one your shell resolves first.

Development

Install in editable mode:

python -m pip install -e .

Install in editable mode with optional test dependencies:

python -m pip install -e ".[test]"

Run directly from source if needed:

python -m ibkr_cli.app --help

Run the offline test suite:

python -m unittest discover -s tests -v

The packaged entrypoint for installed users is:

ibkr --help

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
scripts		scripts
skills/ibkr-cli		skills/ibkr-cli
src/ibkr_cli		src/ibkr_cli
tests		tests
.clawhubignore		.clawhubignore
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

ibkr-cli

Use with AI agents

Features

Requirements

Installation

Quick start

1. Preferred path: start a managed Gateway

2. Fallback path: use local TWS or IB Gateway

3. Inspect configuration

Inspect available profiles

Check connectivity

Core commands

Account and positions

Orders

Trading

Order types

Update

Market data

News

Options

Scanner

Fundamentals

Historical data (Flex Queries)

Configuration

JSON output

Error JSON shape

Operational notes

Prefer paper trading first

Submit is explicit

Run same-profile validations serially

Market data fallback

Command name conflicts

Development

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages