# 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. [Registry Commands](#registry-commands)
4. [Plugin Commands](#plugin-commands)
5. [Help Commands](#help-commands)
6. [Configuration](#configuration)
7. [Common Workflows](#common-workflows)
8. [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
```

---

## Registry Commands

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

### List All Components

```bash
vipr registry components
```

### List Specific Component Types

```bash
# List available predictors
vipr registry predictors

# List available data loaders
vipr registry data-loaders

# List available model loaders
vipr registry model-loaders

# List available hooks
vipr registry hooks

# List available filters
vipr registry 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 registry --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
```

### Config Structure

Basic YAML configuration structure:

```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]
```

**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. Develop with Custom Plugin

```bash
# List current plugins
vipr plugins list

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


```