pvetui

Integration tests are located in the test/integration/ directory and cover the following functional areas:

• API Client Integration: Tests client instantiation, password/token authentication, API operations (VM listing, etc.), caching behavior, and retry mechanisms.
• Configuration Integration: Tests YAML file loading, environment variable overrides, and configuration validation.
• Cache Integration: Tests both Badger (persistent) and in-memory cache operations, including complex data structures and concurrent access.
• End-to-End Workflows: Validates complete paths from configuration (YAML or Environment) through to successful API execution.

Group Mode allows you to combine several profiles into a single unified view of CPU, memory, storage, tasks, and guests.

Operating Modes

• aggregate: Combines resources from all profiles in the group.
• cluster: Used for HA-style setups. pvetui connects through one healthy profile at a time and fails over automatically.

Usage

You can launch directly into a specific group using the --profile flag:

pvetui --profile="my-group"

Note: Migrations are restricted to the VM's original cluster. If a group contains standalone nodes, migration targets will show "No other online nodes available."

Versioning

Upstream apidoc.js is unversioned. You should regenerate your OpenAPI spec whenever you upgrade Proxmox VE to ensure the documentation matches the API.

Data Normalization

• Unknown or null responses are normalized to a nullable object.
• File download endpoints are automatically mapped to application/octet-stream.

Licensing

apidoc.js is licensed under AGPLv3 as part of the Proxmox VE documentation. Because the generated OpenAPI specs are derivative works, you should keep them for internal use or comply with AGPL sharing requirements if distributing them.

You can assign profiles to groups and define how those groups behave using group_settings. This allows you to manage multiple servers as a single logical unit.

Supported modes for groups:

• aggregate (default): Merges resources from all member profiles into a single view.
• cluster: Connects through one healthy member profile at a time with automatic failover.

Set the default_profile to a profile name or a group name to determine what loads on startup.

default_profile: "all-servers"
group_settings:
  all-servers:
    mode: aggregate
  prod-ha:
    mode: cluster

Commands that trigger Proxmox tasks (such as guests create, guests migrate, storage content delete, storage download *, or storage restore) block by default until the task completes. Upon completion, they return a JSON object containing the task status.

To return the task UPID immediately without waiting for completion, use the --no-wait flag.

Example JSON output:

{
  "vmid": 105,
  "node": "pve01",
  "upid": "UPID:pve01:...",
  "status": "complete",
  "exit_status": "OK"
}

A non-"OK" exit_status will result in a non-zero process exit code.

When tests require file system interaction, use t.TempDir() to create a temporary directory. This directory is automatically cleaned up by the Go testing framework after the test completes, preventing side effects and leftover files.

func TestFileOperations(t *testing.T) {
    tempDir := t.TempDir() // Automatically cleaned up

    filePath := filepath.Join(tempDir, "test.txt")
    err := os.WriteFile(filePath, []byte("test"), 0644)
    require.NoError(t, err)

    // Test your file operations
}

pvetui uses a dual-layer theming system:

1. Terminal Emulator Layer: By default, the application uses semantic color constants that map to your terminal's ANSI palette. This allows the UI to automatically adapt to your existing terminal themes (like Dracula, Nord, or Solarized).
2. Application-Level Layer: You can override specific semantic colors in your configuration file to gain precise control over the UI appearance, regardless of your terminal's palette.

If you omit a color key in your configuration, pvetui falls back to the built-in default for that specific semantic role.

theme:
  name: nord
  colors:
    error: "#ff0000"
    background: "#2e3440"

The pvetui interface uses visual cues to communicate the state of your Proxmox environment:

• Status Indicators: Resources are color-coded by state:
  • Green: Running
  • Red: Stopped
  • Yellow: Pending
• Resource Usage: CPU, memory, and storage usage are displayed via visual bars.
• Hierarchy: The UI organizes resources into a clear hierarchy of Nodes, Guests (VMs/Containers), and Tasks.

pvetui uses semantic colors to ensure consistent meaning across different themes. Understanding these mappings helps when designing custom themes:

Status Colors

• Green: Running VMs, online nodes, successful operations
• Red: Stopped VMs, offline nodes, errors
• Yellow: Pending operations, warnings, partial failures
• Blue: Informational elements, descriptions

Resource Usage Colors

• Green: Low usage (< 50%)
• Yellow: Medium usage (50-75%)
• Red: High usage (75-90%)
• Red (bright): Critical usage (> 90%)

UI Element Colors

• Primary: Main text and important information
• Secondary: Supporting text and labels
• Border: Separators and borders
• Selection: Selected items and focus indicators