mt5cli 0.2.0__tar.gz → 0.4.0__tar.gz

mt5cli-0.4.0/.agents/skills/local-qa/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: local-qa
+description: Run local QA including formatting, linting, and testing for the repository. Use whenever any file has been updated.
+disable-model-invocation: false
+---
+
+# Local QA (format, lint, and test)
+
+Run the local QA script `scripts/qa.sh` in this skill.
+
+## Procedure
+
+- Execute the script exactly as shown above when this skill is triggered.
+- Capture and summarize key output (success/failure, major warnings, and any files modified).
+- If the script fails due to missing tooling (`command not found`, missing executable, or equivalent), install the missing tool(s) and rerun `./scripts/qa.sh`.
+- Install tools using this order of preference:
+  1. Use the project's package manager when applicable (`uv`/`poetry` for Python, package manager scripts/dependencies for Node.js).
+  2. Use a system package manager (`brew` on macOS, `apt` on Debian/Ubuntu) when project-local install is not applicable.
+  3. Use language-specific installers as fallback (`pipx`/`pip`, `npm`, `go install`, etc.).
+- If multiple tools are missing, repeat install -> rerun until QA completes or you hit a blocker.
+- If installation fails or requires unavailable privileges, report what was attempted, the exact failure, and stop.
+- Do not run unrelated commands; only run commands needed for QA and missing-tool installation.

mt5cli-0.4.0/.agents/skills/local-qa/scripts/qa.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+set -euox pipefail
+cd "$(git rev-parse --show-toplevel)"
+
+# Python
+uv run ruff format .
+uv run ruff check --fix .
+uv run pyright .
+uv run pytest
+
+# Markdown
+npx -y prettier --write './**/*.md'
+
+# GitHub Actions
+case "${OSTYPE}" in
+  darwin* | linux* )
+    zizmor --fix=safe .github/workflows
+    git ls-files -z -- '.github/workflows/*.yml' | xargs -0 -t actionlint
+    git ls-files -z -- '.github/workflows/*.yml' | xargs -0 -t yamllint -d '{"extends": "relaxed", "rules": {"line-length": "disable"}}'
+    checkov --framework=all --output=github_failed_only --directory=.
+    ;;
+  * )
+    echo "GitHub Actions linting is only supported on Linux and macOS."
+    ;;
+esac

