ibkr-cli 0.1.1

A local-first CLI for Interactive Brokers

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 fatwang2/ibkr-cli

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

• Profile-based local connection management for TWS and IB Gateway
• 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
• Open order cancellation by order ID
• Market data snapshot quotes with live-to-delayed fallback
• Finite quote watch mode for repeated quote updates
• Historical bar retrieval

Requirements

• Python 3.10+
• A running TWS or IB Gateway session
• 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

Initialize local config

ibkr profile init

This creates a config file under the path returned by:

ibkr config-path

The default generated profiles are:

• 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

Inspect available profiles

ibkr profile list
ibkr profile show gateway-paper

Check connectivity

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

Core commands

Account and positions

ibkr account summary --profile gateway-paper
ibkr positions --profile gateway-paper

Orders

ibkr orders open --profile gateway-paper
ibkr orders completed --profile gateway-paper
ibkr orders executions --profile gateway-paper
ibkr orders cancel 12345 --profile gateway-paper

Trading

Preview first:

ibkr buy AAPL 10 --preview --profile gateway-paper
ibkr sell AAPL 10 --preview --profile gateway-paper

Submit only when you explicitly intend to place an order:

ibkr buy AAPL 10 --submit --profile gateway-paper
ibkr sell AAPL 10 --submit --profile gateway-paper

Market data

Snapshot quote:

ibkr quote AAPL --profile gateway-paper
ibkr quote AAPL --profile gateway-paper --json

Finite quote watch:

ibkr quote AAPL --watch --updates 5 --interval 2 --profile gateway-paper

Historical bars:

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

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

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