### Interactive First-Time Setup

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLI_REFERENCE.md

Initiate the interactive installation wizard for a first-time setup of ProxSave.

```bash
./build/proxsave --install
```

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

### Clone Repository and Setup

Source: https://github.com/tis24dev/proxsave/blob/main/docs/DEVELOPER_GUIDE.md

Clone the Proxsave repository, install dependencies, build the project, and run tests.

```bash
# Clone from GitHub
git clone https://github.com/tis24dev/proxsave.git
cd proxsave

# Install dependencies
go mod tidy

# Build
make build

# Run tests
go test ./...
```

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

### Full Reset and Installation

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLI_REFERENCE.md

Perform a complete reset of the installation while preserving the environment and identity. Use this for a clean setup.

```bash
# Full reset + installation (preserves env/identity)
./build/proxsave --new-install
```

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

### Install Prerequisites for Building from Source

Source: https://github.com/tis24dev/proxsave/blob/main/docs/INSTALL.md

Installs Go, rclone, git, and make. Verifies their installations by checking their versions.

```bash
# Install Go (if building from source)
wget https://go.dev/dl/go1.25.11.linux-amd64.tar.gz
tar -C /usr/local -xzf go1.25.11.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

# Install rclone (for cloud storage)
curl https://rclone.org/install.sh | bash

# Install git
apt update && apt install -y git

# Install make
apt update && apt install -y make

# Verify installations
go version    # Should show go1.25.11+
rclone version  # Should show rclone v1.50+
git --version # Should show git 2.47.3+
make --version # Should show make 4.4.1+
```

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

### New Installation with Environment Preservation

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLI_REFERENCE.md

Perform a new installation by wiping the install directory while preserving the build, environment, and identity, then run the wizard.

```bash
./build/proxsave --new-install
```

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

### First-Time Installation

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLI_REFERENCE.md

Run the initial installation of Proxsave. This command sets up the necessary files and configurations for first-time use.

```bash
# First-time installation
./build/proxsave --install
```

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

### Run Interactive Installation Wizard

Source: https://github.com/tis24dev/proxsave/blob/main/docs/INSTALL.md

Launches the interactive installation wizard to create the configuration file. Use --new-install for a clean reinstall.

```bash
./build/proxsave --install
```

```bash
# Or perform a clean reinstall (keeps build/, env/, and identity/)
./build/proxsave --new-install
```

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

### Configuring CLOUD_REMOTE with rclone (MinIO Example)

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CONFIGURATION.md

Illustrates the setup for CLOUD_REMOTE using rclone, specifically with a MinIO backend. This involves configuring rclone with a remote name and then specifying the remote and path.

```bash
rclone config
CLOUD_REMOTE=minio + CLOUD_REMOTE_PATH=/backups
```

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

### Manual rclone Installation

Source: https://github.com/tis24dev/proxsave/blob/main/docs/TROUBLESHOOTING.md

Manually install rclone by downloading the binary, extracting it, and copying it to the system's PATH.

```bash
wget https://downloads.rclone.org/rclone-current-linux-amd64.zip
unzip rclone-current-linux-amd64.zip
sudo cp rclone-*/rclone /usr/local/bin/
sudo chmod 755 /usr/local/bin/rclone
```

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

### Install and Verify rclone

Source: https://github.com/tis24dev/proxsave/blob/main/docs/TROUBLESHOOTING.md

Install rclone using the official script and verify its installation and PATH configuration.

```bash
# Install rclone
curl https://rclone.org/install.sh | sudo bash

# Verify
rclone version
which rclone
```

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

### Install ProxSave Configuration

Source: https://github.com/tis24dev/proxsave/blob/main/docs/TROUBLESHOOTING.md

Run the installer to create the default configuration file if it's missing or in the wrong location. For a clean reinstall, use the --new-install flag.

```bash
./build/proxsave --install
# For a clean reinstall (keeps env/ and identity/), run:
# ./build/proxsave --new-install
```

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

### Interactive Installation Wizard

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLI_REFERENCE.md

Initiate the interactive installation process for ProxSave. Supports both TUI (default) and CLI modes for debugging.

```bash
# Interactive installation wizard (TUI mode - default)
./build/proxsave --install
```

```bash
# Interactive installation wizard (CLI mode - for debugging)
./build/proxsave --install --cli
```

```bash
# Clean reinstall (wipes install dir except build/env/identity, then runs wizard)
./build/proxsave --new-install
```

```bash
# Clean reinstall with CLI mode
./build/proxsave --new-install --cli
```

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

### Direct Install ProxSave

Source: https://github.com/tis24dev/proxsave/blob/main/docs/INSTALL.md

Installs ProxSave using a script from GitHub. Use the --new-install flag for a clean reinstall.

```bash
bash -c "$(curl -fsSL https://raw.githubusercontent.com/tis24dev/proxsave/main/install.sh)"
```

```bash
bash -c "$(curl -fsSL https://raw.githubusercontent.com/tis24dev/proxsave/main/install.sh)" _ --new-install
```

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

### Install Rclone

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLOUD_STORAGE.md

Installs the rclone utility on a new server, which is a prerequisite for restoring configurations and backups from cloud storage.

```bash
apt-get update && apt-get install rclone
```

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

### Install and Test Proxsaves

Source: https://github.com/tis24dev/proxsave/blob/main/docs/EXAMPLES.md