mt5cli-0.4.0/.agents/skills/mt5cli/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: mt5cli
+description: Use the `mt5cli` CLI to export MetaTrader 5 data (rates, ticks, account, symbols, orders, positions, history) to CSV, JSON, Parquet, or SQLite3. Invoke when the user asks to export, dump, download, or fetch MT5 market data or account data to a file.
+---
+
+# mt5cli
+
+Export MetaTrader 5 data to CSV, JSON, Parquet, or SQLite3 via the `mt5cli`
+command. Output format is auto-detected from the file extension (`.csv`,
+`.json`, `.parquet`/`.pq`, `.db`/`.sqlite`/`.sqlite3`) or overridden with
+`--format/-f`.
+
+## Requirements
+
+- Python 3.11+ on Windows with MetaTrader 5 installed (pdmt5 requires the
+  MT5 terminal).
+- Install: `pip install -U mt5cli MetaTrader5`.
+- In this repo, run via `uv run mt5cli ...` or `uv run python -m mt5cli ...`.
+
+## Invocation shape
+
+```
+mt5cli [GLOBAL OPTIONS] -o OUTPUT COMMAND [COMMAND OPTIONS]
+```
+
+Global options MUST precede the subcommand.
+
+### Global options (apply to every subcommand)
+
+| Option                | Purpose                                                       |
+| --------------------- | ------------------------------------------------------------- |
+| `-o, --output PATH`   | Output file path (required).                                  |
+| `-f, --format FORMAT` | `csv`, `json`, `parquet`, or `sqlite3` (auto from extension). |
+| `--table NAME`        | Table name for SQLite3 output (default: `data`).              |
+| `--login INT`         | MT5 trading account login.                                    |
+| `--password TEXT`     | MT5 trading account password.                                 |
+| `--server TEXT`       | MT5 trading server name.                                      |
+| `--path TEXT`         | Path to MetaTrader 5 terminal EXE.                            |
+| `--timeout INT`       | Connection timeout in milliseconds.                           |
+| `--log-level LEVEL`   | `DEBUG`, `INFO`, `WARNING` (default), `ERROR`.                |
+
+### Parameter value formats
+
+- **Datetimes** (`--date-from`, `--date-to`): ISO 8601 (`2024-01-01` or
+  `2024-01-01T12:00:00+00:00`). Naive values are treated as UTC.
+- **Timeframe** (`--timeframe`): `M1`, `M2`, `M3`, `M4`, `M5`, `M6`, `M10`,
+  `M12`, `M15`, `M20`, `M30`, `H1`, `H2`, `H3`, `H4`, `H6`, `H8`, `H12`,
+  `D1`, `W1`, `MN1`, or the raw integer.
+- **Tick flags** (`--flags`): `ALL`, `INFO`, `TRADE`, or the raw integer.
+
+## Commands
+
+| Command           | Required options                                      | Optional options                                                                                                                                                                                                                 |
+| ----------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rates-from`      | `--symbol`, `--timeframe`, `--date-from`, `--count`   | —                                                                                                                                                                                                                                |
+| `rates-from-pos`  | `--symbol`, `--timeframe`, `--start-pos`, `--count`   | —                                                                                                                                                                                                                                |
+| `rates-range`     | `--symbol`, `--timeframe`, `--date-from`, `--date-to` | —                                                                                                                                                                                                                                |
+| `ticks-from`      | `--symbol`, `--date-from`, `--count`, `--flags`       | —                                                                                                                                                                                                                                |
+| `ticks-range`     | `--symbol`, `--date-from`, `--date-to`, `--flags`     | —                                                                                                                                                                                                                                |
+| `account-info`    | —                                                     | —                                                                                                                                                                                                                                |
+| `terminal-info`   | —                                                     | —                                                                                                                                                                                                                                |
+| `symbols`         | —                                                     | `--group` (e.g., `*USD*`)                                                                                                                                                                                                        |
+| `symbol-info`     | `--symbol`                                            | —                                                                                                                                                                                                                                |
+| `orders`          | —                                                     | `--symbol`, `--group`, `--ticket`                                                                                                                                                                                                |
+| `positions`       | —                                                     | `--symbol`, `--group`, `--ticket`                                                                                                                                                                                                |
+| `history-orders`  | —                                                     | `--date-from`, `--date-to`, `--group`, `--symbol`, `--ticket`, `--position`                                                                                                                                                      |
+| `history-deals`   | —                                                     | `--date-from`, `--date-to`, `--group`, `--symbol`, `--ticket`, `--position`                                                                                                                                                      |
+| `collect-history` | `--symbol` (repeatable), `--date-from`, `--date-to`   | `--dataset` (repeatable; rates/ticks/history-orders/history-deals; default all), `--timeframe` (M1; recorded on rates), `--flags` (ALL), `--if-exists` (append/replace/fail; default fail), `--with-views` (SQLite3 output only) |
+
+## Examples
+
+```bash
+# Account snapshot as CSV.
+mt5cli -o account.csv account-info
+
+# EURUSD M1 bars (1000 rows) from a start date to Parquet.
+mt5cli -o rates.parquet rates-from \
+  --symbol EURUSD --timeframe M1 --date-from 2024-01-01 --count 1000
+
+# EURUSD tick stream for a date range to JSON.
+mt5cli -o ticks.json ticks-range \
+  --symbol EURUSD --date-from 2024-01-01 --date-to 2024-01-02 --flags ALL
+
+# USD symbols into a named table in SQLite3.
+mt5cli -o data.db --table symbols symbols --group "*USD*"
+
+# Historical deals filtered by symbol (using an already-logged-in MT5 terminal).
+mt5cli -o deals.csv history-deals --symbol EURUSD --date-from 2024-01-01
+
+# Bundle selected historical datasets into one SQLite db, appending to any
+# existing tables, plus cash_events and positions_reconstructed views.
+mt5cli -o history.db collect-history \
+  --symbol EURUSD --symbol GBPUSD \
+  --date-from 2024-01-01 --date-to 2024-02-01 \
+  --dataset rates --dataset history-deals \
+  --timeframe M1 --flags ALL --if-exists append --with-views
+```
+
+## Guidelines
+
+- Pick the output extension to avoid passing `--format`.
+- Use `--table` only with SQLite3 outputs; it is otherwise ignored.
+- `--count` is required for `rates-from`, `rates-from-pos`, and `ticks-from`.
+  Prefer `rates-range` / `ticks-range` when a fixed window is known.
+- Credentials (`--login`, `--password`, `--server`) are optional when the
+  local MT5 terminal is already logged in.
+- Avoid passing `--password` on the command line in shared or logged
+  environments — it is visible in `ps`, shell history, and CI logs. Prefer
+  logging in through the MT5 terminal first, then omit credentials here.
+- Reach for `--log-level DEBUG` when a command fails silently — MT5
+  connection errors surface there.
+- If the user asks to run from source in this repo, prefix with `uv run`
+  (e.g., `uv run mt5cli -o out.csv account-info`).

{mt5cli-0.2.0 → mt5cli-0.4.0}/.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
       || (github.event_name == 'workflow_dispatch' && inputs.workflow == 'lint-and-test')
     permissions:
       contents: read
-    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-lint-and-scan.yml@main  # zizmor: ignore[unpinned-uses]
+    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-lint-and-scan.yml@main   # zizmor: ignore[unpinned-uses]
     with:
       package-path: .
       runs-on: windows-latest
@@ -59,7 +59,6 @@ jobs:
     uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-mkdocs-gh-deploy.yml@main  # zizmor: ignore[unpinned-uses]
     with:
       package-path: .
-      mkdocs-theme: material
       runs-on: ubuntu-slim
     secrets:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{mt5cli-0.2.0 → mt5cli-0.4.0}/AGENTS.md

@@ -29,9 +29,11 @@ uv sync
 - `mt5cli/`: Main package directory
   - `__init__.py`: Package initialization and exports (`detect_format`, `export_dataframe`)
   - `cli.py`: CLI application with typer-based commands for data export
+  - `utils.py`: Constants, enums, parameter types, parsers, and export utilities
   - `__main__.py`: Entry point for `python -m mt5cli`
 - `tests/`: Comprehensive test suite (pytest-based)
-  - `test_cli.py`: Tests for CLI commands, parameter types, and export functions
+  - `test_cli.py`: Tests for CLI commands and collect-history behavior
+  - `test_utils.py`: Tests for utility constants, parameter types, parsers, and export functions
 - `docs/`: MkDocs documentation with API reference
   - `docs/index.md`: Main documentation
   - `docs/api/`: Auto-generated API documentation for all modules

{mt5cli-0.2.0 → mt5cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 0.2.0
+Version: 0.4.0
 Summary: Command-line tool for MetaTrader 5
 Project-URL: Repository, https://github.com/dceoy/mt5cli.git
 Author-email: dceoy <dceoy@users.noreply.github.com>
@@ -74,30 +74,45 @@ python -m mt5cli -o account.csv account-info
 
 ## Commands
 
-| Command            | Description                                 |
-| ------------------ | ------------------------------------------- |
-| `rates-from`       | Export rates from a start date              |
-| `rates-from-pos`   | Export rates from a start position          |
-| `rates-range`      | Export rates for a date range               |
-| `ticks-from`       | Export ticks from a start date              |
-| `ticks-range`      | Export ticks for a date range               |
-| `account-info`     | Export account information                  |
-| `terminal-info`    | Export terminal information                 |
-| `version`          | Export MetaTrader 5 version information     |
-| `last-error`       | Export the last error information           |
-| `symbols`          | Export symbol list                          |
-| `symbol-info`      | Export symbol details                       |
-| `symbol-info-tick` | Export the last tick for a symbol           |
-| `market-book`      | Export market depth (order book)            |
-| `orders`           | Export active orders                        |
-| `positions`        | Export open positions                       |
-| `history-orders`   | Export historical orders                    |
-| `history-deals`    | Export historical deals                     |
-| `order-check`      | Check funds sufficiency for a trade request |
-| `order-send`       | Send a trade request to the trade server (`--yes` required) |
+| Command            | Description                                                                                                  |
+| ------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `rates-from`       | Export rates from a start date                                                                               |
+| `rates-from-pos`   | Export rates from a start position                                                                           |
+| `rates-range`      | Export rates for a date range                                                                                |
+| `ticks-from`       | Export ticks from a start date                                                                               |
+| `ticks-range`      | Export ticks for a date range                                                                                |
+| `account-info`     | Export account information                                                                                   |
+| `terminal-info`    | Export terminal information                                                                                  |
+| `version`          | Export MetaTrader 5 version information                                                                      |
+| `last-error`       | Export the last error information                                                                            |
+| `symbols`          | Export symbol list                                                                                           |
+| `symbol-info`      | Export symbol details                                                                                        |
+| `symbol-info-tick` | Export the last tick for a symbol                                                                            |
+| `market-book`      | Export market depth (order book)                                                                             |
+| `orders`           | Export active orders                                                                                         |
+| `positions`        | Export open positions                                                                                        |
+| `history-orders`   | Export historical orders                                                                                     |
+| `history-deals`    | Export historical deals                                                                                      |
+| `order-check`      | Check funds sufficiency for a trade request                                                                  |
+| `order-send`       | Send a trade request to the trade server (`--yes` required)                                                  |
+| `collect-history`  | Bundle rates, ticks, history-orders, and history-deals for one or more symbols into a single SQLite database |
 
 Use `order-check` to validate a request payload before running `order-send --yes`.
 
+### `collect-history`
+
+Collect several historical datasets per symbol into one SQLite database in a single MT5 session. Pick datasets with repeatable `--dataset` (default: all four), choose conflict behavior with `--if-exists append|replace|fail` (default: `fail`), and optionally derive `cash_events` / `positions_reconstructed` views from `history_deals` via `--with-views`.
+
+```bash
+mt5cli -o history.db collect-history \
+  --symbol EURUSD --symbol GBPUSD \
+  --date-from 2024-01-01 --date-to 2024-02-01 \
+  --dataset rates --dataset history-deals \
+  --timeframe M1 --flags ALL --if-exists append --with-views
+```
+
+History orders and deals are fetched per symbol and concatenated, so the symbol filter is applied consistently across all datasets. The `cash_events` view is derived from symbol-filtered `history_deals`, so account-level cash events with empty or non-matching symbols may be excluded. The `rates` table records the requested `timeframe` so appended runs at different timeframes remain distinguishable. The `positions_reconstructed` view aggregates trade deals by `position_id`, excludes positions without closing deals, and uses volume-weighted open/close prices; reversal deals (`DEAL_ENTRY_INOUT`) are reported via `volume_reversal` / `reversal_count` columns and do not contribute to the weighted prices.
+
 ## Requirements
 
 - Python 3.11+

{mt5cli-0.2.0 → mt5cli-0.4.0}/README.md

@@ -50,30 +50,45 @@ python -m mt5cli -o account.csv account-info
 
 ## Commands
 
-| Command            | Description                                 |
-| ------------------ | ------------------------------------------- |
-| `rates-from`       | Export rates from a start date              |
-| `rates-from-pos`   | Export rates from a start position          |
-| `rates-range`      | Export rates for a date range               |
-| `ticks-from`       | Export ticks from a start date              |
-| `ticks-range`      | Export ticks for a date range               |
-| `account-info`     | Export account information                  |
-| `terminal-info`    | Export terminal information                 |
-| `version`          | Export MetaTrader 5 version information     |
-| `last-error`       | Export the last error information           |
-| `symbols`          | Export symbol list                          |
-| `symbol-info`      | Export symbol details                       |
-| `symbol-info-tick` | Export the last tick for a symbol           |
-| `market-book`      | Export market depth (order book)            |
-| `orders`           | Export active orders                        |
-| `positions`        | Export open positions                       |
-| `history-orders`   | Export historical orders                    |
-| `history-deals`    | Export historical deals                     |
-| `order-check`      | Check funds sufficiency for a trade request |
-| `order-send`       | Send a trade request to the trade server (`--yes` required) |
+| Command            | Description                                                                                                  |
+| ------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `rates-from`       | Export rates from a start date                                                                               |
+| `rates-from-pos`   | Export rates from a start position                                                                           |
+| `rates-range`      | Export rates for a date range                                                                                |
+| `ticks-from`       | Export ticks from a start date                                                                               |
+| `ticks-range`      | Export ticks for a date range                                                                                |
+| `account-info`     | Export account information                                                                                   |
+| `terminal-info`    | Export terminal information                                                                                  |
+| `version`          | Export MetaTrader 5 version information                                                                      |
+| `last-error`       | Export the last error information                                                                            |
+| `symbols`          | Export symbol list                                                                                           |
+| `symbol-info`      | Export symbol details                                                                                        |
+| `symbol-info-tick` | Export the last tick for a symbol                                                                            |
+| `market-book`      | Export market depth (order book)                                                                             |
+| `orders`           | Export active orders                                                                                         |
+| `positions`        | Export open positions                                                                                        |
+| `history-orders`   | Export historical orders                                                                                     |
+| `history-deals`    | Export historical deals                                                                                      |
+| `order-check`      | Check funds sufficiency for a trade request                                                                  |
+| `order-send`       | Send a trade request to the trade server (`--yes` required)                                                  |
+| `collect-history`  | Bundle rates, ticks, history-orders, and history-deals for one or more symbols into a single SQLite database |
 
 Use `order-check` to validate a request payload before running `order-send --yes`.
 
+### `collect-history`
+
+Collect several historical datasets per symbol into one SQLite database in a single MT5 session. Pick datasets with repeatable `--dataset` (default: all four), choose conflict behavior with `--if-exists append|replace|fail` (default: `fail`), and optionally derive `cash_events` / `positions_reconstructed` views from `history_deals` via `--with-views`.
+
+```bash
+mt5cli -o history.db collect-history \
+  --symbol EURUSD --symbol GBPUSD \
+  --date-from 2024-01-01 --date-to 2024-02-01 \
+  --dataset rates --dataset history-deals \
+  --timeframe M1 --flags ALL --if-exists append --with-views
+```
+
+History orders and deals are fetched per symbol and concatenated, so the symbol filter is applied consistently across all datasets. The `cash_events` view is derived from symbol-filtered `history_deals`, so account-level cash events with empty or non-matching symbols may be excluded. The `rates` table records the requested `timeframe` so appended runs at different timeframes remain distinguishable. The `positions_reconstructed` view aggregates trade deals by `position_id`, excludes positions without closing deals, and uses volume-weighted open/close prices; reversal deals (`DEAL_ENTRY_INOUT`) are reported via `volume_reversal` / `reversal_count` columns and do not contribute to the weighted prices.
+
 ## Requirements
 
 - Python 3.11+

{mt5cli-0.2.0 → mt5cli-0.4.0}/docs/api/index.md

@@ -10,12 +10,22 @@ The mt5cli package consists of the following modules:
 
 Command-line interface module providing typer-based commands for exporting MetaTrader 5 data to CSV, JSON, Parquet, and SQLite3 formats.
 
+### [Utils](utils.md)
+
+Utility module providing constants, enums, Click parameter types, and helper functions for parsing and exporting data.
+
+### [SDK](sdk.md)
+
+Programmatic SDK for read-only MetaTrader 5 data collection. Returns pandas DataFrames and provides `collect_history` for SQLite bulk collection.
+
 ## Architecture Overview
 
 The package follows a simple architecture built on top of pdmt5:
 
-1. **CLI Layer** (`cli.py`): Typer application with subcommands for each data type, custom Click parameter types for datetime/timeframe/tick flags parsing, and format detection/export utilities.
-2. **Data Layer** (via `pdmt5`): Uses `Mt5DataClient` and `Mt5Config` from the pdmt5 package for all MetaTrader 5 data access.
+1. **CLI Layer** (`cli.py`): Typer application with subcommands that delegate to the SDK and export results.
+2. **SDK Layer** (`sdk.py`): Read-only data access functions, `Mt5CliClient`, and `collect_history` orchestration.
+3. **Utils Layer** (`utils.py`): Constants, enums, custom Click parameter types, parsing helpers, and format detection/export utilities.
+4. **Data Layer** (via `pdmt5`): Uses `Mt5DataClient` and `Mt5Config` from the pdmt5 package for all MetaTrader 5 data access.
 
 ## Usage Guidelines
 
@@ -47,15 +57,38 @@ mt5cli -o data.db --table symbols symbols --group "*USD*"
 ## Python API
 
 ```python
