Metadata-Version: 2.4
Name: flareforge-cli
Version: 0.2.0
Summary: FlareForge CLI: FDC mock proofs, FTSOv2 backtests, FAssets risk from the terminal.
Project-URL: Homepage, https://flareforge.io
Project-URL: Documentation, https://flareforge.io/docs
Project-URL: Changelog, https://flareforge.io/changelog
Author: FlareForge
License: Copyright (c) FlareForge. All rights reserved.
        
        This package (flareforge-cli) is a thin client for the public HTTP API at
        https://flareforge.io/api. The source code is published for transparency
        and convenience; redistribution and modification are not permitted.
        
        Permitted use:
        
        1. Install and run the `flareforge` command locally to interact with the
           hosted FlareForge services.
        2. Quote short snippets of this source for commentary, review, and
           documentation purposes.
        
        Not permitted without written permission from the licensor:
        
        1. Redistributing this package under any name on any package index.
        2. Publishing forks, derivative works, or modified versions.
        3. Removing or obscuring this notice.
        
        The hosted FlareForge API remains available to anyone, subject to the
        rate limits and terms published on https://flareforge.io.
        
        No warranty. The software is provided "as is", without warranty of any
        kind, express or implied. The authors and copyright holders are not
        liable for any claim, damages, or other liability arising from the use
        of the software.
License-File: LICENSE
Keywords: blockchain,fassets,fdc,flare,ftso,state-connector
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Description-Content-Type: text/markdown

# flareforge-cli

Terminal companion for [FlareForge](https://flareforge.io). Generates mock
Flare Data Connector proofs for Foundry/Hardhat tests, simulates FTSOv2
data-provider strategies against mainnet consensus, and queries live FAssets
liquidation risk. Everything hits the public `flareforge.io` API, no auth,
no API key.

## Install

```bash
pipx install flareforge-cli
flareforge --version
```

Prefer pip? `pip install flareforge-cli` works the same, just not isolated.

## Quickstart

```bash
# Oracle Lab
flareforge oracle feeds
flareforge oracle backtest \
    --feed-id 0x014254432f55534400000000000000000000000000 \
    --source kraken:8:1.0 \
    --source binance:6:1.5 \
    --aggregation weighted_mean \
    --hours 720

# FAssets risk (live from flareforge.io indexer)
flareforge agents risk

# CrossChain Sandbox — offline FDC proofs for local tests
flareforge sandbox init
flareforge sandbox types
flareforge sandbox generate Payment --source XRP --field transactionId=0x01
flareforge sandbox run scenarios.yaml
```

## Commands

### Oracle Lab

| Command | Purpose |
| --- | --- |
| `flareforge oracle feeds` | Table of every active FTSOv2 feed with its latest value. |
| `flareforge oracle backtest --feed-id X --source NAME:JITTER_BPS:WEIGHT [...] [--aggregation ...] [--hours N]` | Simulate a data-provider strategy against `hours` of mainnet consensus. Prints tier A / B / OUT rate, reward score, median deviation. See [the API guide](https://flareforge.io/docs/ftso-backtester) for the full request shape. |

### FAssets Agent Monitor

| Command | Purpose |
| --- | --- |
| `flareforge agents risk` | Aggregate liquidation-risk summary (safe / warning / danger / critical / unknown) plus worst offenders, computed from vault collateral cushion over mintingCR. See [the Python guide](https://flareforge.io/docs/fassets-risk) for Discord webhook integration. |

### CrossChain Sandbox (FDC mocks)

| Command | Purpose |
| --- | --- |
| `flareforge sandbox init [DIR]` | Copy a starter `scenarios.yaml` into DIR (cwd by default). |
| `flareforge sandbox types` | List every attestation type the sandbox can mock. |
| `flareforge sandbox generate TYPE --source SRC [--field K=V ...] [--out FILE]` | Generate one mock proof, print or write JSON. Covers Payment, EVMTransaction, AddressValidity, ConfirmedBlockHeightExists. |
| `flareforge sandbox run PATH` | Run every scenario in `scenarios.yaml` and print a pass/fail table. CI-friendly: exits non-zero on any failure. |

Every command accepts `--endpoint URL` to target a self-hosted FlareForge
backend instead of `https://flareforge.io/api`.

## scenarios.yaml schema

```yaml
endpoint: https://flareforge.io/api   # optional, overrides the default host

scenarios:
  - name: fasset-mint-payment-xrp
    type: Payment                     # attestation type_id
    source: XRP                       # source chain id
    params:
      transactionId: "0x..."          # request body fields
      inUtxo: 0
      utxo: 0
```

Five templates ship inside the package (FAssets mint, FAssets redemption,
AddressValidity, ConfirmedBlockHeightExists, EVMTransaction). Drop one with
`flareforge sandbox init`.

## Links

- Dashboard: [flareforge.io](https://flareforge.io)
- Written guides: [flareforge.io/docs](https://flareforge.io/docs) — full
  FTSOv2, FAssets, and FDC walkthroughs covering the same endpoints this CLI
  wraps.
- Changelog: [flareforge.io/changelog](https://flareforge.io/changelog) +
  [Atom feed](https://flareforge.io/feed.xml).

## Local development

```bash
git clone <your-fork> flareforge
cd flareforge/cli
uv pip install -e '.[dev]'
pytest
ruff check .
mypy src
```

## License

Business Source License 1.1. See `LICENSE` for the full text. In short: free
for non-production use and evaluation; production use of the hosted
FlareForge services is the licensor's exclusive right until the conversion
date, after which the code reverts to Apache 2.0.
