### Basic API Client Setup

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCUMENTATION.md

A minimal example showing the standard workflow for initializing the pvetui API client, including configuration loading, logger setup, and basic VM list retrieval.

```go
cfg := config.NewConfig()
cfg.ParseFlags()
cfg.SetDefaults()
if err := cfg.Validate(); err != nil {
	log.Fatal("Invalid configuration:", err)
}
loggerInstance, err := logger.NewInternalLogger(logger.LevelInfo, cfg.CacheDir)
defer loggerInstance.Close()
configAdapter := adapters.NewConfigAdapter(cfg)
loggerAdapter := adapters.NewLoggerAdapter(cfg)
client, err := api.NewClient(configAdapter, api.WithLogger(loggerAdapter))
ctx := context.Background()
vms, err := client.GetVmList(ctx)
```

--------------------------------

### Robust API Client Setup with Error Handling

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCUMENTATION.md

A production-ready example that includes comprehensive error handling, fallback logging, context timeouts, and safe iteration over VM resource data.

```go
cfg := config.NewConfig()
cfg.ParseFlags()
cfg.SetDefaults()
if err := cfg.Validate(); err != nil {
	return
}
loggerInstance, err := logger.NewInternalLogger(logger.LevelInfo, cfg.CacheDir)
if err != nil {
	loggerInstance = logger.NewSimpleLogger(logger.LevelInfo)
}
defer loggerInstance.Close()
client, err := api.NewClient(adapters.NewConfigAdapter(cfg), api.WithLogger(adapters.NewLoggerAdapter(cfg)))
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
vms, err := client.GetVmList(ctx)
for _, vm := range vms {
	vmid := api.SafeStringValue(vm["vmid"])
	log.Printf("VM %s", vmid)
}
```

--------------------------------

### Configure pvetui Profiles

Source: https://context7.com/devnullvoid/pvetui/llms.txt

Example YAML configuration showing multi-profile setup, authentication methods, and key bindings.

```yaml
profiles:
  default:
    addr: "https://pve.example.com:8006"
    user: "root"
    realm: "pam"
    password: "your-password"
    insecure: false
  work:
    addr: "https://work-pve.example.com:8006"
    user: "admin"
    token_id: "automation"
    token_secret: "secret-token-value"
    realm: "pam"
    insecure: true

default_profile: "default"

key_bindings:
  switch_view: "]"
  quit: "q"
```

--------------------------------

### Development Setup and Workflow Commands

Source: https://github.com/devnullvoid/pvetui/blob/master/AGENTS.md

Provides essential make commands for setting up the development environment, running code quality checks, building the project, and executing tests. Includes commands for installing pre-commit hooks and managing the noVNC subtree.

```bash
make dev-setup
make update-novnc
pre-commit install
make build
make code-quality
make test
make test-integration
make clean
```

--------------------------------

### Installation

Source: https://github.com/devnullvoid/pvetui/blob/master/cmd/pve-openapi-gen/README.md

Instructions on how to install the pve-openapi-gen tool using Go.

```APIDOC
## Installation

### Description
Install the pve-openapi-gen tool using the Go package manager.

### Method
`go install`

### Endpoint
`github.com/devnullvoid/pvetui/cmd/pve-openapi-gen@latest`

### Parameters

#### Query Parameters
- **@latest** (string) - Required - Installs the latest version from the repository.
- **@<commit>** (string) - Optional - Installs a specific commit or tag.

### Request Example
```bash
go install github.com/devnullvoid/pvetui/cmd/pve-openapi-gen@latest
```

### Response
#### Success Response (200)
- **Installation Complete** (string) - The tool is successfully installed and ready for use.

#### Response Example
```
Installed:
  github.com/devnullvoid/pvetui/cmd/pve-openapi-gen
```
```

--------------------------------

### Install pvetui using Go Install (Latest)

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/TROUBLESHOOTING.md

Installs the latest version of pvetui using the `go install` command. This command fetches and compiles the specified package, including its dependencies. Ensure your Go environment is set up correctly.

```bash
go install github.com/devnullvoid/pvetui/cmd/pvetui@latest
```

--------------------------------

### Proxmox Mock API - Getting Started

Source: https://github.com/devnullvoid/pvetui/blob/master/cmd/pve-mock-api/README.md

Instructions on how to generate the OpenAPI spec and run the Proxmox Mock API server.