-from mt5cli import detect_format, export_dataframe
-import pandas as pd
+from datetime import UTC, datetime
+from pathlib import Path
+
+from mt5cli import (
+    Mt5CliClient,
+    collect_history,
+    copy_rates_range,
+    detect_format,
+    export_dataframe,
+)
+
+# Fetch rates programmatically
+rates = copy_rates_range(
+    "EURUSD",
+    timeframe="H1",
+    date_from="2024-01-01",
+    date_to="2024-02-01",
+)
 
 # Detect output format from file extension
 fmt = detect_format(Path("output.parquet"))  # Returns "parquet"
 
 # Export a DataFrame
-df = pd.DataFrame({"symbol": ["EURUSD"], "bid": [1.1234]})
-export_dataframe(df, Path("output.csv"), "csv")
+export_dataframe(rates, Path("output.csv"), "csv")
+
+# Collect history into SQLite
+collect_history(
+    Path("history.db"),
+    symbols=["EURUSD"],
+    date_from=datetime(2024, 1, 1, tzinfo=UTC),
+    date_to=datetime(2024, 2, 1, tzinfo=UTC),
+)
 ```
 
 ## Examples

mt5cli-0.4.0/docs/api/sdk.md

@@ -0,0 +1,3 @@
+# SDK Module
+
+::: mt5cli.sdk

mt5cli-0.4.0/docs/api/utils.md

@@ -0,0 +1,3 @@
+# Utils Module
+
+::: mt5cli.utils

{mt5cli-0.2.0 → mt5cli-0.4.0}/docs/index.md

@@ -20,6 +20,44 @@ mt5cli is a CLI application that exports MetaTrader 5 trading data to multiple f
 pip install mt5cli
 ```
 
