# Usage Guide

This guide covers the day-to-day use of NVCurve, from launching the web UI to managing profiles and using the CLI.

## First-Time Setup

Before using NVCurve, always run the hardware compatibility check:

```bash
nvcurve setup
```

This verifies that your GPU and driver support the required NvAPI functions, performs a safe test write, and restores your GPU to its original state. Only proceed if the result is **Compatible**.

## Web UI

The web UI is the primary interface for curve editing and monitoring.

### Launching the Web UI

```bash
nvcurve
```

This starts the backend server and opens your browser at `http://127.0.0.1:8042`.

### Server Management

```bash
nvcurve serve start          # Start the web server
nvcurve serve start --detach # Start in the background
nvcurve serve status         # Check if the server is running
nvcurve serve stop           # Stop the server
```

### Curve Editor

The curve editor displays your GPU's V/F curve as an interactive graph with draggable points.

| Action | How |
|---|---|
| Select a point | Click on it |
| Multi-select | Shift+click to add/remove points |
| Select all active points | Ctrl/Cmd+A |
| Clear selection | Escape |
| Edit a point | Drag it to stage a frequency offset |
| Move multiple points | Drag with multiple points selected |
| Exact value input | Select one point, press Enter |
| Nudge ±1 MHz | Arrow keys (↑ / ↓) |
| Nudge ±10 MHz | Ctrl/Cmd + arrow keys |
| Step through points | Tab / Shift+Tab |
| Box select | Shift+drag on the background |
| Pan the graph | Drag on the background |
| Zoom | Alt+scroll |

### Point Table

The point table provides a spreadsheet-like view of all curve points with their frequency, voltage, and offset values.

| Action | How |
|---|---|
| Select a point | Click a row |
| Toggle selection | Ctrl/Cmd+click |
| Range select | Shift+click or drag across rows |
| Select before/after | Click "Select Before" or "Select After" (appears for single selection) |

### Toolbar

The toolbar provides bulk operations:

- **Global Offset Slider** — Appears when all active points share a uniform delta. Adjusts every point simultaneously.
- **Flatten** — When two or more points are selected, flattens them to the anchor point's frequency. The anchor is the last explicitly clicked point (highlighted with an amber halo).
- **Apply** — Commits staged changes to the GPU.
- **Reset** — Clears all offsets back to zero.

### Live Monitoring

The monitoring panel shows real-time GPU metrics:

- Voltage
- Clock speed
- Temperature
- Power draw

Data is streamed via WebSocket from the backend at a configurable poll interval (default: 1 second).

### Multi-GPU

When multiple NVIDIA GPUs are detected, a GPU selector dropdown appears in the status bar. Switching GPUs resets pending edits, selection state, and monitoring for the new target.

## CLI Reference

The CLI is designed for scripting, headless use, and quick operations. All write commands support `--dry-run` to preview changes.

### Reading the Curve

```bash
nvcurve read                  # Condensed V/F curve
nvcurve read --full           # All points including zeros
nvcurve read --json           # JSON output for scripting
```

### Writing Offsets

```bash
# Preview changes without applying
nvcurve write --global --delta 50 --dry-run
nvcurve write --point 80 --delta 100 --dry-run

# Apply changes
nvcurve write --global --delta 50        # All active GPU points
nvcurve write --point 80 --delta 100     # Single point
nvcurve write --range 70-90 --delta 75   # Range of points
nvcurve write --reset                    # Reset all to zero
```

> If you use LACT or similar tools, disable them before writing. Concurrent writes will overwrite each other.

### Snapshots

Snapshots are saved automatically before every write. You can also manage them manually:

```bash
nvcurve snapshot save
nvcurve snapshot list
nvcurve snapshot restore
```

Snapshots are stored in `/var/cache/nvcurve/snapshots`.

### Profiles

Profiles save a named set of curve offsets (plus optional memory offset and power limit settings). Profile commands work whether or not the server is running.

```bash
nvcurve profile save my_profile        # Save current curve state
nvcurve profile apply my_profile       # Apply a saved profile
nvcurve profile list                   # List all profiles
nvcurve profile default my_profile     # Set as auto-load on startup
nvcurve profile default --clear        # Clear auto-load setting
```

Profiles are stored as JSON files in `/etc/nvcurve/profiles`.

### Diagnostics

```bash
nvcurve read --diag                     # Full NvAPI function probe + system info
nvcurve inspect --point 80              # Raw ClockBoostTable fields
nvcurve inspect --range 78-82           # Inspect a range of points
nvcurve gpus                            # List detected GPUs
```

### Global Arguments

The `--gpu N` flag can be placed before or after any subcommand to target a specific GPU in multi-GPU setups:

```bash
nvcurve --gpu 1 read
nvcurve read --gpu 1
nvcurve --gpu 1 profile default perf
```

## Systemd Service

Install NVCurve as a systemd service for automatic profile loading on boot:

### Install

```bash
nvcurve service install
```

With optional web server auto-start:

```bash
nvcurve service install --auto-serve --host 0.0.0.0 --port 8042
```

### Manage

```bash
nvcurve service start
nvcurve service stop
nvcurve service restart
nvcurve service status
nvcurve service uninstall
```

### Reconfigure

```bash
sudo nvcurve service configure --auto-serve
sudo nvcurve service configure --no-auto-serve
sudo nvcurve service configure --host 0.0.0.0 --port 8042
```

## Configuration Files

| File | Purpose |
|---|---|
| `/etc/nvcurve/config.json` | Persistent config (host, port, auto-serve, default profiles) |
| `/etc/nvcurve/profiles/*.json` | Saved profiles |
| `/var/cache/nvcurve/snapshots/` | Auto-saved snapshots before writes |
| `/run/nvcurve.json` | Runtime server info (host, port, PID) |
| `/etc/systemd/system/nvcurve.service` | Systemd unit file |