CLI Reference

CLI Reference

The CLI is built with Typer and lives in src/trading_system/cli.py. All commands accept --help to display full usage; the tables below summarise the defaults and artifacts you should expect.

Shared conventions

• --config / --config-path (or TS_CONFIG_PATH) must point to a YAML configuration file.
• --holdings (or TS_HOLDINGS_PATH) accepts a holdings JSON snapshot.
• --asof / --as-of (or TS_ASOF) expects an ISO date (YYYY-MM-DD). Omit it to use today.
• --dry-run disables outbound notifications and skips writing certain files (where noted).
• All commands emit structured JSON logs when run via ts run (see Observability).

Pipeline commands

ts run daily

Option	Description
--config	Config file (required).
--holdings	Holdings snapshot (required).
--asof	As-of date (defaults to today).
--dry-run	Skip deliveries while still writing artifacts.
--force	Overwrite curated/report outputs if they already exist.
--channel	Notification channels (email, slack, all).
--log-to-file/--no-log-to-file	Write structured logs to reports/<asof>/run.log.

Example:

TS_HOLDINGS_PATH=data/sample-holdings.json \
poetry run ts run daily --config data/sample.yaml --asof 2024-09-23 --dry-run

Artifacts: data/raw/<date>/*.parquet, data/curated/<date>/*.parquet, reports/<date>/daily_report.{json,html}, reports/<date>/risk_alerts.json, reports/<date>/manifest.json, reports/<date>/run.log.

ts run rebalance

Same options as run daily. Adds signal generation and rebalance proposal steps.

Example:

TS_HOLDINGS_PATH=data/sample-holdings.json \
poetry run ts run rebalance --config configs/sample-config.yml --asof 2024-09-27 --dry-run --force

Artifacts: everything from the daily run plus reports/<date>/signals.parquet and reports/<date>/rebalance_proposal.json when cadence conditions pass.

Risk commands

ts risk evaluate

Evaluate crash/drawdown rules and write risk_alerts.json without running the full pipeline.

Option	Description
--config	Config file.
--holdings	Holdings snapshot.
--asof	As-of date.
--output	Optional path to write the JSON payload (defaults under reports/<date>/).

Example:

poetry run ts risk evaluate --config data/sample.yaml --holdings data/sample-holdings.json --asof 2024-09-23

ts risk explain

Print rule evaluations for a single symbol in tabular form.

Option	Description
--config	Config file.
--holdings	Holdings snapshot.
--symbol	Required ticker symbol.
--asof	As-of date.

Example:

poetry run ts risk explain --config configs/sample-config.yml --holdings data/holdings.json --symbol NVDA --asof 2024-09-23

Report commands

ts report build

Render HTML/JSON reports from previously generated artifacts. Ideal when you want to reformat without rerunning upstream steps.

Option	Description
--config	Config file.
--holdings	Holdings snapshot.
--asof	As-of date.
--risk	Override path to risk_alerts.json.
--proposal	Override path to rebalance_proposal.json.
--signals	Override path to signals.parquet.
--include-pdf	Render a PDF alongside HTML/JSON (requires a wkhtmltopdf-compatible renderer).

Example:

poetry run ts report build --config data/sample.yaml --holdings data/sample-holdings.json --asof 2024-09-23 --include-pdf

ts report preview

Shortcut that rebuilds the report, prints a summary, and optionally opens HTML in a browser.

Option	Description
--open/--no-open	Open the HTML file after rendering.

Example:

poetry run ts report preview --config configs/sample-config.yml --holdings data/holdings.json --asof 2024-09-23 --open

Signal commands

ts signals build

Evaluate strategy rules and write signals.parquet (ranked by strategy.rank).

Option	Description
--config	Config file.
--asof	As-of date.
--window	Optional trailing window size for inputs (defaults to full lookback).
--dry-run	Evaluate in-memory without writing the parquet file.

Example:

poetry run ts signals build --config configs/sample-config.yml --asof 2024-09-27

ts signals explain

Print the latest signal evaluation for a single symbol and expose derived indicators.

Option	Description
--config	Config file.
--symbol	Symbol to explain.
--asof	As-of date.
--window	Optional trailing window for the explanation (defaults to 252 days).

Example:

poetry run ts signals explain --config configs/sample-config.yml --symbol MSFT --asof 2024-09-27

Backtest commands

ts backtest run

Execute deterministic backtests driven by the active config.

Option	Description
--config	Config file.
--start / --end	Backtest window (required).
--output	Directory for artifacts (metrics JSON, equity curve, trades, optional chart).
--label	Label appended to output filenames.
--seed	Override RNG seed.

Example:

poetry run ts backtest run --config configs/sample-config.yml --start 2018-01-01 --end 2024-09-23 --output reports/backtests/smoke --label smoke

ts backtest compare

Compare two backtest outputs and print deltas.

Option	Description
--baseline	Path to baseline backtest directory or metrics.json.
--candidate	Path to candidate backtest directory or metrics.json.

Example:

poetry run ts backtest compare --baseline reports/backtests/base --candidate reports/backtests/experiment

Notification commands

ts notify send

Dispatch notifications using existing report artifacts.

Option	Description
--config	Config file (for notify settings).
--asof	As-of date.
--channel	email, slack, or all.
--dry-run	Render payloads without sending them (recommended while onboarding).

Example:

poetry run ts notify send --config data/sample.yaml --asof 2024-09-23 --channel slack --dry-run

ts notify preview

Print the payloads that would be delivered. Uses the same options as notify send minus --dry-run (always a dry run).

Observability commands

ts observability manifest

Validate a run directory’s manifest.json, recompute hashes, and print the QA summary.

Option	Description
--run	Path to reports/<date> or to manifest.json.

Example:

poetry run ts observability manifest --run reports/2024-09-23

ts observability tail

Stream the structured JSON logs (run.log) for a pipeline run.

Option	Description
--run	Path to reports/<date> or run.log.

Utility commands

• ts steps – list orchestrated steps with their expected artifacts.
• ts doctor – check required tooling (poetry, python, black, ruff, mypy, pytest).
• ts info / ts version – print project summary or package version.
• ts data providers – list raw data providers and their availability.

All commands respect Typer auto-completion (poetry run ts --install-completion). See Pipelines to understand how these commands fit together end-to-end.