+## Programmatic usage / SDK usage
+
+mt5cli can be used as a small Python SDK for read-only MetaTrader 5 data collection. SDK functions return pandas DataFrames without writing files. Use `export_dataframe` when you need to persist results.
+
+```python
+from datetime import UTC, datetime
+from pathlib import Path
+
+from mt5cli import Mt5CliClient, collect_history, copy_rates_range, export_dataframe
+
+# One-off fetch with module-level helpers
+rates = copy_rates_range(
+    "EURUSD",
+    timeframe="H1",
+    date_from="2024-01-01",
+    date_to="2024-02-01",
+)
+export_dataframe(rates, Path("rates.csv"), "csv")
+
+# Reuse one MT5 connection for multiple calls
+with Mt5CliClient(login=12345, password="secret", server="Broker-Demo") as client:
+    account = client.account_info()
+    positions = client.positions()
+
+# Bulk SQLite collection (same behavior as the collect-history CLI command)
+collect_history(
+    Path("history.db"),
+    symbols=["EURUSD", "GBPUSD"],
+    date_from=datetime(2024, 1, 1, tzinfo=UTC),
+    date_to=datetime(2024, 2, 1, tzinfo=UTC),
+    timeframe="M1",
+    flags="ALL",
+    with_views=True,
+)
+```
+
+Timeframes, tick flags, and ISO 8601 date strings are accepted wherever noted in the SDK API.
+
 ## Quick Start
 
 ```bash
@@ -74,17 +112,46 @@ mt5cli --login 12345 --password mypass --server MyBroker-Demo \
 
 ### Trading
 
-| Command          | Description                                 |
-| ---------------- | ------------------------------------------- |
-| `orders`         | Export active orders                        |
-| `positions`      | Export open positions                       |
-| `history-orders` | Export historical orders                    |
-| `history-deals`  | Export historical deals                     |
-| `order-check`    | Check funds sufficiency for a trade request |
+| Command          | Description                                                 |
+| ---------------- | ----------------------------------------------------------- |
+| `orders`         | Export active orders                                        |
+| `positions`      | Export open positions                                       |
+| `history-orders` | Export historical orders                                    |
+| `history-deals`  | Export historical deals                                     |
+| `order-check`    | Check funds sufficiency for a trade request                 |
 | `order-send`     | Send a trade request to the trade server (`--yes` required) |
 
 Use `order-check` to validate a request payload before running `order-send --yes`.
 
+### Bulk Collection
+
+| Command           | Description                                                                                                                                        |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `collect-history` | Collect rates, ticks, history-orders, and history-deals for one or more symbols into a single SQLite database (optional cash-event/position views) |
+
+```bash
+mt5cli -o history.db collect-history \
+  --symbol EURUSD --symbol GBPUSD \
+  --date-from 2024-01-01 --date-to 2024-02-01 \
+  --dataset rates --dataset history-deals \
+  --timeframe M1 --flags ALL --if-exists append --with-views
+```
+
+`collect-history` options:
+
+| Option         | Default    | Description                                                                                   |
+| -------------- | ---------- | --------------------------------------------------------------------------------------------- |
+| `--symbol/-s`  | _required_ | Symbol to collect (repeat for multiple).                                                      |
+| `--date-from`  | _required_ | Start date in ISO 8601.                                                                       |
+| `--date-to`    | _required_ | End date in ISO 8601.                                                                         |
+| `--dataset`    | all four   | Repeatable: `rates`, `ticks`, `history-orders`, `history-deals`.                              |
+| `--timeframe`  | `M1`       | Rates timeframe; recorded in a `timeframe` column on the `rates` table.                       |
+| `--flags`      | `ALL`      | Tick copy flags forwarded to `copy_ticks_range`.                                              |
+| `--if-exists`  | `fail`     | `append`, `replace`, or `fail` when a target table already exists.                            |
+| `--with-views` | off        | Add `cash_events` and `positions_reconstructed` views (requires the `history-deals` dataset). |
+
+History orders and deals are fetched per symbol and concatenated, so the symbol filter is applied consistently across all datasets. The `cash_events` view is derived from symbol-filtered `history_deals`, so account-level cash events with empty or non-matching symbols may be excluded. The `positions_reconstructed` view excludes positions with no closing deal, uses volume-weighted open/close prices, and reports reversal deals (`DEAL_ENTRY_INOUT`) via `volume_reversal` / `reversal_count`.
+
 ## Global Options
 
 | Option         | Description                                             |
@@ -109,7 +176,9 @@ Use `order-check` to validate a request payload before running `order-send --yes
 
 Browse the API documentation for detailed module information:
 
