mt5cli 0.1.0__tar.gz → 0.3.0__tar.gz

mt5cli-0.3.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.3.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.3.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.1.0 → mt5cli-0.3.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,23 +59,9 @@ 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 }}
-  python-package-release:
-    if: >
-      github.event_name == 'push'
-      || (github.event_name == 'workflow_dispatch' && inputs.workflow == 'lint-and-test')
-    permissions:
-      contents: write
-      id-token: write
-    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-release-on-pypi-and-github.yml@main  # zizmor: ignore[unpinned-uses]
-    with:
-      package-path: .
-      create-releases: false
-    secrets:
-      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
   dependabot-auto-merge:
     if: >
       github.event_name == 'pull_request' && github.actor == 'dependabot[bot]'

mt5cli-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+---
+name: Release
+on:
+  workflow_dispatch:
+permissions:
+  contents: read
+defaults:
+  run:
+    shell: bash -euo pipefail {0}
+    working-directory: .
+jobs:
+  build-and-release:
+    permissions:
+      contents: write
+      id-token: write
+    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-release-on-pypi-and-github.yml@main  # zizmor: ignore[unpinned-uses]
+    with:
+      package-path: .
+      create-github-release: true
+      publish-to-pypi: false
+    secrets:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  publish-to-pypi:
+    name: Publish the Python 🐍 distribution 📦 to PyPI
+    if: >
+      startsWith(github.ref, 'refs/tags/')
+    needs:
+      - build-and-release
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/${{ needs.build-and-release.outputs.project-name }}
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: ${{ needs.build-and-release.outputs.distribution-artifact-name }}
+          path: dist/
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
+        with:
+          verbose: true

