How mattsta/icli works
Project Type and Purpose
• icli is an open‑source, full-featured Command‑Line Interface (CLI) tool for live and paper trading via Interactive Brokers (IBKR).
• Purpose: rapid entry of orders, real‑time streaming quotes, account management, and optional audio notifications.
File Structure
• Top‐level:
• icli/ – main package
• pyproject.toml – build and dependency config (Poetry)
• README, LICENSE, .gitignore
• Inside icli/:
• __main__.py – entry point, sets up event loop & env
• cli.py – REPL loop using prompt‑toolkit, command dispatcher
• lang.py – implementations of each CLI command via a dispatch framework
• awwdio.py – optional audio announcement client integration
• futsexchanges.py – futures symbol ↔ exchange mapping generator
• helpers.py – contracts and naming utilities
• orders.py – IBKR Order object builders and metadata handling
• calc.py, tinyalgo.py – calculator and experimental algo hooks
README for Insights
• Entry point and architecture summary at the bottom (“Architecture” section).
• External dependencies: IBKR Gateway/TWS, ib_insync wrapper, optional awwdio audio server.
• Persistence: ~/.tplatcli_ibkr_history.*, timestamped icli-*.log.
Main Components
a. Frontend:
– Terminal / User
– prompt_toolkit REPL
b. Core CLI Application:
– __main__.py: bootstrap, read ENV, start event loop
– cli.py: IBKRCmdlineApp.dorepl() — prompt loop & parser
– Command Dispatcher (mutil/dispatch.py‑based)
– Command Implementations in lang.py, calc.py, tinyalgo.py
– Helpers (helpers.py, orders.py, futsexchanges.py)
c. External Services:
– IBKR Gateway/TWS (local host + port)
– IBKR upstream trade/data API
– Optional awwdio audio notification server
d. Persistence & Logging:
– History file in user home ~/.tplatcli_ibkr_history.{live,sandbox}
– Log file icli-{timestamp}.log
– Environment variables / .env.icli
Relationships and Data Flows
• User types commands in Terminal → REPL (cli.py) → Dispatcher (mutil) → Command classes (lang.py, etc.)
• Commands that request market data or send orders call ib_insync wrapper → IBKR Gateway → IBKR servers.
• Command results (quotes, positions, logs) streamed back to CLI UI.
• Execution events optionally sent to awwdio for speech.
• All API calls and events appended to a logfile; user inputs persisted to history file.
Architectural Patterns & Design Principles
• Modular command classes (Command pattern via dispatch map in lang.py).
• Separation of concerns:
• REPL / I/O (cli.py)
• Business logic (lang.py, calc.py, tinyalgo.py)
• External integrations (awwdio.py, futsexchanges.py, orders.py)
• Event-driven loop (prompt-toolkit) for concurrency & async IO (IBKR streaming).
• Environment-based configuration (12‑factor style via ENV vars / .env.icli).
Relevant Technologies & Libraries
• Python 3.x, Poetry (pyproject.toml)
• prompt‑toolkit for interactive CLI
• ib_insync for IBKR API wrapper
• questionary for prompts
• mutil/dispatch.py for command dispatching
• Standard logging module
• Optional HTTP client to awwdio
• Use clear, descriptive labels for each component (e.g., “REPL Loop”, “Order Builder”, “IBKR Gateway”).
• User → REPL
• REPL → Dispatcher → Command Classes
• Commands → IBKR API → IBKR Gateway → IBKR Servers
• Commands → Log Writer / History Persister
• Optional Commands → AWwdio → Audio Output
• Blue for CLI core
• Green for external services
• Orange for helpers & utilities
• Gray for persistence & config
• Clouds for external services (IBKR, AWwdio)