```APIDOC
## Proxmox Mock API - Getting Started

This section covers the initial setup and execution of the Proxmox Mock API server.

### Setup

1. **Generate OpenAPI Spec:**
   ```bash
   make gen-openapi
   ```

2. **Run Mock Server:**
   ```bash
   go run ./cmd/pve-mock-api -spec docs/api/pve-openapi.yaml -port 8080
   ```

### Running Integration Tests

To run the integration/regression suite against the mock API:

```bash
make gen-openapi   # If docs/api/pve-openapi.yaml is outdated
make test-mock     # Spins up the mock inside the tests on port 8086
```
```

--------------------------------

### Install pvetui CLI

Source: https://github.com/devnullvoid/pvetui/blob/master/skills/pvetui-cli/SKILL.md

Instructions for installing the pvetui CLI tool via Go or a compatible agent.

```bash
go install github.com/devnullvoid/pvetui/cmd/pvetui@latest
npx skills add devnullvoid/pvetui
```

--------------------------------

### Run pvetui with Configuration Wizard

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/TROUBLESHOOTING.md

Launches the pvetui application with an interactive configuration wizard. This is useful for initial setup or when creating a new configuration file, guiding the user through the necessary settings.

```bash
./pvetui --config-wizard
```

--------------------------------

### Install pvetui via CLI

Source: https://context7.com/devnullvoid/pvetui/llms.txt

Commands to install the pvetui binary using Go or various system package managers.

```bash
go install github.com/devnullvoid/pvetui/cmd/pvetui@latest
yay -S pvetui-bin
brew install --cask devnullvoid/pvetui/pvetui
scoop bucket add pvetui https://github.com/scoop-pvetui
scoop install pvetui
```

--------------------------------

### Viewing Documentation - Web Interface

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCUMENTATION.md

Instructions on how to install and run `godoc` to serve documentation locally via a web browser.

```APIDOC
## Viewing Documentation - Web Interface

Generate and serve HTML documentation locally:

```bash
# Install godoc if not already installed
go install golang.org/x/tools/cmd/godoc@latest

# Serve documentation on http://localhost:6060
godoc -http=:6060

# Then navigate to:
# http://localhost:6060/pkg/github.com/devnullvoid/pvetui/
```
```

--------------------------------

### Install pvetui using Go Toolchain on macOS

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/TROUBLESHOOTING.md

Installs pvetui directly using the Go toolchain after cloning the repository. This is recommended for developers and compiles the source code with vendored dependencies.

```bash
git clone https://github.com/devnullvoid/pvetui.git
cd pvetui
make install-go
# or: go install ./cmd/pvetui
```

--------------------------------

### Serve Go Documentation Locally (Bash)

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCUMENTATION.md

Instructions for installing and running the 'godoc' tool to serve Go documentation locally via HTTP. This allows for interactive browsing of the project's documentation.

```bash
# Install godoc if not already installed
go install golang.org/x/tools/cmd/godoc@latest

# Serve documentation on http://localhost:6060
godoc -http=:6060

# Then navigate to:
# http://localhost:6060/pkg/github.com/devnullvoid/pvetui/
```

--------------------------------

### POST /guests/{vmid}/start

Source: https://context7.com/devnullvoid/pvetui/llms.txt

Start a stopped VM or container.

```APIDOC
## POST /guests/{vmid}/start

### Description
Starts a specific VM or container by ID.

### Method
POST

### Endpoint
pvetui guests start {vmid}

### Parameters
#### Path Parameters
- **vmid** (integer) - Required - The ID of the guest to start.

### Response
#### Success Response (200)
- **vmid** (integer) - The ID of the guest.
- **upid** (string) - The unique process ID for the task.

#### Response Example
{
  "vmid": 100,
  "upid": "UPID:pve01:00001234:12345678:6789ABCD:qmstart:100:root@pam:"
}
```

--------------------------------

### Create Basic API Client (Go)

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCUMENTATION.md

Shows the basic instantiation of the pvetui API client using a configuration object. This is the starting point for interacting with the Proxmox VE API.

```go
// Basic client
client, err := api.NewClient(config)
```

--------------------------------

### API Reference - Client Creation

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCUMENTATION.md

Examples showing how to create a new pvetui client, with options for custom logger and cache.