Steps to install Proxsaves, configure it by editing the environment file, and perform a dry run to test the configuration before the first actual backup.

```bash
# 1. Install
./build/proxsave --install
# (use --new-install to wipe everything except build/, env/, and identity/ before installing)

# 2. Edit configuration
nano configs/backup.env
# (paste configuration above)

# 3. Test
./build/proxsave --dry-run

# 4. Run first backup
./build/proxsave
```

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

### Run First Backup

Source: https://github.com/tis24dev/proxsave/blob/main/docs/INSTALL.md

Executes the ProxSave binary to perform the first backup after installation.

```bash
./build/proxsave
```

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

### Test Encryption Setup

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLI_REFERENCE.md

Verify that the encryption setup is correct by generating new encryption keys. This is a prerequisite for encrypted backups.

```bash
# Test encryption setup
./build/proxsave --newkey
```

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

### Restore Workflow Example

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLI_REFERENCE.md

Example command for restoring from a backup. It is strongly advised to test restore operations in a controlled environment like a VM before applying to a production system.

```bash
# Restore workflow (test in VM first!)
./build/proxsave --restore
```

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

### Linux: Verify and Install Proxsave

Source: https://github.com/tis24dev/proxsave/blob/main/docs/PROVENANCE_VERIFICATION.md

This script downloads the Proxsave binary for Linux, verifies its attestation using GitHub CLI, makes it executable, and installs it to /usr/local/bin. Ensure GitHub CLI is installed and authenticated.

```bash
#!/bin/bash
set -e

# 1. Download the binary
echo "Downloading binary..."
wget -q https://github.com/tis24dev/proxsave/releases/download/v0.9.0/proxsave-linux-amd64

# 2. Verify the attestation
echo "Verifying attestation..."
if gh attestation verify proxsave-linux-amd64 --repo tis24dev/proxsave; then
    echo "✓ Attestation verified successfully!"
else
    echo "✗ Attestation verification failed!"
    rm proxsave-linux-amd64
    exit 1
fi

# 3. Make executable
chmod +x proxsave-linux-amd64

# 4. Move to /usr/local/bin
sudo mv proxsave-linux-amd64 /usr/local/bin/proxsave

echo "Installation complete!"
proxsave --version

```

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

### Minimal proxsave Cloud Storage Configuration

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLOUD_STORAGE.md

Enable cloud storage and specify the rclone remote name and path for backups. This is the basic setup required to start using cloud storage.

```bash
# Enable cloud storage
CLOUD_ENABLED=true
# rclone remote NAME (from `rclone config`)
CLOUD_REMOTE=GoogleDrive
# Full path (or prefix) inside the remote
CLOUD_REMOTE_PATH=/proxsave/backup

# Retention
MAX_CLOUD_BACKUPS=30
```

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

### Install GitHub CLI on Windows with winget

Source: https://github.com/tis24dev/proxsave/blob/main/docs/PROVENANCE_VERIFICATION.md

Installs the GitHub CLI on Windows using the winget package manager.

```powershell
winget install --id GitHub.cli
```

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

### Prepare New Hardware for Proxmox VE

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLUSTER_RECOVERY.md

Install Proxmox VE on the new hardware, set the same hostname and IP address as the old hardware, and reboot to apply network configuration.

```bash
# 1. Install Proxmox VE
# (Fresh installation)

# 2. Set SAME hostname as old hardware
hostnamectl set-hostname <old-hostname>

# 3. Configure SAME IP address
vi /etc/network/interfaces
# Set same IP as old hardware

# 4. Reboot to apply network config
reboot
```

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

### Install GitHub CLI on Debian/Ubuntu

Source: https://github.com/tis24dev/proxsave/blob/main/docs/PROVENANCE_VERIFICATION.md

Installs the GitHub CLI on Debian-based or Ubuntu systems using apt.

```bash
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh
```

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

### Start PVE Cluster Services

Source: https://github.com/tis24dev/proxsave/blob/main/docs/RESTORE_TECHNICAL.md

Executes systemctl commands to start the PVE cluster services: pve-cluster, pvedaemon, pveproxy, and pvestatd. Returns an error if any service fails to start.

```go
func startPVEClusterServices(ctx context.Context, logger *logging.Logger) error {
    commands := [][]string{
        {"systemctl", "start", "pve-cluster"},
        {"systemctl", "start", "pvedaemon"},
        {"systemctl", "start", "pveproxy"},
        {"systemctl", "start", "pvestatd"},
    }
    for _, cmd := range commands {
        if err := runCommand(ctx, logger, cmd[0], cmd[1:]...); err != nil {
            return fmt.Errorf("failed to start %s: %w", cmd[2], err)
        }
    }
    return nil
}
```

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

### Check Prerequisites

Source: https://github.com/tis24dev/proxsave/blob/main/docs/DEVELOPER_GUIDE.md

Verify that Go, make, and optional tools like rclone and age are installed and accessible.

```bash
# Go 1.25 or later
go version

# Build tools
make --version

# Optional: rclone for cloud storage development
rclone version

# Optional: age for encryption development
age --version
```

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

### macOS: Verify and Install Proxsave (Homebrew Alternative)

Source: https://github.com/tis24dev/proxsave/blob/main/docs/PROVENANCE_VERIFICATION.md

