---
name: "uforia-cli"
description: "Use this skill when the task is to inspect, query, or monitor Uforia through the public read-only `uforia` terminal client. Covers what Uforia is, how to query the main signal families, what each public signal means, how to turn those readings into trade expressions, output modes (`rich`, `--json`, `--ndjson`, `--compact`), watch mode, and the main command groups: system, overview, signals, options, perps, composite, datasets, runs, engines, and execution."
metadata:
  short-description: "Query Uforia signals and trade context"
---

# Uforia CLI

Use this skill for the public `uforia` terminal client.

## What Uforia Is

`uforia` is a research-first market-structure and trading-intelligence platform. The public CLI is a read-only client over the production API.

Core families exposed through the CLI:
- overview and health
- BTC/ETH `VVIX`
- BTC/ETH `Razor`
- options dashboards and options composite signals
- perps dashboards and perps composite signals
- BTC, ETH, and market composite state indices
- datasets, runs, engines, and read-only execution state

Use Uforia as a context, ranking, and expression-selection system. It is not an auto-execution engine and its scores should not be treated as standalone entry triggers.

Default posture:
- `uforia` is read-only and API-backed.
- Prefer `uforia`, not `uforia-admin`, unless the user explicitly asks for admin/build/ingest/maintenance work.
- If you are inside the repo, prefer `uv run uforia ...`.
- If the package is installed globally, `uforia ...` is fine.

## Quick Start

Common setup:

```bash
export UFORIA_API_BASE_URL=https://uforia.polynomial.fi
export UFORIA_TIMEOUT_SECONDS=20
```

Basic health checks:

```bash
uv run uforia system show
uv run uforia overview show --asset BTC --timeframe 15m
uv run uforia options dashboards
uv run uforia signals list
uv run uforia composite list
```

## Command Selection

Use these command groups:
- `system show`: service health and freshness
- `overview show`: market candles, latest price context, dashboard summaries
- `signals list|show`: VVIX/Razor and other signal families
- `options dashboards|show|signals`: options dashboards and options signals
- `perps dashboards|show|signals`: perps dashboards and perps signals
- `composite list|show`: composite indices, components, transitions
- `datasets list|show|rows`: dataset inventory and raw row access
- `runs list|summary`: pipeline runs and run summaries
- `engines list`: engine catalog and status
- `execution ...`: read-only execution state

## Public Signal Map

### Headline signals

- `btc_vvix`, `eth_vvix`: volatility-of-volatility views over the asset vol index and surface state. Use `qvvix_*` as implied vol-of-vol and `rvvix_*` as realized vol-of-vol once enough history exists.
- `btc_razor`, `eth_razor`: running edge between systematic short-vol and long-vol 7D ATM straddle programs. Use Razor to confirm whether selling or owning gamma has actually been paying recently, not just whether it looks optically cheap.

### Options composite signals

These are ranking and filtering scores for options structure:
- `vol_carry_score`: short-tenor carry richness and short-vol carry attractiveness
- `skew_stress_score`: crash-premium pressure and skew stress
- `surface_dislocation_score`: local smile residual and surface distortion pressure
- `cross_asset_vol_score`: BTC versus ETH relative vol richness
- `vol_regime_score`: combined VVIX, Razor, carry, and skew regime state
- `funding_vol_context_score`: funding extremity conditioned on the current vol regime
- `breakeven_gap_score`: whether realized movement is outrunning short-dated breakevens
- `term_structure_momentum_score`: acceleration or decay in front-end term pressure
- `surface_factor_score`: latent surface-factor momentum across normalized surface cells
- `residual_surface_rv_score`: residual node-level value after removing common surface moves
- `ml_carry_toxicity_score`: carry after toxicity, jump-risk, spread, and hedge-cost penalties
- `expiry_pin_score`: positive-gamma pinning strength into expiry
- `gamma_flip_score`: breakout risk when negative gamma meets distance from pain and thin flow
- `adaptive_hedge_score`: research-only hedge quality for smile-aware delta and route choice
- `sessionality_score`: UTC session, weekend, funding-window, and expiry-window regime score
- `dispersion_score`: BTC-ETH implied-correlation gap and cross-smile consistency
- `funding_skew_score`: funding and basis pressure mapped into skew richness and smile stress

