# VIPR Framework - CLI Reference

Complete command reference for the VIPR command-line interface.

## Table of Contents
1. [Command Overview](#command-overview)
2. [Inference Commands](#inference-commands)
3. [Compare Commands](#compare-commands)
4. [Registry Commands](#registry-commands)
5. [Plugin Commands](#plugin-commands)
6. [Help Commands](#help-commands)
7. [Configuration](#configuration)
8. [Common Workflows](#common-workflows)
9. [Troubleshooting](#troubleshooting)

---

## Command Overview

```bash
vipr [OPTIONS] COMMAND [ARGS]
```

**Global Options:**
- `--config PATH` - Path to configuration file (required for most commands)
- `--version` - Show VIPR version
- `--help` - Show help message

---

## Inference Commands

### Run Inference

Execute the full inference workflow with the specified configuration.

```bash
vipr --config <path-to-config> inference run
```

**Examples:**

```bash
# Using package notation
vipr --config @vipr_reflectometry/reflectorch/examples/configs/PTCDI-C3.yaml inference run

# Using relative path
vipr --config ./config.yaml inference run

# Using absolute path
vipr --config /path/to/config.yaml inference run
```

**Example configs shipped in `vipr-framework/examples/` (selection):**

- `Fe_Pt_DN_Reflectorch_narrow_bounds.yaml` - Fe/Pt (spin-down) with narrow first-layer thickness prior
- `Fe_Pt_DN_Reflectorch_broad_bounds.yaml` - Fe/Pt (spin-down) with broad first-layer thickness prior
- `Fe_Pt_DN_NSF.yaml` - Fe/Pt example using the NSF model setup
- `PTCDI-C3_Reflectorch.yaml` - deterministic Reflectorch workflow for PTCDI-C3 X-ray reflectivity

For the full and up-to-date list of example configs, see `vipr-framework/examples/README.md`.

If you are running from the `vipr-framework` repository root, you can use:

```bash
vipr --config ./examples/Fe_Pt_DN_Reflectorch_narrow_bounds.yaml inference run
```

---

## Compare Commands

Compare existing stored results without rerunning inference.

### Run Compare

```bash
vipr compare run --results <result-a> <result-b> [<result-c> ...]
```

**Examples:**

```bash
# Compare two stored results by full ID
vipr compare run --results 3a2d7b6e-... 51f9b3c1-...

# Compare using unambiguous short prefixes
vipr compare run --results 3a2d7b6e 51f9b3c1

# Use a YAML config
vipr --config ./examples/Fe_Pt_DN_compare.yaml compare run

# Set an explicit result ID for the generated compare result
vipr compare run --results RESULT_A RESULT_B --result-id my_compare_run
```

**Compare example config shipped in `vipr-framework/examples/`:**

- `Fe_Pt_DN_compare.yaml` - Compare the stored results `Fe_Pt_DN_Reflectorch_narrow_bounds`, `Fe_Pt_DN_Reflectorch_broad_bounds`, and `Fe_Pt_DN_NSF`

**CLI Options:**

- `--results` - Stored result IDs or unambiguous short UUID prefixes to compare
- `--result-id` - Optional explicit result ID for the stored compare result

**Config-based compare fields:**

```yaml
compare:
  results:
    - Fe_Pt_DN_Reflectorch_narrow_bounds
    - Fe_Pt_DN_Reflectorch_broad_bounds
    - Fe_Pt_DN_NSF
  result_id: Fe_Pt_DN_compare
  overlay:
    series_kinds:
      - polished
    include_experimental: true
```

**Notes:**

- Compare requires at least two distinct stored results.
- CLI values override `compare.results` and `compare.result_id` from YAML config.
- The generated compare output is stored as a normal result with `result_kind = compare`.

---

## Registry Commands

Query the component registry to discover available handlers, filters, and hooks.

### List All Components

```bash
vipr discovery components
```

### List Specific Component Types

```bash
# List available predictors
vipr discovery predictors

# List available data loaders
vipr discovery data-loaders

# List available model loaders
vipr discovery model-loaders

# List available hooks
vipr discovery hooks

# List available filters
vipr discovery filters
```

### Filter by Plugin

```bash
# Show only components from specific plugin
vipr discovery predictors --plugin reflectometry
```

### Show Plugin Summary

```bash
vipr discovery plugins
```

---

## Plugin Commands

### List Installed Plugins

```bash
vipr plugins list
```

Shows all plugins currently installed in your environment.

---

## Help Commands

### General Help

```bash
vipr --help
```

### Command-Specific Help

```bash
# Inference help
vipr inference --help

# Registry help
vipr discovery --help

# Plugins help
vipr plugins --help
```

---

## Configuration

### Config Path Formats

VIPR supports three configuration path formats:

#### 1. Package Notation
Access configs bundled with plugins using `@package/path` syntax:

```bash
vipr --config @vipr_reflectometry/reflectorch/examples/configs/PTCDI-C3.yaml inference run
```

#### 2. Relative Path
Paths relative to your current working directory:

```bash
vipr --config ./my-configs/config.yaml inference run
```

#### 3. Absolute Path
Full filesystem paths:

```bash
vipr --config /home/user/vipr/configs/config.yaml inference run
```

### Inference Config Structure

Basic YAML structure for `vipr --config ... inference run`:

```yaml
vipr:
  inference:
    # Data loading
    load_data:
      handler: csv_spectrareader
      parameters:
        data_path: './data.txt'
        column_mapping:
          q: 0
          I: 1
    
    # Model loading
    load_model:
      handler: reflectorch
      parameters:
        config_name: b_mc_point_xray_conv_standard_L2_InputQ
    
    # Preprocessing filters
    filters:
      INFERENCE_PREPROCESS_PRE_FILTER:
        - class: vipr_reflectometry.reflectorch.preprocess.interpolation_filter.InterpolationFilter
          method: preprocess_interpolate
          enabled: true
    
    # Prediction
    prediction:
      handler: reflectorch_predictor
      parameters:
        polish_prediction: true
        prior_bounds:
          roughnesses: [[0, 20], [0, 15], [0, 15]]
          slds: [[10, 13], [20, 21], [20, 21]]
          thicknesses: [[1, 400], [1, 10]]
          q_shift: [-0.002, 0.002]
          r_scale: [0.9, 1.1]
```

This example shows an inference configuration under `vipr.inference`. Compare-specific YAML uses the top-level `compare:` section shown in the [Compare Commands](#compare-commands) section above.

**Key Sections:**
- `load_data`: Specifies data source and format
- `load_model`: Defines which ML model to use
- `filters`: Custom preprocessing/postprocessing hooks
- `prediction`: Inference execution parameters

---

## Common Workflows

### 1. Test Installation

```bash
# Run example
vipr --config @vipr_reflectometry/reflectorch/examples/configs/PTCDI-C3.yaml inference run

# Check results
ls storage/results/
```

### 2. Run with Custom Data

```bash
# Create custom config (modify data_path)
cp example-config.yaml my-config.yaml

# Edit my-config.yaml to point to your data file

# Run inference
vipr --config ./my-config.yaml inference run
```

### 3. Explore Available Components

```bash
# See all available components
vipr discovery components

# Check specific component types
vipr discovery predictors
vipr discovery data-loaders

# Filter by plugin
vipr discovery predictors --plugin reflectometry
```

### 4. Compare Existing Results

```bash
# First generate inference results
vipr --config ./Fe_Pt_DN_Reflectorch_narrow_bounds.yaml inference run
vipr --config ./Fe_Pt_DN_Reflectorch_broad_bounds.yaml inference run
vipr --config ./Fe_Pt_DN_NSF.yaml inference run

# Then compare the stored outputs
vipr --config ./Fe_Pt_DN_compare.yaml compare run
```

### 5. Develop with Custom Plugin

```bash
# List current plugins
vipr plugins list

# Install your plugin
pip install -e /path/to/your/plugin
```