This script downloads the Proxsave binary for macOS, verifies its provenance using GitHub CLI, and installs it to /usr/local/bin. It serves as an alternative to Homebrew installation. Ensure GitHub CLI is installed and authenticated.

```bash
#!/bin/bash
set -e

VERSION="v0.9.0"
BINARY="proxsave-darwin-$(uname -m)"
URL="https://github.com/tis24dev/proxsave/releases/download/${VERSION}/${BINARY}"

# Download
echo "Downloading ${BINARY}..."
curl -L -o proxsave "${URL}"

# Verify
echo "Verifying provenance..."
gh attestation verify proxsave --repo tis24dev/proxsave || {
    echo "Verification failed!"
    rm proxsave
    exit 1
}

# Install
chmod +x proxsave
sudo mv proxsave /usr/local/bin/
echo "Installed successfully!"

```

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

### Interface Modes for Installation

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLI_REFERENCE.md

Specify the interface mode for the installation wizard. CLI mode is useful for debugging or when TUI rendering issues occur.

```bash
# TUI mode (default) - terminal interface
./build/proxsave --install
```

```bash
# CLI mode - text prompts (for debugging)
./build/proxsave --install --cli
```

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

### Automatic Migration Tool Output Example

Source: https://github.com/tis24dev/proxsave/blob/main/docs/MIGRATION_GUIDE.md

This is an example of the output you might see when running the automatic migration tool, detailing variable status and backup information.

```text
✓ Migrated 45 variables (SAME category)
✓ Converted 12 variables (RENAMED category)
⚠ Review required: 2 variables (SEMANTIC CHANGE)
  - STORAGE_WARNING_THRESHOLD_PRIMARY → MIN_DISK_SPACE_PRIMARY_GB
  - CLOUD_BACKUP_PATH → CLOUD_REMOTE_PATH
ℹ Skipped 18 legacy variables (LEGACY category)

Configuration written to: /opt/proxsave/configs/backup.env
Backup saved to: /opt/proxsave/configs/backup.env.bak-20251117-143022

⚠ IMPORTANT: Review SEMANTIC CHANGE variables before running backup!

Next step: ./build/proxsave --dry-run
```

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

### Maximum Compression for Archival Example

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CONFIGURATION.md

Example configuration for maximum compression, ideal for archival purposes when storage space is limited. Utilizes all available CPU cores.

```bash
COMPRESSION_TYPE=xz
COMPRESSION_LEVEL=9
COMPRESSION_MODE=ultra
COMPRESSION_THREADS=0  # Use all CPU cores
```

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

### Install GitHub CLI on Windows with Scoop

Source: https://github.com/tis24dev/proxsave/blob/main/docs/PROVENANCE_VERIFICATION.md

Installs the GitHub CLI on Windows using the Scoop package manager.

```powershell
scoop install gh
```

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

### Example Dry-Run Output

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLI_REFERENCE.md

This output demonstrates the information provided during a dry-run of the configuration migration, showing what would be migrated, converted, or skipped, without making any system changes.

```bash
[DRY-RUN] Reading legacy Bash configuration: /opt/proxsave/env/backup.env
[DRY-RUN] Parsing 89 variables from legacy file...

[DRY-RUN] Migration summary:
✓ Would migrate 45 variables (SAME category)
✓ Would convert 12 variables (RENAMED category)
⚠ Manual review required: 2 variables (SEMANTIC CHANGE)
  - STORAGE_WARNING_THRESHOLD_PRIMARY → MIN_DISK_SPACE_PRIMARY_GB
    Bash: "90" (90% used) → Go: needs GB value (e.g., "10")
  - CLOUD_BACKUP_PATH → CLOUD_REMOTE_PATH
    Bash: "/gdrive:backups/folder" → Go: "backups/folder" (prefix only)
ℹ Would skip 18 legacy variables (LEGACY category)

[DRY-RUN] No files created or modified (preview mode)

✓ Dry-run complete. Run without --dry-run to execute migration.
```

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

### No Compression Example

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CONFIGURATION.md

Configuration to disable compression, recommended for data that is already compressed.

```bash
COMPRESSION_TYPE=none
```

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

### Install GitHub CLI on Fedora/RHEL/CentOS

Source: https://github.com/tis24dev/proxsave/blob/main/docs/PROVENANCE_VERIFICATION.md

Installs the GitHub CLI on Fedora, RHEL, or CentOS systems using dnf.

```bash
sudo dnf install gh
```

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

### Install GitHub CLI on Arch Linux

Source: https://github.com/tis24dev/proxsave/blob/main/docs/PROVENANCE_VERIFICATION.md

Installs the GitHub CLI on Arch Linux systems using pacman.

```bash
sudo pacman -S github-cli
```

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

### Remote Format Examples

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CONFIGURATION.md

Provides examples of the `<remote-name>:<path>` format for configuring rclone remotes, including different cloud providers and path structures.

```bash
gdrive:pbs-backups
```

```bash
s3:my-bucket/backups
```

```bash
minio:/pbs
```

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

### Install and Use Mermaid CLI

Source: https://github.com/tis24dev/proxsave/blob/main/docs/RESTORE_DIAGRAMS.md

Install the mermaid-cli globally and use it to generate PNG or SVG images from markdown files containing Mermaid diagrams.

```bash
npm install -g @mermaid-js/mermaid-cli

# Generate PNG
mmdc -i docs/RESTORE_DIAGRAMS.md -o diagrams/

# Generate SVG
mmdc -i docs/RESTORE_DIAGRAMS.md -o diagrams/ -t svg
```

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