```APIDOC
## API Reference - Client Creation

```go
// Basic client
client, err := api.NewClient(config)

// Client with custom logger and cache
client, err := api.NewClient(config,
    api.WithLogger(logger),
    api.WithCache(cache))
```
```

--------------------------------

### Build pvetui from Source on macOS

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/TROUBLESHOOTING.md

Installs pvetui by cloning the repository and using the `make install` command. This method compiles the source code locally, bypassing macOS Gatekeeper issues. It ensures the noVNC client is properly vendored.

```bash
git clone https://github.com/devnullvoid/pvetui.git
cd pvetui
make install
```

--------------------------------

### Install pve-openapi-gen via Go

Source: https://github.com/devnullvoid/pvetui/blob/master/cmd/pve-openapi-gen/README.md

Installs the latest version of the pve-openapi-gen CLI tool directly from the GitHub repository using the Go toolchain.

```bash
go install github.com/devnullvoid/pvetui/cmd/pve-openapi-gen@latest
```

--------------------------------

### Quick Usage

Source: https://github.com/devnullvoid/pvetui/blob/master/cmd/pve-openapi-gen/README.md

A quick guide to generating an OpenAPI YAML file from the Proxmox VE API documentation.

```APIDOC
## Quick Use

### Description
Generate an OpenAPI 3.0 specification file in YAML format from Proxmox VE's `apidoc.js`.

### Method
`pve-openapi-gen`

### Endpoint
`/` (Command Line Tool)

### Parameters

#### Query Parameters
- **-out** (string) - Required - Specifies the output file path for the OpenAPI specification (e.g., `pve-openapi.yaml`).
- **-version** (string) - Required - Sets the version label in the `info.version` field of the OpenAPI spec (e.g., `pve-9.x`).

### Request Example
```bash
pve-openapi-gen \
  -out pve-openapi.yaml \
  -version "pve-9.x"   # label in info.version
```

### Response
#### Success Response (200)
- **OpenAPI Spec Generated** (string) - An OpenAPI 3.0 specification file is created at the specified output path.

#### Response Example
```yaml
openapi: 3.0.0
info:
  version: "pve-9.x"
  title: "Proxmox VE API"
# ... rest of the OpenAPI spec
```
```

--------------------------------

### Configure pvetui Environment Variables

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCKER.md

Example configuration for the .env file required to connect the containerized application to a Proxmox server.

```bash
PVETUI_ADDR=https://your-proxmox-server:8006
PVETUI_USER=root
PVETUI_PASSWORD=your-password
PVETUI_REALM=pam
PVETUI_DEBUG=false
PVETUI_CACHE_DIR=/app/cache
```

--------------------------------

### Utilize Mock and Test Helpers

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/TESTING.md

Examples of initializing and using various mock and test utility objects provided by the testutils package for dependency injection and state verification.

```go
mockLogger := &testutils.MockLogger{}
mockLogger.On("Debug", mock.Anything, mock.Anything).Return()

mockCache := &testutils.MockCache{}
mockCache.On("Get", "key", mock.Anything).Return(true, nil)
mockCache.On("Set", "key", "value", time.Hour).Return(nil)

mockConfig := &testutils.MockConfig{}
mockConfig.On("GetAddr").Return("https://test.com")

config := testutils.NewTestConfig()
tokenConfig := testutils.NewTestConfigWithToken()

logger := testutils.NewTestLogger()
logger.Debug("test message")
assert.Contains(t, logger.DebugMessages[0], "test message")

cache := testutils.NewInMemoryCache()
cache.Set("key", "value", time.Hour)
```

--------------------------------

### Password Authentication Manager (Go)

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCUMENTATION.md

Example of creating an authentication manager using a password for the Proxmox Virtual Environment API client. It initializes the manager with an HTTP client, credentials, and a logger.

```go
// Password-based authentication
authManager := api.NewAuthManagerWithPassword(httpClient, "root", "password", logger)
```

--------------------------------

### API Token Authentication Manager (Go)

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCUMENTATION.md

Example of creating an authentication manager using an API token for the Proxmox Virtual Environment API client. It initializes the manager with an HTTP client, token, and a logger.

```go
// API token authentication
authManager := api.NewAuthManagerWithToken(httpClient, "PVEAPIToken=...", logger)
```

--------------------------------

### API Reference - Authentication

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCUMENTATION.md

