Metadata-Version: 2.4
Name: quantcentral-cli
Version: 0.1.0
Summary: Quantcentral.ai command-line client (qc) — manage backtest runs, results, and credentials from the terminal.
Project-URL: Homepage, https://quantcentral.ai
Project-URL: Repository, https://github.com/QuantCentral-ai/quantcentral-cli
Project-URL: Issues, https://github.com/QuantCentral-ai/quantcentral-cli/issues
Author-email: Eric Vaillancourt <eric.vaillancourt@talsom.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: backtesting,cli,quant,quantcentral,trading
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# quantcentral-cli

[![PyPI version](https://img.shields.io/pypi/v/quantcentral-cli.svg)](https://pypi.org/project/quantcentral-cli/)
[![Python versions](https://img.shields.io/pypi/pyversions/quantcentral-cli.svg)](https://pypi.org/project/quantcentral-cli/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

> Command-line client for the [Quantcentral.ai](https://quantcentral.ai) platform — manage backtest runs, results, and credentials from the terminal.

Part of the [Quantcentral.ai](https://quantcentral.ai) ecosystem.

## Install

```bash
pip install quantcentral-cli
```

Requires Python 3.12+. Provides a single executable: `qc`.

## Quickstart

```bash
# 1. Point qc at your control-api deployment (default: http://localhost:8080).
qc auth set-url https://api.quantcentral.ai

# 2. Save your bearer token. Issued by control-api / SSO.
qc auth login                         # prompts (hidden input)

# 3. Verify.
qc auth status

# 4. Submit a run.
qc run create ./run-bundle.json --start

# 5. Watch.
qc run list
qc run show <run-id>

# 6. Pull results.
qc run result <run-id> --output result.json
```

## Commands

| Command | Purpose |
|---|---|
| `qc auth login` | Store the bearer token (JWT) issued by control-api. |
| `qc auth logout` | Remove the stored token. |
| `qc auth status` | Show the configured API URL and the JWT subject (no signature check). |
| `qc auth set-url <url>` | Persist the control-api URL. |
| `qc run create <bundle.json>` | POST a run bundle to `/v1/runs`. Use `--start` to start immediately. |
| `qc run start <run-id>` | Start a created run. |
| `qc run cancel <run-id>` | Cancel a running run. |
| `qc run list` | List recent runs (Rich table). |
| `qc run show <run-id>` | Print run metadata as JSON. |
| `qc run result <run-id>` | Fetch the result JSON; `--output PATH` writes to file. |

## Configuration

| Path / env | Purpose |
|---|---|
| `~/.config/quantcentral/token` | Bearer token (mode 600). |
| `~/.config/quantcentral/config.toml` | `[api] url = "..."` |
| `$QC_CONFIG_DIR` | Override config directory (useful for tests / CI). |
| `$QC_API_URL` | Override API base URL (takes precedence over disk). |
| `$QC_TOKEN` | Override bearer token (takes precedence over disk). |

## Roadmap

`v0.1.0` ships the `auth` and `run` subcommand families — enough to drive a full
backtest lifecycle against control-api. Future versions are planned to add:

| Subcommand | Status |
|---|---|
| `qc strategy scaffold/validate/push` | v0.2 — scaffolds strategies using `quantcentral-sdk`'s `StrategyBase`. |
| `qc optim sweep/show` | v0.2 — parameter optimization sweeps. |
| `qc feed list/test` | v0.3 — data feed inspection. |
| `qc broker list/test` | v0.3 — broker connectivity check. |
| `qc mcp inspect` | v0.3 — local MCP tool introspection. |

## License

**Apache-2.0** — see [LICENSE](LICENSE) for details. Attribution requirements in [NOTICE](NOTICE).

## Development

```bash
git clone git@github.com:QuantCentral-ai/quantcentral-cli.git
cd quantcentral-cli
python -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
pytest
```

Tracking: <https://github.com/QuantCentral-ai/quantcentral-planning>
