nvcurve/docs/Usage-Guide.md

# 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.

## Authentication (Multi-User)

By default the server runs **without** authentication — anyone who can reach the port can use it. This is fine for a single-user workstation, but on a shared AI server you will want to lock it down. nvcurve uses a **dual mode**:

- **No users configured** → the API and web UI are open, exactly as before.
- **One or more users configured** → every API and WebSocket endpoint requires a login. The web UI shows a sign-in screen first.

There is no "single shared password" mode — once you add a user, each person gets their own account.

### Managing users

Users are stored as **bcrypt** hashes in `/etc/nvcurve/users.json` (mode `0600`, root-owned). Plaintext passwords are never written to disk. Manage them with the CLI (root required to add/remove/change):

```bash
# Add a user (prompts for the password twice). Never pass the password as an
# argument — it would be visible in the process list and recorded in sudo logs.
sudo nvcurve user add alice
sudo nvcurve user add bob

# List users
nvcurve user list

# Change a user's password
sudo nvcurve user set-password alice

# Remove a user
sudo nvcurve user remove bob
```

Adding the first user **switches the server into authenticated mode immediately** (no restart needed). Removing the last user switches it back to open mode.

### Signing in

- **Web UI:** open the app as usual; if authentication is enabled you will see a sign-in screen. Enter your username and password.
- **CLI / scripts:** the Python client can authenticate and reuse the session:

  ```python
  from nvcurve.client import NvCurveClient
  client = NvCurveClient(base="http://127.0.0.1:8042")
  client.login("alice", "S3cret!")   # stores the session token
  print(client.gpu())                 # subsequent calls are authorized
  ```

  Or pass a token you already have: `NvCurveClient(base=..., token="...")`.

### Sessions

- A successful login creates a session that **lasts 24 hours**, after which a new login is required.
- Browsers receive the session as an `HttpOnly` cookie; CLI/scripts use the returned token as an `Authorization: Bearer <token>` header.
- Sessions are kept in server memory, so a server restart invalidates them (users must sign in again).
- A per-IP lockout (10 failed attempts within 5 minutes → 15-minute lockout) slows down brute-force guessing.

### Security notes

- The user store file should stay root-owned and `0600` (the CLI enforces this).
- The web UI and API are still only as safe as the network path to the server — bind to a trusted interface (`--host`) and/or firewall the port. Authentication protects against casual access, not a determined network attacker.
- The `nvcurve user` commands and the user store require root; day-to-day sign-in does not.

## 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 |