Code examples demonstrating how to authenticate using either password or API tokens with the `AuthManager`.

```APIDOC
## API Reference - Authentication

```go
// Password-based authentication
authManager := api.NewAuthManagerWithPassword(httpClient, "root", "password", logger)

// API token authentication
authManager := api.NewAuthManagerWithToken(httpClient, "PVEAPIToken=...", logger)

// Ensure authentication
err := authManager.EnsureAuthenticated()
```
```

--------------------------------

### Define pvetui Configuration Profiles

Source: https://github.com/devnullvoid/pvetui/blob/master/README.md

Example YAML configuration showing how to define multiple Proxmox connection profiles, authentication methods, and SSH jump host settings.

```yaml
profiles:
  default:
    addr: "https://your-proxmox-host:8006"
    user: "your-user"
    realm: "pam"
    token_id: "your-token-id"
    token_secret: "your-secret"
    ssh_jump_host:
      addr: "jump.example.com"
      port: 2222
  work:
    addr: "https://work-proxmox:8006"
    token_id: "worktoken"
    token_secret: "worksecret"
    groups:
      - all-servers

default_profile: "all-servers"
plugins:
  enabled:
    - "ansible"
    - "community-scripts"
```

--------------------------------

### Manage pvetui with Docker Compose

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCKER.md

Recommended commands for starting the interactive TUI session using Docker Compose, including cleanup and log management.

```bash
docker compose run --rm pvetui
docker-compose down
docker-compose logs -f
```

--------------------------------

### Setting Up Proxmox Environment for Integration Tests

Source: https://github.com/devnullvoid/pvetui/blob/master/AGENTS.md

Guides users on resolving integration test failures by ensuring the Proxmox test environment is correctly set up. This involves setting the 'PVETUI_INTEGRATION_TEST' environment variable and configuring the '.env.test' file, or using the mock server.

```bash
export PVETUI_INTEGRATION_TEST=true
# Configure .env.test
```

--------------------------------

### Get pvetui Help Information

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/TROUBLESHOOTING.md

Displays the help message for the pvetui command-line tool. This output includes information about available flags, configuration file paths, and usage instructions.

```bash
./pvetui --help
```

--------------------------------

### Go Documentation Standard Template

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCUMENTATION.md

Provides the official documentation structure for Go packages and functions, including parameter descriptions, return values, and usage examples to ensure consistent API documentation.

```go
// PackageName provides functionality for specific purpose.
package packagename

// FunctionName performs a specific operation with the given parameters.
//
// Parameters:
//   - param1: Description of first parameter
//   - param2: Description of second parameter
//
// Returns the result or an error if the operation fails.
func FunctionName(param1 string, param2 int) (string, error) {
    return "", nil
}
```

--------------------------------

### Define Resource Limits in docker-compose.yml

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCKER.md

Example configuration from a docker-compose.yml file showing how to set resource limits (memory and CPU) for the pvetui service. These limits help manage resource consumption.

```yaml
deploy:
  resources:
    limits:
      memory: 256M
      cpus: '0.5'
    reservations:
      memory: 64M
      cpus: '0.1'
```

--------------------------------

### Initialize and Validate Configuration

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCUMENTATION.md

Demonstrates how to instantiate the configuration object, parse command-line flags, merge settings from a YAML file, apply defaults, and validate the final configuration state.

```go
config := config.NewConfig()
config.ParseFlags()
err := config.MergeWithFile("config.yml")
config.SetDefaults()
err = config.Validate()
```

--------------------------------

### Run pvetui from Command Line (Bash)

Source: https://github.com/devnullvoid/pvetui/blob/master/README.md

Demonstrates how to launch the pvetui application from the command line, with options to specify a custom configuration file.

```bash
# Auto-detects config at ~/.config/pvetui/config.yml
./pvetui

# Or specify custom config
./pvetui --config /path/to/config.yml
```

--------------------------------

### Test Cache Set and Get Operations (Go)

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/TESTING.md

Tests the basic functionality of an in-memory cache, specifically the Set and Get operations. It ensures that data can be stored with an expiration time and retrieved correctly. Dependencies include the 'time' package.

