# Terminal Client

`uforia` is the public, read-only terminal client for Uforia.

It exposes the same API-backed analytics surfaces as the web app without browser dependencies:
- overview
- signals
- options
- perps
- composite
- datasets
- runs
- engines
- execution

It does **not** expose microstructure commands in the public terminal surface.

## Install

Local editable install:

```bash
uv sync --extra dev
uv run uforia --help
```

From PyPI:

```bash
pip install uforia
uforia --help
```

Release behavior:
- every push to `main` or `master` publishes a unique development release to PyPI
- version tags like `v0.2.0` publish the matching stable release

## Configuration

The client is API-driven and read-only. It can point at local, staging, or production environments.

Environment variables:

```bash
export UFORIA_API_BASE_URL=https://uforia.polynomial.fi
export UFORIA_TIMEOUT_SECONDS=8
export UFORIA_OUTPUT=rich
```

Equivalent command-line flags:

```bash
uforia --api-base-url https://uforia.polynomial.fi --timeout 8 system show
uforia --json system show
uforia --ndjson signals list
```

Output modes:
- default rich terminal rendering
- `--json` for a single structured payload
- `--ndjson` for row-oriented streaming output

All JSON payloads follow this top-level shape:

```json
{
  "command": "signals.show",
  "fetched_at": "2026-03-17T12:00:00+00:00",
  "filters": {
    "signal_id": "btc_vvix"
  },
  "data": {},
  "meta": {},
  "warnings": []
}
```

For `--ndjson`, each line has:

```json
{
  "command": "signals.list",
  "fetched_at": "2026-03-17T12:00:00+00:00",
  "filters": {},
  "item": {}
}
```

## Command Catalog

### System

```bash
uforia system show
uforia --json system show
uforia system show --watch 10
```

### Overview

```bash
uforia overview show --asset BTC --venue-scope binance --timeframe 15m
uforia overview show --asset ETH --range-days 3
```

### Signals

```bash
uforia signals list
uforia signals show btc_vvix --source dvol --range-days 3
uforia --json signals show btc_razor
```

### Options

```bash
uforia options dashboards
uforia options show vol_surface --underlying BTC --range-days 3
uforia options signals --underlying ETH
```

### Perps

```bash
uforia perps dashboards
uforia perps show funding_basis_carry --asset BTC --venue-scope all
uforia perps signals --asset ETH --venue-scope binance
```

### Composite

```bash
uforia composite list
uforia composite show market_composite --range-days 3
```

### Datasets

```bash
uforia datasets list
uforia datasets show signal_series
uforia datasets rows signal_series --limit 50
uforia --ndjson datasets rows signal_series --limit 200
```

### Runs

```bash
uforia runs list --limit 20
uforia runs summary
```

### Engines

```bash
uforia engines list
```

### Execution

```bash
uforia execution venues
uforia execution markets --venue hyperliquid --asset BTC
uforia execution accounts
uforia execution orders --venue hyperliquid --account default --limit 50
uforia execution fills --venue lighter --asset ETH
uforia execution positions --venue derive
uforia execution balances --account default
uforia execution health
```

## Watch Mode

Any command that supports `--watch` will poll the API repeatedly.

Examples:

```bash
uforia overview show --watch 15
uforia signals list --watch 30
uforia --json runs summary --watch 60
```

Behavior:
- rich mode clears and redraws the terminal on each poll
- JSON mode prints a full payload each cycle
- NDJSON mode appends new lines each cycle
- `Ctrl+C` exits cleanly with code `0`

## Exit Codes

- `0`: success
- `1`: request failure, timeout, invalid response, or empty/unsupported command path
- `2`: invalid CLI arguments from Typer

## Shell Completion

Typer completion is built in.

Install completion for your shell:

```bash
uforia --install-completion
```

Preview completion script:

```bash
uforia --show-completion
```

## Agent Usage Notes

Recommended defaults for automation:

```bash
uforia --json system show
uforia --json overview show --asset BTC
uforia --json signals show btc_vvix
uforia --ndjson datasets rows signal_series --limit 500
```

Guidance:
- prefer `--json` for summary/detail commands
- prefer `--ndjson` for row-oriented commands
- set `UFORIA_API_BASE_URL` once in the environment
- use `--watch` only when polling is explicitly desired

## Release

The public release workflow lives in `.github/workflows/terminal-release.yml`.

It:
- runs tests
- builds source and wheel distributions
- installs the built wheel in a clean virtualenv
- verifies `uforia --help`
- publishes a dev build to PyPI on each push to `main` or `master`
- publishes a stable build to PyPI on version tags
