Feature/tmo cli enhancement

docs/user-guide/cli.md

@@ -1,15 +1,80 @@
-# CLI (`tmoapi`)
+# CLI Tools
 
-The SDK ships with a small CLI helper named `tmoapi`. It lets you download,
-store, and explore the official Postman collection for The Mortgage Office
-without touching Python code.
+The SDK ships with multiple CLI tools for working with The Mortgage Office API:
+
+- **`tmoapi`** - API documentation and configuration management
+- **`tmopo`** - Mortgage pools operations (shares and capital)
+- **`tmols`** - Loan servicing operations (placeholder)
+- **`tmolo`** - Loan origination operations (placeholder)
+
+All CLI tools install automatically alongside the library (`pip install tmo-api`).
+
+## Configuration
+
+All TMO CLI tools use a shared configuration file at `~/.tmorc` for storing API credentials and profiles.
+
+### Initialize Configuration
+
+Create the configuration file:
 
 ```bash
-$ tmoapi --help
-usage: tmoapi [-h] {download,copy,list,show} ...
+tmoapi init
+```
+
+This creates `~/.tmorc` with a default `demo` profile that connects to the TMO API Sandbox.
+
+### Configuration File Format
+
+The `~/.tmorc` file uses INI format with named profiles:
+
+```ini
+[demo]
+token = TMO
+database = API Sandbox
+environment = us
+
+[production]
+token = YOUR_TOKEN_HERE
+database = YOUR_DATABASE_NAME
+environment = us
+timeout = 30
 ```
 
-The CLI installs automatically alongside the library (`pip install tmo-api`).
+### Using Profiles
+
+All CLI commands default to the `demo` profile. Use `-P` or `--profile` to select a different profile:
+
+```bash
+# Uses demo profile (default)
+tmopo shares pools
+
+# Use production profile
+tmopo -P production shares pools
+tmopo --profile prod shares pools
+
+# Override profile settings
+tmopo -P prod --database "Other DB" shares pools
+```
+
+### Credential Priority
+
+Credentials are resolved in this order (highest to lowest priority):
+
+1. Command-line flags (`--token`, `--database`, `--environment`)
+2. Profile from `~/.tmorc` (specified with `-P` or defaults to `demo`)
+3. Environment variables (`TMO_API_TOKEN`, `TMO_DATABASE`)
+4. Built-in demo credentials (for `demo` profile only)
+
+---
+
+## `tmoapi` - API Documentation & Config
+
+The `tmoapi` command manages API documentation and configuration.
+
+```bash
+$ tmoapi --help
+usage: tmoapi [-h] {init,download,copy,list,show} ...
+```
 
 ## Where specs are stored
 
@@ -26,7 +91,20 @@ directory until a `pyproject.toml` file is found.
 If you want to use a different file, pass `--api-spec path/to/file.json` to the
 commands that read specs.
 
-## Commands
+## `tmoapi` Commands
+
+### `init`
+
+Initialize the `~/.tmorc` configuration file with a demo profile.
+
+```bash
+tmoapi init
+tmoapi init --force  # Overwrite existing file
+```
+
+Option | Description
+------ | -----------
+`--force` | Overwrite existing configuration file
 
 ### `download`
 
@@ -90,7 +168,209 @@ you to refine the search.
     to find the name you care about, then `tmoapi show "<name>"` to see the
     request details.
 