mt5cli-0.3.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: mt5cli
+Version: 0.3.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>
+Maintainer-email: dceoy <dceoy@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: <3.14,>=3.11
+Requires-Dist: click>=8.1.0
+Requires-Dist: pdmt5>=0.2.3
+Requires-Dist: pyarrow>=19.0.0
+Requires-Dist: typer>=0.15.0
+Description-Content-Type: text/markdown
+
+# mt5cli
+
+[![CI/CD](https://github.com/dceoy/mt5cli/actions/workflows/ci.yml/badge.svg)](https://github.com/dceoy/mt5cli/actions/workflows/ci.yml)
+
+Command-line tool for exporting MetaTrader 5 data to CSV, JSON, Parquet, and SQLite3.
+
+Built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data handler for MetaTrader 5.
+
+## Features
+
+- **Multi-format export**: CSV, JSON, Parquet, and SQLite3 output formats
+- **Auto-detection**: Format detection from file extensions
+- **Comprehensive data access**: Rates, ticks, account info, symbols, orders, positions, and trading history
+- **Flexible timeframes**: Named timeframes (M1, H1, D1, etc.) and numeric values
+- **Connection management**: Optional credentials, server, and timeout configuration
+
+## Installation
+
+```bash
+pip install -U mt5cli MetaTrader5
+```
+
+## Usage
+
+```bash
+# Export account information to CSV
+mt5cli -o account.csv account-info
+
+# Export EURUSD M1 rates to Parquet
+mt5cli -o rates.parquet rates-from --symbol EURUSD --timeframe M1 \
+  --date-from 2024-01-01 --count 1000
+
+# Export ticks to JSON
+mt5cli -o ticks.json ticks-from --symbol EURUSD \
+  --date-from 2024-01-01 --count 500 --flags ALL
+
+# Export symbols to SQLite3 with custom table name
+mt5cli -o data.db --table symbols symbols --group "*USD*"
+
+# Export with connection credentials
+mt5cli --login 12345 --password mypass --server MyBroker-Demo \
+  -o positions.csv positions
+```
+
+Run as a Python module:
+
+```bash
+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)                                                  |
+| `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+
+- Windows OS (MetaTrader 5 requirement)
+- MetaTrader 5 platform installed
+
+## Development
+
+```bash
+git clone https://github.com/dceoy/mt5cli.git
+cd mt5cli
+uv sync
+```
+
+## License
+
+[MIT](LICENSE)

mt5cli-0.3.0/README.md

@@ -0,0 +1,108 @@
+# mt5cli
+
+[![CI/CD](https://github.com/dceoy/mt5cli/actions/workflows/ci.yml/badge.svg)](https://github.com/dceoy/mt5cli/actions/workflows/ci.yml)
+
+Command-line tool for exporting MetaTrader 5 data to CSV, JSON, Parquet, and SQLite3.
+
+Built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data handler for MetaTrader 5.
+
+## Features
+
+- **Multi-format export**: CSV, JSON, Parquet, and SQLite3 output formats
+- **Auto-detection**: Format detection from file extensions
+- **Comprehensive data access**: Rates, ticks, account info, symbols, orders, positions, and trading history
+- **Flexible timeframes**: Named timeframes (M1, H1, D1, etc.) and numeric values
+- **Connection management**: Optional credentials, server, and timeout configuration
+
+## Installation
+
+```bash
+pip install -U mt5cli MetaTrader5
+```
+
+## Usage
+
+```bash
+# Export account information to CSV
+mt5cli -o account.csv account-info
+
+# Export EURUSD M1 rates to Parquet
+mt5cli -o rates.parquet rates-from --symbol EURUSD --timeframe M1 \
+  --date-from 2024-01-01 --count 1000
+
+# Export ticks to JSON
+mt5cli -o ticks.json ticks-from --symbol EURUSD \
+  --date-from 2024-01-01 --count 500 --flags ALL
+
+# Export symbols to SQLite3 with custom table name
+mt5cli -o data.db --table symbols symbols --group "*USD*"
+
+# Export with connection credentials
+mt5cli --login 12345 --password mypass --server MyBroker-Demo \
+  -o positions.csv positions
+```
+
+Run as a Python module:
+
+```bash
+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)                                                  |
+| `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+
+- Windows OS (MetaTrader 5 requirement)
+- MetaTrader 5 platform installed
+
+## Development
+
+```bash
+git clone https://github.com/dceoy/mt5cli.git
+cd mt5cli
+uv sync
+```
+
+## License
+
+[MIT](LICENSE)

mt5cli-0.3.0/docs/index.md

@@ -0,0 +1,154 @@
+# mt5cli
+
+Command-line tool for MetaTrader 5 data export.
+
+## Overview
+
+mt5cli is a CLI application that exports MetaTrader 5 trading data to multiple file formats. It is built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data handler for MetaTrader 5.
+
+## Features
+
+- **Multi-format export**: CSV, JSON, Parquet, and SQLite3 output formats
+- **Auto-detection**: Format detection from file extensions
+- **Comprehensive data access**: Rates, ticks, account info, symbols, orders, positions, and trading history
+- **Flexible timeframes**: Named timeframes (M1, H1, D1, etc.) and numeric values
+- **Connection management**: Optional credentials, server, and timeout configuration
+
+## Installation
+
+```bash
+pip install mt5cli
+```
+
+## Quick Start
+
+```bash
+# Export account information to CSV
+mt5cli -o account.csv account-info
+
+# Export EURUSD M1 rates to Parquet
+mt5cli -o rates.parquet rates-from --symbol EURUSD --timeframe M1 \
+  --date-from 2024-01-01 --count 1000
+
+# Export ticks to JSON
+mt5cli -o ticks.json ticks-from --symbol EURUSD \
+  --date-from 2024-01-01 --count 500 --flags ALL
+
+# Export symbols to SQLite3 with custom table name
+mt5cli -o data.db --table symbols symbols --group "*USD*"
+
+# Export with connection credentials
+mt5cli --login 12345 --password mypass --server MyBroker-Demo \
+  -o positions.csv positions
+```
+
+## Commands
+
+### Rates
+
+| 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
+
+| Command       | Description                    |
+| ------------- | ------------------------------ |
+| `ticks-from`  | Export ticks from a start date |
+| `ticks-range` | Export ticks for a date range  |
+
+### Information
+
+| Command            | Description                             |
+| ------------------ | --------------------------------------- |
+| `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)        |
+
+### 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                 |
+| `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                                             |
+| -------------- | ------------------------------------------------------- |
+| `-o, --output` | Output file path (required)                             |
+| `-f, --format` | Output format (auto-detected from extension if omitted) |
+| `--table`      | Table name for SQLite3 output (default: "data")         |
+| `--login`      | Trading account login                                   |
+| `--password`   | Trading account password                                |
+| `--server`     | Trading server name                                     |
+| `--path`       | Path to MetaTrader5 terminal EXE file                   |
+| `--timeout`    | Connection timeout in milliseconds                      |
+| `--log-level`  | Logging level (DEBUG, INFO, WARNING, ERROR)             |
+
+## Requirements
+
+- Python 3.11+
+- Windows OS (MetaTrader 5 requirement)
+- MetaTrader 5 platform
+
+## API Reference
+
+Browse the API documentation for detailed module information:
+
+- [CLI Module](api/cli.md) - CLI application with export commands and utility functions
+
+## Development
+
+This project follows strict code quality standards:
+
+- Type hints required (strict mode)
+- Comprehensive linting with Ruff
+- Test coverage tracking
+- Google-style docstrings
+
+## License
+
+MIT License - see [LICENSE](https://github.com/dceoy/mt5cli/blob/main/LICENSE) file for details.