### Force CLI Mode for Installation/Setup

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLI_REFERENCE.md

Use the command-line interface (CLI) instead of the text-based user interface (TUI) for interactive operations like installation or key generation. Useful for scripting or debugging.

```bash
./build/proxsave --install --cli
```

```bash
./build/proxsave --new-install --cli
```

```bash
./build/proxsave --newkey --cli
```

```bash
./build/proxsave --decrypt --cli
```

```bash
./build/proxsave --restore --cli
```

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

### Telegram Bot Setup Steps

Source: https://github.com/tis24dev/proxsave/blob/main/docs/EXAMPLES.md

Instructions for creating a Telegram bot via BotFather and obtaining the necessary bot token and chat ID for ProxSave notifications.

```bash
# Create bot via @BotFather on Telegram
# Send message: /newbot
# Get token: 123456789:ABC...

# Get chat ID:
# Send message to bot
# Visit: https://api.telegram.org/bot<TOKEN>/getUpdates
# Copy chat.id value
```

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

### Example Real Migration Output

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLI_REFERENCE.md

This output shows the result of a successful configuration migration, detailing the number of variables migrated, converted, and skipped, along with the location of the new configuration file and backup.

```bash
✓ Migrated 45 variables (SAME category)
✓ Converted 12 variables (RENAMED category)
⚠ Review required: 2 variables (SEMANTIC CHANGE)
  - STORAGE_WARNING_THRESHOLD_PRIMARY → MIN_DISK_SPACE_PRIMARY_GB
  - CLOUD_BACKUP_PATH → CLOUD_REMOTE_PATH
ℹ Skipped 18 legacy variables (LEGACY category)

Configuration written to: /opt/proxsave/configs/backup.env
Backup saved to: /opt/proxsave/configs/backup.env.bak-20251117-143022

⚠ IMPORTANT: Review SEMANTIC CHANGE variables before running backup!
See migration documentation for conversion details.

Next step: ./build/proxsave --dry-run
```

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

### Example Release Artifacts

Source: https://github.com/tis24dev/proxsave/blob/main/docs/RELEASE-PROCESS.md

Illustrates the typical file names and formats of release artifacts generated by GoReleaser for a specific version, including binaries, archives, SBOMs, and checksums.

```text
proxsave_1.6.0_linux_amd64
proxsave_1.6.0_linux_amd64.tar.gz
proxsave_1.6.0_linux_amd64.tar.gz.sbom.cdx.json
SHA256SUMS
```

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

### Encryption Workflow Example

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLI_REFERENCE.md

A typical workflow for managing encryption keys and performing backups. First, generate keys, then run a backup, and finally decrypt when needed.

```bash
# Generate keys
./build/proxsave --newkey

# Run encrypted backup
./build/proxsave

# Decrypt when needed
./build/proxsave --decrypt
```

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

### Troubleshooting Examples

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLI_REFERENCE.md

Commands useful for troubleshooting ProxSave issues, including dry runs with debug logging and running in support mode.

```bash
# Dry run with debug logging
./build/proxsave --dry-run --log-level debug

# Support mode for detailed logging and email
./build/proxsave --support
```

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

### Mount Network Share for Secondary Storage (CIFS/SMB)

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CONFIGURATION.md

Example of mounting a CIFS/SMB network share to a local directory, requiring credentials for access.

```bash
# CIFS/SMB example
sudo mount -t cifs //192.168.0.10/backup /mnt/nas-backup -o credentials=/root/.smbcreds
```

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

### Verify System and Cluster Status

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLUSTER_RECOVERY.md

Before starting the recovery, verify that you are on the correct system, Proxmox VE is installed, and the node is not currently part of a cluster.

```bash
# 1. Verify you're on the target system
hostname
# Expected: Should match backup hostname

# 2. Check PVE installed
dpkg -l | grep proxmox-ve

# 3. Verify no cluster membership
pvecm status
# Expected: "cluster not ready - no quorum?" or similar
```

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

### Initialize Go Module and Build

Source: https://github.com/tis24dev/proxsave/blob/main/docs/TROUBLESHOOTING.md

Fix 'go: cannot find main module' errors by initializing the Go module and tidying dependencies in the project root.

```bash
cd /opt/proxsave
go mod init github.com/tis24dev/proxsave
go mod tidy
make build
```

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

### Install rclone

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLOUD_STORAGE.md

Installs rclone using the official script or package managers. Verifies the installation and checks the version.

```bash
which rclone
rclone version
```

```bash
curl https://rclone.org/install.sh | sudo bash
```

```bash
# Debian/Ubuntu
sudo apt-get update && sudo apt-get install rclone

# CentOS/RHEL
sudo yum install rclone
```

```bash
wget https://downloads.rclone.org/rclone-current-linux-amd64.zip
unzip rclone-current-linux-amd64.zip
sudo cp rclone-*/rclone /usr/local/bin/
sudo chmod 755 /usr/local/bin/rclone
```

```bash
rclone version  # Should show v1.50+
```

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

### Mounting Network Share for SECONDARY_PATH

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CONFIGURATION.md

Example of mounting a network share to a local filesystem path, which can then be used with SECONDARY_PATH. Ensure the mount point exists and permissions are correctly set.

