Metadata-Version: 2.5
Name: filtrix-cli
Version: 0.3.0
Summary: Agent-first command-line interface for the FILTRIX backtest engine.
Project-URL: Homepage, https://filtrix.net
Project-URL: Documentation, https://pypi.org/project/filtrix-cli/
Author-email: Filtrix <team@filtrix.net>
License: MIT
License-File: LICENSE
Keywords: ai-agents,backtest,cli,filtrix,quant,screener,trading
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: platformdirs>=4
Requires-Dist: rich>=13
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# filtrix-cli

Agent-first command-line interface to [FILTRIX](https://filtrix.net) — historical trading-pattern backtesting.

## Install

```bash
pipx install filtrix-cli      # or: uvx filtrix-cli ...
```

## Authenticate

```bash
export FILTRIX_API_KEY=flt_your_key      # for every read command
filtrix auth login                       # for managing API keys (stores a JWT)
```

### Sign up (terminal)

```bash
filtrix auth register --email you@example.com --accept-tos
# FILTRIX emails a 6-digit code; paste it when prompted; you're logged in.
```

## Examples

```bash
filtrix meta                                      # outcomes, units, limits, quota (free)
filtrix filters --search "relative volume"        # find column names (no key needed)
filtrix backtest --filter "gap_gup>=50" --filter "price_price<5" --sample 5
filtrix backtest -f "gap_gup>=10" --outcome day_return --threshold 0
filtrix screen --filter "gap_gup>=50" --limit 20 --field rv_computed
filtrix --json screen --filter "gap_gup>=50"     # force JSON in a terminal
filtrix ticker NVDA                               # metadata
filtrix overview NVDA                             # price, moves, 52-week range, fundamentals
filtrix gaps TSLA --threshold 10 --direction down # this ticker's own gap history
filtrix daily AAPL --limit 60                     # daily OHLCV bars
filtrix coverage TSLA                             # how much history
filtrix premarket                                 # today's premarket gappers (free)
filtrix account
filtrix runs save -f "gap_gup>=20" -f "price_price<10" --name "Small gappers" --wait
filtrix runs list
filtrix simulate --run-id 42 --entry open_at_0930 --exit stop_loss_take_profit --sl 0.03 --tp 0.06 --wait
filtrix runs context 42 ABCD 2025-03-14            # daily + minute bars of one event
filtrix jobs get JOB_ID
filtrix keys create --name laptop
filtrix llms          # machine-readable usage guide for AI agents
```

## Output & scripting

Output is human-readable in a terminal and JSON when piped or with the global `--json` flag.
Global flags (`--json`, `--quiet`, `--profile`, `--api-key`, `--base-url`) go BEFORE the subcommand.
Exit codes: 0 ok, 2 usage, 3 not-found, 4 auth, 5 rate-limited, 6 network or `--wait` timeout, 1 server
or failed job.

`runs save` and `simulate` start background jobs; `--wait` polls until they finish. `runs delete` needs
`--yes` when not interactive.

## Configuration

Settings resolve in order: CLI flag > environment variable > config file
(`filtrix config path` shows the location). Use `--profile NAME` for multiple environments.
Credentials (API key / JWT) are stored in cleartext in this TOML file (best-effort `chmod 600` on POSIX) — treat it like an SSH key.