### Perps composite signals

These summarize perp market structure:
- `carry_score`: composite crowding and carry richness score for perps
- `cascade_risk_score`: composite liquidation-cascade and fragility score
- `toxicity_score`: composite flow-toxicity and adverse-selection score
- `positioning_score`: composite OI divergence and leverage-pressure score
- `fragility_score`: composite spread, depth, and dislocation fragility score

### Composite market-state signals

Use `btc_composite`, `eth_composite`, and `market_composite` to separate regime from instrument choice:
- `sentiment_index` on `0-100`: fear, greed, crowding, and complacency
- `directional_tilt` on `-100..100`: bearish-to-bullish lean
- `fragility_index` on `0-100`: squeeze, cascade, and overshoot risk
- `confidence_score`: confidence in the published reading

Do not collapse these into one number. A market can be bullish and fragile, bearish and complacent, or neutral but structurally unstable.

### Dashboards versus signals

Signals are compressed summaries. Dashboards are the raw drivers behind them.

Common map:
- `vol_carry_score` -> `carry_vrp`
- `skew_stress_score` -> `skew_crash_premium`
- `surface_dislocation_score` -> `surface_dislocation`
- `cross_asset_vol_score` -> `btc_eth`
- `funding_vol_context_score` -> `funding_context`
- `breakeven_gap_score` -> `straddle_breakeven`
- `term_structure_momentum_score` -> `term_structure_momentum`
- `carry_score` -> `funding_basis_carry`
- `cascade_risk_score` -> `liquidation_cascade`
- `toxicity_score` -> `order_flow_toxicity`
- `positioning_score` -> `oi_price_divergence`
- `fragility_score` -> `depth_resilience`, `cross_venue_price_discovery`

Start from the score, then open the matching dashboard for the raw fields before forming a view.

## Output Rules

Global output flags must come before the command path:

```bash
uv run uforia --json system show
uv run uforia --ndjson datasets rows signal_series --limit 200
uv run uforia --compact overview show --asset BTC
```

Use:
- default rich output for interactive terminal inspection
- `--json` for one structured payload
- `--ndjson` for row-oriented output or piping
- `--compact` for dense, agent-friendly summaries

Recommended defaults:
- prefer `--json` for summary/detail commands
- prefer `--ndjson` for `datasets rows`
- prefer `--compact` when the user wants quick scanning over presentation

## Watch Mode

Use `--watch <seconds>` only when polling is explicitly useful.

Examples:

```bash
uv run uforia system show --watch 10
uv run uforia signals list --watch 30
uv run uforia --json runs summary --watch 60
```

Watch behavior:
- rich mode redraws
- JSON prints a full payload each cycle
- NDJSON appends lines
- `Ctrl+C` exits cleanly

## Reading Rules

- Higher is not the same as bullish. Most scores mean “more of the named condition.”
- Prefer relative interpretation over fixed thresholds unless the payload exposes explicit regime labels.
- Treat disagreement across carry, funding, VVIX, Razor, and fragility as lower conviction.
- Treat `quality_flag=partial_context` or `quality_flag=insufficient_data` as a real state, not a UI bug.
- Use the composite family for regime and stress, then the options/perps families for expression selection.

## Building Trade Expressions

A trade expression is the instrument and structure you choose after reading the regime, the driver, and the fragility of the setup.

Use this sequence:
1. Read regime: `composite show`, `signals show btc_vvix`, `signals show btc_razor`
2. Confirm the driver: open the matching options or perps dashboard
3. Choose the expression: short vol, long gamma, relative value, momentum, or hedge
4. Check blockers: fragility, funding stress, poor quality flags, or conflicting families

### Expression framework

Short-vol carry:
- Look for high `vol_carry_score`, contained `vol_regime_score`, calm or falling `qvvix`, and non-stretched `funding_vol_context_score`.
- Prefer this when `fragility_index` and perps `cascade_risk_score` are contained.
- Typical expressions: short ATM straddle, wider short strangle, short-end carry harvest.