```bash
sudo mount 192.168.0.10:/share /mnt/nas
SECONDARY_PATH=/mnt/nas
```

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

### Mount NAS and Configure Secondary Backup

Source: https://github.com/tis24dev/proxsave/blob/main/docs/EXAMPLES.md

Steps to mount a NAS share (NFS example) and configure Proxsaves for secondary storage. This includes creating directories, setting permissions, and testing write access before running the backup.

```bash
# 1. Mount NAS (example with NFS)
sudo mkdir -p /mnt/nas
sudo mount -t nfs 192.168.1.100:/backup /mnt/nas

# Make mount persistent
echo "192.168.1.100:/backup /mnt/nas nfs defaults 0 0" | sudo tee -a /etc/fstab

# 2. Create backup directories
mkdir -p /mnt/nas/pbs-backup /mnt/nas/pbs-log
chmod 700 /mnt/nas/pbs-backup /mnt/nas/pbs-log

# 3. Test write access
touch /mnt/nas/pbs-backup/test.txt && rm /mnt/nas/pbs-backup/test.txt

# 4. Configure and run
./build/proxsave --install
# (use --new-install if you want to reset the install dir first, keeping env/identity)
# (paste configuration above)
./build/proxsave --dry-run
./build/proxsave
```

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

### Run First Real Backup with Go Version

Source: https://github.com/tis24dev/proxsave/blob/main/docs/MIGRATION_GUIDE.md

Execute the first real backup using the new Go version of ProxSave. Verify the backup file and check the log for any issues.

```bash
# First real backup with Go version
./build/proxsave

# Verify results
ls -lh backup/
# Typical file (bundling enabled by default): <hostname>-backup-YYYYMMDD-HHMMSS.tar.xz.bundle.tar

# Check log for any issues
cat log/backup-*.log
tail -100 log/backup-$(hostname)-*.log | grep -i "error\|warning\|complete"
```

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

### Install GitHub CLI on macOS

Source: https://github.com/tis24dev/proxsave/blob/main/docs/PROVENANCE_VERIFICATION.md

Installs the GitHub CLI on macOS using Homebrew.

```bash
brew install gh
```

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

### Install rclone

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLOUD_STORAGE.md

Installs rclone using a script from the official website. This is a solution for the 'rclone not found in PATH' error.

```bash
curl https://rclone.org/install.sh | sudo bash
```

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

### Review and Compare VM Configuration Files

Source: https://github.com/tis24dev/proxsave/blob/main/docs/RESTORE_GUIDE.md

Displays the content of a specific VM configuration file and compares it with the currently active configuration on the system. This allows for review before applying changes.

```bash
# View VM config
cat qemu-server/100.conf

# Compare with current config (if exists)
diff qemu-server/100.conf /etc/pve/qemu-server/100.conf
```

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

### Install GitHub CLI on Windows with Chocolatey

Source: https://github.com/tis24dev/proxsave/blob/main/docs/PROVENANCE_VERIFICATION.md

Installs the GitHub CLI on Windows using the Chocolatey package manager.

```powershell
choco install gh
```

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

### Full Upgrade Workflow

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLI_REFERENCE.md

Execute a complete upgrade process, including both the binary and configuration updates, followed by a dry-run to verify functionality.

```bash
# Full upgrade workflow (binary + config)
./build/proxsave --upgrade
./build/proxsave --upgrade-config
./build/proxsave --dry-run  # Verify everything works

```

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

### Build proxsave Binary from Source

Source: https://github.com/tis24dev/proxsave/blob/main/docs/INSTALL.md

Clones the proxsave repository, downloads dependencies, and builds the binary. Verifies the build by checking the version.

```bash
# Create folder
mkdir /opt/proxsave

# Navigate to project directory
cd /opt/proxsave

# Copy from github
git clone --branch main https://github.com/tis24dev/proxsave.git .

# Download dependencies
go mod tidy

# Build binary
make build

# Verify build
./build/proxsave --version
```

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

### Fresh Start with Config Import (Bash)

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLUSTER_RECOVERY.md

This procedure involves a complete reinstallation of Proxmox VE components and then manually restoring configuration files. It's a last resort for severe corruption, requiring careful re-creation of the cluster if it was multi-node.

```bash
# 1. Backup everything
tar -czf /root/emergency-backup-$(date +%s).tar.gz \
    /etc/pve/ /var/lib/pve-cluster/ 2>/dev/null || true

# 2. Remove cluster completely
pvecm delnode $(hostname)  # If multi-node
apt remove --purge proxmox-ve pve-cluster pvedaemon pveproxy

# 3. Reinstall cluster components
apt install proxmox-ve

# 4. Restore selective configs manually
# Use export-only /etc/pve contents from backup
# Copy configs one by one after reviewing

# 5. Recreate cluster (if multi-node)
pvecm create <cluster-name>  # On first node
pvecm add <first-node-ip>     # On other nodes
```

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

### Configure Backblaze B2

Source: https://github.com/tis24dev/proxsave/blob/main/docs/EXAMPLES.md

Steps to create a Backblaze B2 account, bucket, and application key, followed by rclone configuration.

```bash
# Create B2 account (10GB free)
# Create bucket: pbs-backups (Private)
# Create Application Key (copy Key ID and Application Key)

rclone config
# n > b2 > b2 > <Key-ID> > <App-Key> > n > n > y > q
```

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

### Windows PowerShell: Verify and Install Proxsave