-- [CLI Module](api/cli.md) - CLI application with export commands and utility functions
+- [CLI Module](api/cli.md) - CLI application with export commands
+- [SDK Module](api/sdk.md) - Programmatic read-only data collection API
+- [Utils Module](api/utils.md) - Constants, parameter types, parsers, and export utilities
 
 ## Development
 

{mt5cli-0.2.0 → mt5cli-0.4.0}/mkdocs.yml

@@ -56,6 +56,8 @@ nav:
   - API Reference:
       - Overview: api/index.md
       - CLI: api/cli.md
+      - SDK: api/sdk.md
+      - Utils: api/utils.md
 
 markdown_extensions:
   - admonition

mt5cli-0.4.0/mt5cli/__init__.py

@@ -0,0 +1,56 @@
+"""mt5cli: Command-line tool and SDK for MetaTrader 5."""
+
+from importlib.metadata import version
+
+from .sdk import (
+    Mt5CliClient,
+    account_info,
+    build_config,
+    collect_history,
+    copy_rates_from,
+    copy_rates_from_pos,
+    copy_rates_range,
+    copy_ticks_from,
+    copy_ticks_range,
+    history_deals,
+    history_orders,
+    last_error,
+    market_book,
+    orders,
+    positions,
+    symbol_info,
+    symbol_info_tick,
+    symbols,
+    terminal_info,
+)
+from .sdk import (
+    version as mt5_version,
+)
+from .utils import detect_format, export_dataframe
+
+__version__ = version(__package__) if __package__ else None
+
+__all__ = [
+    "Mt5CliClient",
+    "account_info",
+    "build_config",
+    "collect_history",
+    "copy_rates_from",
+    "copy_rates_from_pos",
+    "copy_rates_range",
+    "copy_ticks_from",
+    "copy_ticks_range",
+    "detect_format",
+    "export_dataframe",
+    "history_deals",
+    "history_orders",
+    "last_error",
+    "market_book",
+    "mt5_version",
+    "orders",
+    "positions",
+    "symbol_info",
+    "symbol_info_tick",
+    "symbols",
+    "terminal_info",
+]