```Go
func TestCache_SetAndGet(t *testing.T) {
    cache := NewInMemoryCache()

    key := "test-key"
    value := "test-value"

    // Test Set
    err := cache.Set(key, value, time.Hour)
    assert.NoError(t, err)

    // Test Get
    var result string
    found, err := cache.Get(key, &result)
    assert.NoError(t, err)
    assert.True(t, found)
    assert.Equal(t, value, result)
}
```

--------------------------------

### Create API Client with Custom Options (Go)

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCUMENTATION.md

Illustrates how to create an API client with custom logger and cache implementations. This allows for tailored logging and caching strategies.

```go
// Client with custom logger and cache
client, err := api.NewClient(config,
    api.WithLogger(logger),
    api.WithCache(cache))
```

--------------------------------

### GET /guests

Source: https://context7.com/devnullvoid/pvetui/llms.txt

List all guests or filter by status using a specific profile.

```APIDOC
## GET /guests

### Description
Lists all guests in the cluster. Supports filtering by status and profile.

### Method
GET

### Endpoint
pvetui --profile [profile] guests list --status [status]

### Parameters
#### Query Parameters
- **profile** (string) - Optional - The configuration profile to use.
- **status** (string) - Optional - Filter guests by status (e.g., running, stopped).

### Response
#### Success Response (200)
- **id** (integer) - The VMID of the guest.
- **name** (string) - The guest hostname.
- **status** (string) - Current power state.

#### Response Example
[
  {
    "id": 100,
    "name": "webserver",
    "status": "running"
  }
]
```

--------------------------------

### Perform Guest Lifecycle Operations

Source: https://github.com/devnullvoid/pvetui/blob/master/skills/pvetui-cli/SKILL.md

Commands to start, stop, shutdown, or restart Proxmox guests using their VMID.

```bash
pvetui guests start 100
pvetui guests shutdown 100
pvetui guests stop 100
pvetui guests restart 100
```

--------------------------------

### View Go Package Documentation (Bash)

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCUMENTATION.md

Demonstrates how to use the 'go doc' command to view documentation for specific packages, functions, or all exported items within a package. It also shows how to view documentation with the source code.

```bash
# View package documentation
go doc pkg/api
go doc internal/config
go doc pkg/api/interfaces

# View specific function documentation
go doc pkg/api FormatBytes
go doc pkg/api AuthManager.GetValidToken

# View detailed documentation for all exported items
go doc -all pkg/api

# View documentation with source code
go doc -src pkg/api FormatBytes
```

--------------------------------

### Manage Guest Lifecycle

Source: https://context7.com/devnullvoid/pvetui/llms.txt

Perform power operations on guests including start, stop, shutdown, and restart. These commands return a UPID for tracking.

```bash
# Start
pvetui guests start 100
# Force Stop
pvetui guests stop 100
# Graceful Shutdown
pvetui guests shutdown 100
# Restart
pvetui guests restart 100
```

--------------------------------

### Configure Passwordless Sudo for PCT

Source: https://github.com/devnullvoid/pvetui/blob/master/README.md

Example sudoers configuration to allow non-root users to execute pct commands without password prompts.

```text
youruser ALL=(ALL) NOPASSWD: /usr/sbin/pct enter *, /usr/sbin/pct exec *
```

--------------------------------

### Manage Guests (VMs and Containers) via CLI

Source: https://github.com/devnullvoid/pvetui/blob/master/README.md

Commands to list, filter, and control guest lifecycle states. Includes functionality to execute commands directly within guests via the QEMU guest agent.

```bash
# List all guests
pvetui guests list
pvetui guests list --output table

# Filter by node, status, or type
pvetui guests list --node pve01 --status running --type qemu

# Show a specific guest
pvetui guests show 100

# Lifecycle operations
pvetui guests start 100
pvetui guests shutdown 100
pvetui guests stop 100
pvetui guests restart 100

# Execute command in guest
pvetui guests exec 100 "uptime"
pvetui guests exec 200 "df -h" --timeout 60s
```

--------------------------------

### Apply Catppuccin Mocha Theme

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/THEMING.md

Provides a complete example of overriding the default pvetui theme with the Catppuccin Mocha color palette for a consistent, modern aesthetic.