Source: https://github.com/tis24dev/proxsave/blob/main/docs/PROVENANCE_VERIFICATION.md

This PowerShell script downloads the Proxsave executable for Windows, verifies its attestation using GitHub CLI, and installs it into a dedicated directory within Program Files, adding it to the system PATH. Ensure GitHub CLI is installed and authenticated.

```powershell
# Download binary
$version = "v0.9.0"
$binary = "proxsave-windows-amd64.exe"
$url = "https://github.com/tis24dev/proxsave/releases/download/$version/$binary"

Write-Host "Downloading $binary..." -ForegroundColor Cyan
Invoke-WebRequest -Uri $url -OutFile "proxsave.exe"

# Verify attestation
Write-Host "Verifying attestation..." -ForegroundColor Cyan
$result = gh attestation verify proxsave.exe --repo tis24dev/proxsave

if ($LASTEXITCODE -eq 0) {
    Write-Host "✓ Attestation verified successfully!" -ForegroundColor Green

    # Move to Program Files
    $destPath = "$env:ProgramFiles\ProxmoxBackup"
    New-Item -ItemType Directory -Force -Path $destPath | Out-Null
    Move-Item -Path "proxsave.exe" -Destination "$destPath\proxsave.exe" -Force

    # Add to PATH if not already there
    $currentPath = [Environment]::GetEnvironmentVariable("Path", "Machine")
    if ($currentPath -notlike "*$destPath*") {
        [Environment]::SetEnvironmentVariable("Path", "$currentPath;$destPath", "Machine")
        Write-Host "Added to system PATH" -ForegroundColor Green
    }

    Write-Host "Installation complete!" -ForegroundColor Green
} else {
    Write-Host "✗ Attestation verification failed!" -ForegroundColor Red
    Remove-Item "proxsave.exe"
    exit 1
}

```

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

### Preview Configuration Migration (Dry-Run)

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLI_REFERENCE.md

Execute a dry-run of the configuration migration to preview changes without modifying any files. This is recommended as a first step to verify the migration process and identify variables requiring manual review.

```bash
./build/proxsave --env-migration-dry-run --old-env /opt/proxsave/env/backup.env
```

```bash
./build/proxsave --env-migration-dry-run
```

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

### Configure Basic Local Backup

Source: https://github.com/tis24dev/proxsave/blob/main/docs/EXAMPLES.md

Set up a simple local backup configuration for a standalone Proxmox VE or PBS server. This configuration defines backup paths, compression settings, and retention policies for local storage.

```bash
# configs/backup.env
BACKUP_ENABLED=true
BACKUP_PATH=/opt/proxsave/backup
LOG_PATH=/opt/proxsave/log

# Compression
COMPRESSION_TYPE=xz
COMPRESSION_LEVEL=6
COMPRESSION_MODE=standard

# Retention: Keep 15 backups
MAX_LOCAL_BACKUPS=15

# Run backup
./build/proxsave
```

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

### Build Go Version of ProxSave

Source: https://github.com/tis24dev/proxsave/blob/main/docs/MIGRATION_GUIDE.md

Navigate to the ProxSave directory and build the Go binary. Verify the binary exists and check its version.

```bash
cd /opt/proxsave
make build

# Verify binary
ls -lh build/proxsave
./build/proxsave --version
```

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

### Configure MinIO Bucket and Rclone

Source: https://github.com/tis24dev/proxsave/blob/main/docs/EXAMPLES.md

This snippet shows how to create buckets in MinIO using the 'mc' client and configure rclone to connect to a local MinIO instance. Ensure MinIO is running and accessible.

```bash
# Assuming MinIO running at https://minio.local:9000
# Create bucket via MinIO Console or mc client
mc mb minio-local/pbs-backups
mc mb minio-local/pbs-logs

rclone config
# n > minio > s3 > Minio > minioadmin > minioadmin > (empty region) > https://minio.local:9000 > y > q
```

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

### Install Script for Latest Main Version

Source: https://github.com/tis24dev/proxsave/blob/main/docs/RELEASE-PROCESS.md

Provides a command to install the latest stable version of Proxsave directly from the main branch using a curl and bash script.

```bash
bash -c "$(curl -fsSL https://raw.githubusercontent.com/tis24dev/proxsave/main/install.sh)"
```

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

### ProxSave Network Rollback - DISARMED/CLEARED Status Example

Source: https://github.com/tis24dev/proxsave/blob/main/docs/RESTORE_GUIDE.md

This example shows the output when ProxSave is interrupted and the network rollback is DISARMED or CLEARED, meaning it will not run. It advises reconnecting using the post-apply IP.

```text
===========================================
NETWORK ROLLBACK

  Status: DISARMED/CLEARED (marker removed before deadline)
  Pre-apply IP (from snapshot): 192.168.1.100
  Post-apply IP (observed): 10.0.0.4/24
  Rollback log: /tmp/proxsave/network_rollback_20260122_153012.log

Rollback will NOT run: reconnect using the post-apply IP: 10.0.0.4/24
===========================================
```

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

### Verify VM and Container Configurations

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLUSTER_RECOVERY.md

List all virtual machines and containers to ensure they are recognized by the system. Check individual VM/CT configurations for completeness.

