icli: IBKR live trade cli

icli is a command line interface for live trading (or sandbox/paper trading) using IBKR accounts.

The intended use case is for scalping or swing trading, so we prioritize easy of understanding your positions and active orders while removing unnecessary steps when placing orders.

Demo Replay

Watch the console replay demo below to see a paper trading account where we add some live quotes for stocks and options, remove quotes, place orders to buy and sell, check execution details to view aggregate commission charges, check outstanding order details, and add some live futures quotes too.

Note: the capture preview is a couple years old at this point and we should make a new one. The interface has improved since then, so try it out from a recent clone and join us here in the future.

Overview

Welcome to icli! You can use icli to manage manual and automated trading using your IBKR account for stocks, futures, currencies, and options.

You can enable audio announcements of trade events if you also run awwdio and provide your awwdio address as an environment variable like ICLI_AWWDIO_URL=http://127.0.0.1:8000 poetry run icli (macOS only currently and you need to manually install the system speech voice packs in system settings).

You can run multiple clients in different terminal windows using unique client ids for each session like ICLI_CLIENT_ID=4 poetry run icli. Note: IBKR restricts orders per-client-id, so for example if you place an order under client id 4, the order will not show up under other clients.

The full features of icli are exposed as individual commands which aren't all documented here in the README. Use the ? command to see all available commands to you at runtime then use cmdname? for documentation per-command.

Some helpful advanced commands only available in icli:

• We have an efficient quote adding system where one command of add SPY240412{P,C}005{1,2,3}0000 will add live quotes for each of: SPY240412C00510000, SPY240412C00520000, SPY240412C00530000, SPY240412P00510000, SPY240412P00520000, SPY240412P00530000.
  • Then if you want to easily remove those quotes, you can run rm SPY240412{P,C}005{1,2,3}0000 too. The syntax also supports range population like add SPXW24041{5..7}{P05135,C05150}000. Each quote also has a row id, and you can remove quotes by row id individually or using replacement syntax: rm :31, rm :{31..37}, rm :{25,27,29} etc.
• You can run multiple purchases concurrently using the expand wrapper like: expand buy {META,MSFT,NVDA,AMD,AAPL} $15_000 MID — that command will buy approximately $15,000 worth of each symbol using current midpoint quote prices.
• You can easily empty your portfolio with evict * -1 0 MID or immediately sell symbols with current market price caps using evict MSFT -1 0 AF etc as well.
  • See expand? and evict? and buy? for more details of how it all works.
• The price format also supports negative prices for shorts or sells, so you can do buy AAPL 100 MID to buy then buy AAPL -100 MID to sell. You can buy and sell by any combination of price and quantity: buy MSFT $10_000 AF, buy MSFT -10 MKT etc.
• The price format also doubles as a share count format if you don't include $, so buy AAPL 100 AF will buy 100 shares of AAPL at the current market price using IBKR's Adaptive Fast order algo type. Price or Quantity values can be positive or negative: buy AAPL 100 AF, buy AAPL $10_000 AF, buy AAPL -20 AF, buy AAPL -$40_000 AF. You can append preview to buy orders to get an estimate of margin impact and other account-based order details too.
• The text buy format also supports exact limit prices and automatic brackets or sells via:
  • buy AAPL 100 AF @ 233.33 — submit buy order for 100 shares but with user-specified limit price of $233.33
  • buy AAPL 100 AF @ 233.33 preview — preview the margin impact and cost estimation without executing an order
  • buy AAPL 100 AF @ 233.33 + 10 — same buy order as above, but automatically attach a "take profit" order $10 higher
  • buy AAPL 100 AF @ 233.33 - 10 — same buy order as above, but automatically attach a "stop loss" order $10 lower
  • buy AAPL 100 AF @ 233.33 ± 10 — same buy order as above, but automatically attach a "take profit" $10 high and a "stop loss" $10 lower simultaenously (when one executes, the other is automatically cancelled by the IBKR system)
• The cli also supports running any commands concurrently or sequentially. This will run both buy commands concurrently then show your portfolio holdings after they complete:
  • buy AAPL 100 AF preview&; buy MSFT 100 AF preview&; ls.
  • Basically: append & to your commands to run them concurrently then split commands with ;, and you can also run any commands sequentially with just ; as well like: ls; ord; bal SMA
  • Note: these two are equivalent, but the expand version is easier if your purchase quantity/amount and algo are the same: buy AAPL 100 AF preview&; buy MSFT 100 AF preview& versus expand buy {MSFT,AAPL} 100 AF prevew