```yaml
theme:
  colors:
    primary: "#cdd6f4"
    secondary: "#bac2de"
    tertiary: "#a6adc8"
    success: "#a6e3a1"
    warning: "#f9e2af"
    error: "#f38ba8"
    info: "#89b4fa"
    background: "#1e1e2e"
    border: "#45475a"
    selection: "#585b70"
    header: "#313244"
    headertext: "#f5e0dc"
    footer: "#313244"
    footertext: "#cdd6f4"
    title: "#b4befe"
    contrast: "#313244"
    morecontrast: "#181825"
    inverse: "#1e1e2e"
    statusrunning: "#a6e3a1"
    statusstopped: "#f38ba8"
    statuspending: "#f9e2af"
    statuserror: "#f38ba8"
    usagelow: "#a6e3a1"
    usagemedium: "#f9e2af"
    usagehigh: "#fab387"
    usagecritical: "#f38ba8"
```

--------------------------------

### Viewing Documentation - Command Line

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCUMENTATION.md

Demonstrates how to use the `go doc` command to view package and function documentation directly from the terminal.

```APIDOC
## Viewing Documentation - Command Line

Use Go's built-in documentation tools to view documentation:

```bash
# View package documentation
go doc pkg/api
go doc internal/config
go doc pkg/api/interfaces

# View specific function documentation
go doc pkg/api FormatBytes
go doc pkg/api AuthManager.GetValidToken

# View detailed documentation for all exported items
go doc -all pkg/api

# View documentation with source code
go doc -src pkg/api FormatBytes
```
```

--------------------------------

### Configure pvetui via Environment Variables

Source: https://context7.com/devnullvoid/pvetui/llms.txt

Setting up Proxmox connection details, authentication, and SSH settings using environment variables prefixed with PVETUI_.

```bash
export PVETUI_ADDR="https://pve.example.com:8006"
export PVETUI_USER="root"
export PVETUI_REALM="pam"
export PVETUI_PASSWORD="your-password"
export PVETUI_TOKEN_ID="mytoken"
export PVETUI_TOKEN_SECRET="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export PVETUI_SSH_USER="root"
export PVETUI_VM_SSH_USER="ubuntu"
export PVETUI_SSH_JUMPHOST_ADDR="jump.example.com"
export PVETUI_INSECURE="true"
export PVETUI_DEBUG="true"
pvetui nodes list
```

--------------------------------

### Update Environment Variables Prefix

Source: https://github.com/devnullvoid/pvetui/blob/master/CHANGELOG.md

This example shows how to update environment variables from the old 'PROXMOX_' prefix to the new 'PVETUI_' prefix. This is necessary for the project's rebranding and trademark compliance.

```bash
# Example: Change PROXMOX_HOST to PVETUI_HOST
```

--------------------------------

### Common pvetui Agent Patterns and Queries

Source: https://github.com/devnullvoid/pvetui/blob/master/skills/pvetui-cli/SKILL.md

Demonstrates common use cases for pvetui, including listing guests by status and type, retrieving IP addresses, checking guest status, running health checks, filtering guests by tags, aggregating node resources, and monitoring task completion.

```bash
# Find all running VMs on a specific node
pvetui guests list --node pve01 --status running --type qemu

# Get IP addresses of all running guests
pvetui guests list --status running | jq '.[].ip'

# Check if a specific guest is running
pvetui guests show 100 | jq -r '.status'

# Run a health check across multiple guests
for vmid in 100 101 102; do
  echo "=== $vmid ==="
  pvetui guests exec $vmid "systemctl is-active nginx"
done

# Find guests with a specific tag
pvetui guests list | jq '[.[] | select(.tags | contains("prod"))]'

# Get total memory across all nodes
pvetui nodes list | jq '[.[].memory_total] | add'

# Monitor a task until completion (poll tasks list)
pvetui tasks list --recent 5 | jq '.[] | select(.upid == "UPID:...")'
```

--------------------------------

### Running Basic Tests in pvetui (Bash)

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/TESTING.md

Commands to execute tests within the pvetui project using make and go test. Includes options for running all tests, tests with coverage, specific packages, verbose output, and parallel execution.

```bash
make test

make test-coverage

go test ./internal/config

go test -v ./...

go test -run TestConfig_Validate ./internal/config

go test -parallel 4 ./...
```

--------------------------------

### Initialize and Run Proxmox Mock API

Source: https://github.com/devnullvoid/pvetui/blob/master/cmd/pve-mock-api/README.md

Commands to generate the OpenAPI specification and launch the mock server. The server requires a valid OpenAPI YAML file and a specified port to listen for incoming requests.

