Metadata-Version: 2.4
Name: filtrix-cli
Version: 0.1.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 backtests/screens/ticker/account
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 backtest --filter "gap_gup>=50" --filter "price_price<5"
filtrix screen --filter "gap_gup>=50" --limit 20
filtrix --json screen --filter "gap_gup>=50"     # force JSON in a terminal
filtrix ticker NVDA
filtrix filters --search gap
filtrix account
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, 1 server.

## 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.