• We also have a built-in account and market calculator operating in prefix mode:
  • (/ :BP3 AAPL) shows how many shares you can buy of AAPL (on 33% margin).
  • (grow :AF 300) calculates your AvailableFunds growing by 300%.
  • Caluclation functions can be combined arbitrarily like: (grow (* AAPL (/ :BP3 AAPL)) 7)
  • You can also do math on arbitrary symbols if you want to for some reason: (/ AAPL TSLA)
  • prices used for symbol math are the live bid/ask midpoint price for each symbol.
  • You can also use row-position details for a live quote value too: (/ AAPL :18).
• You can simulate "action-if-touched" using our ifthen predicates like: if AAPL last > 300: buy AAPL 100 AF which will check every AAPL quote update, and if the last trade price is over $300, your command executes. The ifthen system supports unlimited combinations of conditions triggering on any combinations of: last, bid, ask, high, low, emas, atrs, greeks, and others per symbol. See code or test case examples for usability conditions.
• Also, the ifthen system supports loading "ifthen programs" into icli so you can alternate commands based on some algo feed conditions (i.e. "if ema crossover to the upside, buy; if ema crossover to the downside, sell" but the conditions remain active after one exectues so your "algo conditions" remain live and continue executing until you manually stop it (or unless you run out of buying power)).

See below for further account setup and environment variable conditions under the Download section.

For tracking feature updates, check the full commit history and you can always run ? for listing commands and getting help when running commands. The README is slightly undermaintained and some features are lacking complete documentation outside of the runtime itself, so feel free to suggest updates where useful.

Features

• allows full trading and data access to your IBKR account using only a CLI
  • note: IBKR doesn't allow all operations from their API, so some operations like money transfers, funding, requesting market data, requesting trading permissions, etc, still need to use the mobile/web apps.
• allows trading as fast as you can type (no need to navigate multiple screens / checks / pre-flight confirmations)
  • in fact, no confirmation for anything. you type it, it happens.
  • forward implication: also allows losing money as fast as you can type
• commands can be entered as any unambiguous prefix
  • e.g. position command can be entered as just p because it doesn't conflict with any other command
  • but for qquote and quote commands, so those must be clarified by using qq or qu at a minimum
• interface shows balances, components of account value, P&L, and other account stats updating in real time
• an excessive amount of attention is given to formatting data for maximum readability and quick understanding at a glance
  • due to density of visible data, it's recommended to run a smaller terminal font size to enable 170+ character wide viewing
• uses console ansi color gradients to show the "goodness" or "badness" of current price quotes
  • bad is red
  • more bad is more red
  • good is green
  • more good is more green
  • really really good is blue (>= 0.98% change)
• helpful CLI prompts for multi-stage operations (thanks to questionary)
• selects correct class of IBKR contract based on names entered (see: helpers.py:contractForName())
  • futures are prefixed with slashes, as is a norm: /ES, /MES, /NQ, /MNQ, etc
  • options are the full OCC symbol (no spaces): AAPL210716C00155000
  • future options start with a slash: /ES210716C05000000
  • warrants, bonds, bills, forex, etc, aren't currently addressable in the CLI because we didn't decide on a naming convention yet
  • spreads can be entered as a full buy/sell ratio description like:
    • "bto 1 AAPL210716C00155000 sto 2 AAPL210716C00160000 bto 1 AAPL210716C00165000"
    • works for adding live quotes (add "bto ... sto ...") and for requesting spread trades using the spread command
      • for ordering spreads, you specify the baseline spread per-leg ratio (e.g. butterflies are 1:2:1 as above), then the total spread order is the quantity requested multiplied by each leg ratio (e.g. butterfly 1:2:1 with quantity 100 will order 100 + 200 + 100 = 400 total contracts via a COB)
• the positions CLI view also shows matched closing orders for each currently owned symbol
• helper shorthands, like an EVICT [symbol] [quantity] command to immediately yeet an entire equity position into a [MidPrice](https://www.interactivebro