```bash
# List VMs
qm list
# Expected: All VMs listed (may show "unknown" if disk images not restored)

# Check specific VM config
qm config 100
# Expected: Full config displayed

# List containers
pct list
# Expected: All CTs listed

# Check specific CT config
pct config 200
# Expected: Full config displayed
```

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

### Handle Missing PVE Cluster Service

Source: https://github.com/tis24dev/proxsave/blob/main/docs/RESTORE_GUIDE.md

If 'Failed to stop pve-cluster: Unit not found' occurs, it may be normal on PBS systems or indicate PVE is not installed. Check PVE installation or reinstall the service.

```bash
# This is normal on PBS systems
# Or check if PVE installed
dpkg -l | grep proxmox-ve

# If truly PVE but service missing, repair
apt install --reinstall pve-cluster
```

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

### ProxSave Network Rollback - EXECUTED Status Example

Source: https://github.com/tis24dev/proxsave/blob/main/docs/RESTORE_GUIDE.md

This example illustrates the output when ProxSave is interrupted and the network rollback has already EXECUTED. It confirms the rollback has run and advises reconnecting using the pre-apply IP.

```text
===========================================
NETWORK ROLLBACK

  Status: EXECUTED (marker removed)
  Pre-apply IP (from snapshot): 192.168.1.100
  Post-apply IP (observed): 10.0.0.4/24
  Rollback log: /tmp/proxsave/network_rollback_20260122_153012.log

Rollback executed: reconnect using the pre-apply IP: 192.168.1.100
===========================================
```

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

### PVE Cluster Service Start (Warn-Only)

Source: https://github.com/tis24dev/proxsave/blob/main/docs/RESTORE_TECHNICAL.md

Implements a warn-only error handling strategy for starting Proxmox Virtual Environment (PVE) cluster services after a restore. Failures to restart services are logged as warnings but do not halt the process.

```go
defer func() {
    if err := startPVEClusterServices(ctx, logger); err != nil {
        logger.Warning("Failed to restart: %v", err)
        // Continue anyway - restore already completed
    }
}()
```

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

### Run Application Directly with Go Run

Source: https://github.com/tis24dev/proxsave/blob/main/docs/DEVELOPER_GUIDE.md

Execute the application directly using 'go run' without a prior build step. This is convenient for quick testing during development.

```bash
# Run directly with go run
make run

# Or manually
go run ./cmd/proxsave
```

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

### ProxSave Network Rollback - ARMED Status Example

Source: https://github.com/tis24dev/proxsave/blob/main/docs/RESTORE_GUIDE.md

This example shows the output when ProxSave is interrupted with Ctrl+C and the network rollback is ARMED, indicating it will execute automatically. It provides the pre-apply and post-apply IPs, the rollback log path, and a countdown timer.

```text
===========================================
NETWORK ROLLBACK

  Status: ARMED (will execute automatically)
  Pre-apply IP (from snapshot): 192.168.1.100
  Post-apply IP (observed): 10.0.0.4/24
  Rollback log: /tmp/proxsave/network_rollback_20260122_153012.log

Connection will be temporarily interrupted during restore.
Remember to reconnect using the pre-apply IP: 192.168.1.100
  Remaining: 147s
===========================================

===========================================
ProxSave - Go - <build signature>
===========================================
```

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

### Check pveproxy Service Status

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLUSTER_RECOVERY.md

Verify that the pveproxy service is running. If not, start it.

```bash
systemctl status pveproxy
# If not running:
systemctl start pveproxy
```

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

### Perform and Verify First Real Backup

Source: https://github.com/tis24dev/proxsave/blob/main/docs/INSTALL.md

Execute the first real backup after configuration migration and verification. This includes running the backup command and checking the output files and logs.

```bash
# First real backup
./build/proxsave

# Verify results
ls -lh backup/
cat log/backup-*.log
```

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

### Review and Copy Exported Configuration Files

Source: https://github.com/tis24dev/proxsave/blob/main/docs/RESTORE_GUIDE.md

How to review exported /etc/pve files and selectively copy needed configuration files back to the system. Useful for manual restoration of specific configurations.

```bash
# Review exported files
ls /opt/proxsave/proxmox-config-export-*/etc/pve/

# Compare with current
diff /opt/proxsave/proxmox-config-export-*/etc/pve/storage.cfg \
     /etc/pve/storage.cfg

# Selectively copy needed files
cp /opt/proxsave/proxmox-config-export-*/etc/pve/qemu-server/100.conf \
   /etc/pve/qemu-server/100.conf
```

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

### PBS Service Management for Restore

Source: https://github.com/tis24dev/proxsave/blob/main/docs/RESTORE_GUIDE.md

Shows the steps for stopping Proxmox Backup Server (PBS) services in preparation for configuration restore. Includes a prompt for continuing if service stop fails.

```text
Preparing PBS system for restore: stopping proxmox-backup services

Stopping proxmox-backup-proxy...
Stopping proxmox-backup...
PBS services stopped successfully.
```

```text
Unable to stop PBS services automatically: <error>
Continue restore with PBS services still running? (y/N): _
```

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

### Public Key Format

Source: https://github.com/tis24dev/proxsave/blob/main/docs/ENCRYPTION.md

An example of a public key generated by the age encryption tool.

```text
age1abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567abc
```

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

### Check Proxsave Version

Source: https://github.com/tis24dev/proxsave/blob/main/docs/TROUBLESHOOTING.md

Verify the installed Proxsave version. This is a good first step before troubleshooting.