Long gamma or long vol:
- Look for positive `breakeven_gap_score`, rising `term_structure_momentum_score`, elevated `vol_regime_score`, and strengthening `VVIX`.
- Prefer this when funding stress or fragility says short vol is crowded.
- Typical expressions: long ATM straddle, long gamma, front-end calendars when short-end repricing leads long-end repricing.

Relative-value vol:
- Look for high `surface_dislocation_score`, `cross_asset_vol_score`, `residual_surface_rv_score`, or `dispersion_score` while the broader regime is mixed.
- Prefer this when outright vol direction is unclear but local richness is obvious.
- Typical expressions: sell rich wings, buy cheap nodes, BTC-versus-ETH vol spreads, dispersion-style structures.

Perps momentum or breakout:
- Look for high `toxicity_score`, supportive cumulative delta, resilient depth, and a composite `directional_tilt` aligned with the move.
- Avoid passive fading when toxicity and fragility are both rising.
- Typical expressions: join the breakout, reduce maker-style mean reversion, bias execution toward the leading venue.

Crowding unwind or deleveraging defense:
- Look for high `carry_score`, `positioning_score`, `cascade_risk_score`, or market/composite `fragility_index`.
- Treat this as a warning that yield-looking trades may be underpricing squeeze risk.
- Typical expressions: reduce carry exposure, buy convexity, tighten risk on levered trend trades, favor unwind expressions over fresh crowding.

### Practical recipes

Short-vol carry check:

```bash
uv run uforia --json signals show btc_vvix --source dvol --range-days 3
uv run uforia --json signals show btc_razor --range-days 3
uv run uforia --json options signals
uv run uforia options show carry_vrp --underlying BTC --range-days 3
uv run uforia options show funding_context --underlying BTC --range-days 3
uv run uforia --json composite show btc_composite --range-days 3
```

Long-gamma check:

```bash
uv run uforia --json options signals
uv run uforia options show straddle_breakeven --underlying BTC --range-days 3
uv run uforia options show term_structure_momentum --underlying BTC --range-days 3
uv run uforia --json signals show btc_vvix --source dvol --range-days 3
uv run uforia --json composite show btc_composite --range-days 3
```

Perps breakout check:

```bash
uv run uforia --json perps signals
uv run uforia perps show order_flow_toxicity --asset BTC --venue-scope all
uv run uforia perps show depth_resilience --asset BTC --venue-scope all
uv run uforia perps show cum_delta_momentum --asset BTC --venue-scope all
uv run uforia --json composite show btc_composite --range-days 3
```

## High-Value Commands

Production status:

```bash
uv run uforia --json system show
uv run uforia runs summary
uv run uforia engines list
```

Overview and prices:

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

Signals:

```bash
uv run uforia signals list
uv run uforia signals show btc_vvix --source dvol --range-days 3
```

Options and perps:

```bash
uv run uforia options dashboards
uv run uforia options show vol_surface --underlying BTC --range-days 3
uv run uforia perps dashboards
uv run uforia perps show funding_basis_carry --asset BTC --venue-scope all
```

Composite:

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

Datasets:

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

Execution:

```bash
uv run uforia execution venues
uv run uforia execution markets --venue hyperliquid --asset BTC
uv run uforia execution accounts
uv run uforia execution orders --venue hyperliquid --account default --limit 50
```

## Troubleshooting

If a command fails:
- verify `UFORIA_API_BASE_URL`
- rerun with `--json` to get a clean structured response
- check `system show` first
- use `datasets rows` only with explicit limits; avoid huge pulls by default

If the trade expression is unclear:
- start from `composite show` to classify regime first
- then inspect one family at a time; do not mix options and perps conclusions without checking conflict
- prefer the dashboard over the score when a signal looks surprising
- prefer no trade over forcing a view from low-confidence or conflicting readings

Exit codes:
- `0`: success
- `1`: request failure, timeout, invalid response, or unsupported path
- `2`: invalid CLI arguments

## Source of Truth

If command details drift, check:

```bash
uv run uforia --help
uv run uforia <group> --help
```

In this repo, deeper examples live in:
- `docs/terminal-client.md`
- `docs/overview.md`
- `docs/multi-asset-vol-suite.md`
- `docs/options-signals.md`
- `docs/composite-index.md`
