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:

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

nvcurve

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

Server Management

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

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

Writing Offsets

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

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.

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

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:

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

nvcurve service install

With optional web server auto-start:

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

Manage

nvcurve service start
nvcurve service stop
nvcurve service restart
nvcurve service status
nvcurve service uninstall

Reconfigure

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