```bash
./build/proxsave --version
```

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

### Verify Go Module Files

Source: https://github.com/tis24dev/proxsave/blob/main/docs/TROUBLESHOOTING.md

Confirm that the `go.mod` and `go.sum` files exist after initializing the Go module.

```bash
ls -la go.mod go.sum
```

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

### Lint Code

Source: https://github.com/tis24dev/proxsave/blob/main/docs/DEVELOPER_GUIDE.md

Command to run the linter to check code quality. Requires golangci-lint to be installed.

```bash
# Lint (requires golangci-lint)
golangci-lint run
```

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

### List Dependencies

Source: https://github.com/tis24dev/proxsave/blob/main/docs/DEVELOPER_GUIDE.md

Command to list all current project dependencies.

```bash
# List dependencies
go list -m all
```

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

### Verify Sendmail Installation

Source: https://github.com/tis24dev/proxsave/blob/main/docs/TROUBLESHOOTING.md

Check if the sendmail executable is available on the system when using the sendmail delivery method.

```bash
test -x /usr/sbin/sendmail && echo "sendmail OK" || echo "sendmail not found"
```

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

### List Project Dependencies with Go

Source: https://github.com/tis24dev/proxsave/blob/main/docs/DEVELOPER_GUIDE.md

Use `go list` to view project dependencies. `-m all` lists all modules, `-f '{{if not .Indirect}}{{.}}{{end}}'` filters for direct dependencies, and `-u` checks for available updates.

```bash
# List all dependencies
go list -m all
```

```bash
# List direct dependencies only
go list -m -f '{{if not .Indirect}}{{.}}{{end}}' all
```

```bash
# Check for available updates
go list -u -m all
```

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

### Private Key Format

Source: https://github.com/tis24dev/proxsave/blob/main/docs/ENCRYPTION.md

An example of a private key generated by the age encryption tool. This key should be kept secure.

```text
AGE-SECRET-KEY-1ABC123DEF456GHI789JKL012MNO345PQR678STU901VWX234YZ567ABC
```

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

### Preview Configuration Upgrade Changes

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLI_REFERENCE.md

Perform a dry-run of the configuration upgrade process to preview the changes without applying them.

```bash
# Preview upgrade changes
./build/proxsave --upgrade-config-dry-run
```

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

### Import ZFS Pool

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CLUSTER_RECOVERY.md

If ZFS pools are not imported, use 'zpool import' and then start the corresponding ZFS import service.

```bash
zpool status
# If not imported:
zpool import <pool-name>
systemctl start zfs-import@<pool-name>.service
```

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

### Commit Changes with Detailed Message

Source: https://github.com/tis24dev/proxsave/blob/main/docs/DEVELOPER_GUIDE.md

Example of staging all changes and committing with an atomic commit message that includes a detailed explanation.

```bash
# Atomic commits with clear messages
git add .
git commit -m "Add: feature description

Detailed explanation of changes:
- Added X functionality
- Updated Y module
- Fixed Z issue"
```

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

### Run Interactive Restore Workflow

Source: https://github.com/tis24dev/proxsave/blob/main/docs/RESTORE_GUIDE.md

Execute the main restore command to start the interactive process. Follow the on-screen prompts to select backup source, choose a backup, enter a passphrase if needed, select a restore mode, review the plan, confirm the restore, and wait for completion.

```bash
# Run the interactive restore workflow
./build/proxsave --restore

# Follow the prompts:
# 1. Select backup source location
# 2. Choose specific backup from list
# 3. Enter decryption passphrase (if encrypted)
# 4. Select restore mode
# 5. Review restore plan
# 6. Type "RESTORE" to confirm
# 7. Wait for completion
# 8. Verify services and cluster status
```

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

### GFS Retention Example Output

Source: https://github.com/tis24dev/proxsave/blob/main/docs/CONFIGURATION.md

Illustrates the output format for GFS retention, showing backup classification, deletions, and remaining backups.

```text
GFS classification → daily: 7/7, weekly: 4/4, monthly: 12/12, yearly: 2/3, to_delete: 15
Deleting old backup: pbs-backup-20220115-120000.tar.xz (created: 2022-01-15 12:00:00)
Cloud storage retention applied: deleted 15 backups (logs deleted: 15), 26 backups remaining
```

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

### Standard Development Build

Source: https://github.com/tis24dev/proxsave/blob/main/docs/DEVELOPER_GUIDE.md

Use this command for a standard development build. The output is placed in the build/proxsave directory.

```bash
# Standard development build
make build

# Output: build/proxsave
```

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

### Checksum Verification Success Example

Source: https://github.com/tis24dev/proxsave/blob/main/docs/RESTORE_GUIDE.md

This output indicates that the SHA256 checksum of the backup was successfully verified after decryption, confirming the integrity of the backup data.

```text
Verifying SHA256 checksum...
Expected: a1b2c3...
Actual:   a1b2c3...
✓ Checksum verified successfully.
```

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

### Run Automatic Migration Tool

Source: https://github.com/tis24dev/proxsave/blob/main/docs/MIGRATION_GUIDE.md

Use these commands to preview and execute the automatic configuration migration. The dry-run is recommended first.

```bash
# Step 1: Preview migration (recommended first step)
./build/proxsave --env-migration-dry-run
```

```bash
# Step 2: Execute real migration
./build/proxsave --env-migration
```