```bash
make gen-openapi
go run ./cmd/pve-mock-api -spec docs/api/pve-openapi.yaml -port 8080
```

--------------------------------

### List Guests via CLI

Source: https://context7.com/devnullvoid/pvetui/llms.txt

Commands to list VMs and containers with filtering options for node, status, and type.

```bash
pvetui guests list
pvetui guests list --node pve01 --status running
pvetui guests list --type qemu --output table
pvetui guests list --type lxc --status stopped
```

--------------------------------

### Run pvetui with Mock Profile

Source: https://github.com/devnullvoid/pvetui/blob/master/scripts/e2e/golden/pvetui-mock.txt

This command executes the pvetui application using the 'mock' profile. It demonstrates setting the PVETUI_CONFIG environment variable before running the binary. This is useful for testing or development environments where a mock configuration is needed.

```bash
PVETUI_CONFIG=${PVETUI_CONFIG} ./bin/pvetui --profile mock

```

--------------------------------

### Serve Embedded Files with Go HTTP (Go)

Source: https://github.com/devnullvoid/pvetui/blob/master/internal/vnc/README.md

Example of how the VNC server uses Go's `http.FS` to serve embedded noVNC files from memory. This is a key part of the self-contained VNC integration.

```go
internal/vnc/server.go
```

--------------------------------

### Customize Cache Directory

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/CONFIGURATION.md

Specify a custom location for pvetui's cache files. The `cache_dir` setting overrides the platform's default cache directory. Paths starting with '~' are expanded to the user's home directory.

```yaml
cache_dir: "/custom/cache/path"
```

--------------------------------

### pvetui API Token Authentication Setup

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/CONFIGURATION.md

Illustrates how to configure pvetui to use Proxmox API tokens for authentication. This method requires splitting the token ID provided by Proxmox into separate user, realm, and token ID fields in the configuration.

```yaml
profiles:
  default:
    addr: "https://your-proxmox-host:8006"
    user: "root"          # from user@realm!tokenid → user
    realm: "pam"          # from user@realm!tokenid → realm
    token_id: "mytoken"   # from user@realm!tokenid → tokenid
    token_secret: "YOUR_SECRET"
    insecure: false
    ssh_user: "root"
    vm_ssh_user: "root"
    ssh_jump_host:
      addr: "jump.example.com"
      port: 2222
```

--------------------------------

### Troubleshoot pvetui Container Startup

Source: https://github.com/devnullvoid/pvetui/blob/master/docs/DOCKER.md

Commands to check the logs of a running pvetui container to diagnose startup issues. Supports both Docker and Podman.

```bash
# Check logs
docker logs pvetui
# or
podman logs pvetui
```

--------------------------------

### Initialize and Connect VNC with RFB.js

Source: https://github.com/devnullvoid/pvetui/blob/master/internal/vnc/novnc/vnc_lite.html

This snippet demonstrates how to initialize the RFB object to establish a VNC connection. It reads connection parameters from the URL query string, constructs the WebSocket URL, and sets up event listeners for connection events. Dependencies include the RFB.js library.

```javascript
let rfb;

function status(text) {
    document.getElementById('status').textContent = text;
}

function readQueryVariable(name, defaultValue) {
    const re = new RegExp('.\[?&\' + name + '=(\[^&#\]\*)'),
        match = document.location.href.match(re);
    if (match) {
        return decodeURIComponent(match[1]);
    }
    return defaultValue;
}

const host = readQueryVariable('host', window.location.hostname);
let port = readQueryVariable('port', window.location.port);
const password = readQueryVariable('password');
const path = readQueryVariable('path', 'websockify');

let url;
if (window.location.protocol === "https:") {
    url = 'wss';
} else {
    url = 'ws';
}
url += '://' + host;
if(port) {
    url += ':' + port;
}
url += '/' + path;

rfb = new RFB(document.getElementById('screen'), url, {
    credentials: { password: password }
});

rfb.addEventListener("connect", connectedToServer);
rfb.addEventListener("disconnect", disconnectedFromServer);
rfb.addEventListener("credentialsrequired", credentialsAreRequired);
rfb.addEventListener("desktopname", updateDesktopName);

rfb.viewOnly = readQueryVariable('view_only', false);
rfb.scaleViewport = readQueryVariable('scale', false);
```