ibkr-cli 0.1.0__tar.gz

ibkr_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wangding
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ibkr_cli-0.1.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: ibkr-cli
+Version: 0.1.0
+Summary: A local-first CLI for Interactive Brokers
+Author: wangding
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/wangding/ibkr-cli
+Project-URL: Repository, https://github.com/wangding/ibkr-cli
+Project-URL: Issues, https://github.com/wangding/ibkr-cli/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ib_async<3,>=2.1
+Requires-Dist: platformdirs<5,>=4.2
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: rich<14,>=13.7
+Requires-Dist: tomli<3,>=2.0; python_version < "3.11"
+Requires-Dist: typer<1,>=0.12
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == "test"
+Dynamic: license-file
+
+# ibkr-cli
+
+A local-first CLI for Interactive Brokers built on top of `ib_async`, `Typer`, and `Rich`.
+
+## 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:
+
+```bash
+pipx install ibkr-cli
+```
+
+If you prefer to install into the current Python environment:
+
+```bash
+python -m pip install ibkr-cli
+```
+
+After installation:
+
+```bash
+ibkr --help
+ibkr --version
+```
+
+## Quick start
+
+### Initialize local config
+
+```bash
+ibkr profile init
+```
+
+This creates a config file under the path returned by:
+
+```bash
+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
+
+```bash
+ibkr profile list
+ibkr profile show gateway-paper
+```
+
+### Check connectivity
+
+```bash
+ibkr doctor --profile gateway-paper
+ibkr connect test --profile gateway-paper
+```
+
+## Core commands
+
+### Account and positions
+
+```bash
+ibkr account summary --profile gateway-paper
+ibkr positions --profile gateway-paper
+```
+
+### Orders
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+ibkr buy AAPL 10 --submit --profile gateway-paper
+ibkr sell AAPL 10 --submit --profile gateway-paper
+```
+
+### Market data
+
+Snapshot quote:
+
+```bash
+ibkr quote AAPL --profile gateway-paper
+ibkr quote AAPL --profile gateway-paper --json
+```
+
+Finite quote watch:
+
+```bash
+ibkr quote AAPL --watch --updates 5 --interval 2 --profile gateway-paper
+```
+
+Historical bars:
+
+```bash
+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:
+
+```bash
+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:
+
+```json
+{
+  "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:
+
+```bash
+python -m pip install -e .
+```
+
+Install in editable mode with optional test dependencies:
+
+```bash
+python -m pip install -e ".[test]"
+```
+
+Run directly from source if needed:
+
+```bash
+python -m ibkr_cli.app --help
+```
+
+Run the offline test suite:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+The packaged entrypoint for installed users is:
+
+```bash
+ibkr --help
+```

ibkr_cli-0.1.0/README.md

@@ -0,0 +1,242 @@
+# ibkr-cli
+
+A local-first CLI for Interactive Brokers built on top of `ib_async`, `Typer`, and `Rich`.
+
+## 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:
+
+```bash
+pipx install ibkr-cli
+```
+
+If you prefer to install into the current Python environment:
+
+```bash
+python -m pip install ibkr-cli
+```
+
+After installation:
+
+```bash
+ibkr --help
+ibkr --version
+```
+
+## Quick start
+
+### Initialize local config
+
+```bash
+ibkr profile init
+```
+
+This creates a config file under the path returned by:
+
+```bash
+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
+
+```bash
+ibkr profile list
+ibkr profile show gateway-paper
+```
+
+### Check connectivity
+
+```bash
+ibkr doctor --profile gateway-paper
+ibkr connect test --profile gateway-paper
+```
+
+## Core commands
+
+### Account and positions
+
+```bash
+ibkr account summary --profile gateway-paper
+ibkr positions --profile gateway-paper
+```
+
+### Orders
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+ibkr buy AAPL 10 --submit --profile gateway-paper
+ibkr sell AAPL 10 --submit --profile gateway-paper
+```
+
+### Market data
+
+Snapshot quote:
+
+```bash
+ibkr quote AAPL --profile gateway-paper
+ibkr quote AAPL --profile gateway-paper --json
+```
+
+Finite quote watch:
+
+```bash
+ibkr quote AAPL --watch --updates 5 --interval 2 --profile gateway-paper
+```
+
+Historical bars:
+
+```bash
+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:
+
+```bash
+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:
+
+```json
+{
+  "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:
+
+```bash
+python -m pip install -e .
+```
+
+Install in editable mode with optional test dependencies:
+
+```bash
+python -m pip install -e ".[test]"
+```
+
+Run directly from source if needed:
+
+```bash
+python -m ibkr_cli.app --help
+```
+
+Run the offline test suite:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+The packaged entrypoint for installed users is:
+
+```bash
+ibkr --help
+```

ibkr_cli-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ibkr-cli"
+version = "0.1.0"
+description = "A local-first CLI for Interactive Brokers"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  {name = "wangding"},
+]
+dependencies = [
+  "ib_async>=2.1,<3",
+  "platformdirs>=4.2,<5",
+  "pydantic>=2.6,<3",
+  "rich>=13.7,<14",
+  "tomli>=2.0,<3; python_version < '3.11'",
+  "typer>=0.12,<1",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Office/Business :: Financial :: Investment",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/wangding/ibkr-cli"
+Repository = "https://github.com/wangding/ibkr-cli"
+Issues = "https://github.com/wangding/ibkr-cli/issues"
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8,<9",
+]
+
+[project.scripts]
+ibkr = "ibkr_cli.app:app"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]

ibkr_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ibkr_cli-0.1.0/setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()

ibkr_cli-0.1.0/src/ibkr_cli/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

ibkr_cli-0.1.0/src/ibkr_cli/__main__.py

@@ -0,0 +1,4 @@
+from ibkr_cli.app import app
+
+if __name__ == "__main__":
+    app()