+---
+
+## `tmopo` - Mortgage Pools Operations
+
+The `tmopo` command provides comprehensive access to mortgage pools operations, including shares and capital pools.
+
+```bash
+$ tmopo --help
+usage: tmopo [-h] [-P PROFILE] [--token TOKEN] [--database DATABASE]
+             [--environment {us,usa,can,aus}] [--debug]
+             [--user-agent USER_AGENT]
+             {shares,capital} ...
+```
+
+### Common Options
+
+Option | Description
+------ | -----------
+`-P`, `--profile` | Configuration profile to use (default: `demo`)
+`--token` | API token (overrides profile)
+`--database` | Database name (overrides profile)
+`--environment` | API environment: `us`, `canada`, or `australia` (overrides profile)
+`--debug` | Enable debug output
+`--user-agent` | Override the default User-Agent header
+
+### Shares Operations
+
+All shares pool operations support the following actions and output options.
+
+#### Output Options
+
+The `shares` subcommand supports `-O` / `--output` flag to specify output file and format:
+
+Option | Description
+------ | -----------
+`-O`, `--output` | Output file path. Format is auto-detected from extension: `.json`, `.csv`, `.xlsx`. If not specified, outputs as text to stdout.
+
+**Supported Formats:**
+
+- **Text (default)**: Human-readable table output to stdout
+- **JSON** (`.json`): Raw JSON data
+- **CSV** (`.csv`): Flattened CSV with intelligent handling of CustomFields
+- **XLSX** (`.xlsx`): Flattened Excel spreadsheet (requires `pip install tmo-api[xlsx]`)
+
+**CSV/XLSX Flattening:**
+
+- Data is flattened to 2 levels deep by default
+- CustomFields with Name/Value pairs are intelligently flattened into columns named `CustomFields_<Name>`
+- Example: `CustomFields_Account_Number`, `CustomFields_Account_Status`, `CustomFields_Interest_Rate`
+- The `raw_data` field is automatically excluded from all outputs
+
+**Examples:**
+
+```bash
+# Text output to stdout (default)
+tmopo shares pools
+
+# JSON output to file
+tmopo shares pools -O pools.json
+
+# CSV output (flattened with CustomFields as named columns)
+tmopo shares partners -O partners.csv
+
+# Excel output (requires openpyxl)
+tmopo shares pools -O pools.xlsx
+
+# Export with date filtering
+tmopo shares distributions --start-date 01/01/2024 -O distributions.csv
+```
+
+#### Pool Operations
+
+```bash
+# List all shares pools
+tmopo shares pools
+
+# Get specific pool details
+tmopo shares pools-get LENDER-C
+tmopo shares pools-get --pool LENDER-C
+
+# Get pool partners
+tmopo shares pools-partners LENDER-C
+
+# Get pool loans
+tmopo shares pools-loans LENDER-C
+
+# Get pool bank accounts
+tmopo shares pools-bank-accounts LENDER-C
+
+# Get pool attachments
+tmopo shares pools-attachments LENDER-C
+```
+
+#### Partner Operations
+
+```bash
+# List all partners (defaults to last 31 days)
+tmopo shares partners
+
+# List partners with date range
+tmopo shares partners --start-date 01/01/2024 --end-date 12/31/2024
+
+# Get specific partner details
+tmopo shares partners-get P001002
+tmopo shares partners-get --partner P001002
+
+# Get partner attachments
+tmopo shares partners-attachments P001002
+```
+
+#### Distribution Operations
+
+```bash
+# List all distributions (defaults to last 31 days)
+tmopo shares distributions
+
+# List distributions with date range
+tmopo shares distributions --start-date 01/01/2024 --end-date 12/31/2024
+
+# List distributions for specific pool
+tmopo shares distributions --pool LENDER-C
+
+# Get specific distribution details
+tmopo shares distributions-get 4ABBA93E18D945CF8BC835E7512C8B8F
+tmopo shares distributions-get --recid 4ABBA93E18D945CF8BC835E7512C8B8F
+```
+
+#### Certificate Operations
+
+```bash
+# List certificates (defaults to last 31 days)
+tmopo shares certificates
+
+# List certificates with date range
+tmopo shares certificates --start-date 01/01/2024 --end-date 12/31/2024
+
+# Filter by partner and pool
+tmopo shares certificates --partner P001001 --pool LENDER-C
+```
+
+#### History Operations
+
+```bash
+# Get transaction history (defaults to last 31 days)
+tmopo shares history
+
+# Get history with date range
+tmopo shares history --start-date 01/01/2024 --end-date 12/31/2024
+
+# Filter by partner
+tmopo shares history --partner P001001
+
+# Filter by pool
+tmopo shares history --pool LENDER-C
+
+# Combine filters
+tmopo shares history --start-date 01/01/2024 --partner P001001 --pool LENDER-C
+```
+
+### Date Filtering
+
+For operations that support date filtering (`partners`, `distributions`, `certificates`, `history`):
+
+- **No dates specified**: Defaults to last 31 days
+- **Only start date**: End date is 31 days after start date (or today, whichever is earlier)
+- **Only end date**: Start date is 31 days before end date
+- **Both dates**: Uses the specified range
+
+Date format: `MM/DD/YYYY`
+
+### Complete Examples
+
+```bash
+# Use demo profile (default) with text output
+tmopo shares pools
+
+# Use production profile
+tmopo -P production shares pools
+
+# Export to CSV with custom date range
+tmopo -P production shares partners --start-date 01/01/2024 --end-date 12/31/2024 -O partners.csv
+
+# Export distributions to Excel
+tmopo shares distributions --pool LENDER-C -O distributions.xlsx
+
+# Get history as JSON with all filters
+tmopo shares history --start-date 01/01/2024 --partner P001001 --pool LENDER-C -O history.json
+
+# Override profile settings
+tmopo -P production --database "Backup DB" shares pools -O pools.json
+```
+
+### Installation for XLSX Support
+
+To use `.xlsx` output format, install the optional `xlsx` extra:
+
+```bash
+pip install tmo-api[xlsx]
+```
+
+This installs the required `openpyxl` library for Excel file generation.
+
 ## Exit codes
 
 - `0` – success (including the "multiple matches" case for `show`)
-- `1` – user or network error (missing file, download failure, unknown command, etc.)
+- `1` – user or network error (missing file, download failure, unknown command, authentication error, etc.)

pyproject.toml

@@ -36,6 +36,7 @@ Repository = "https://github.com/inntran/tmo-api-python"
 Issues = "https://github.com/inntran/tmo-api-python/issues"
 
 [project.scripts]
+tmopo = "tmo_api.cli.tmopo:main"
 tmoapi = "tmo_api.cli.tmoapi:main"
 
 [project.optional-dependencies]
@@ -47,12 +48,19 @@ dev = [
     "isort>=5.12.0",
     "mypy>=1.0.0",
     "types-requests>=2.31.0",
+    "types-PySocks>=1.7.0",
+    "types-openpyxl>=3.1.0",
+    "types-docutils>=0.20.0",
+    "types-Pygments>=2.17.0",
 ]
 docs = [
     "mkdocs>=1.6.0",
     "mkdocs-material>=9.6.0",
     "mike>=2.1.0",
 ]
+xlsx = [
+    "openpyxl>=3.0.0",
+]
 
 [build-system]
 requires = ["hatchling"]