PROXMOX-BACKUP-CLIENT(1)

📦
version 4.2.0 · 2 versions
, in nixos 26.05

🌸 NAME 🌸

proxmox-backup-client — Command line tool for Backup and Restore. This is the PROXMOX-BACKUP-CLIENT(1) page from the Proxmox Backup manual, and bestie, it's literally the CLI for backup and restore. 💖

✨ SYNOPSIS ✨

okay so every command gets its own little moment here. Keep the code exactly as written — no renaming, no merging, no invented flags. 💅

💾 backup — the main character 💾

proxmox-backup-client backup {<backupspec>} [OPTIONS]

Create a (host) backup. Main character energy, honestly.

<backupspec> (<string>) — List of backup source specifications:

[<archive-name>.<type>:<source-path>] ...

The archive-name must only contain alphanumerics, hyphens and underscores while the type must be either pxar, img, conf or log. Can be specified more than once.

bestie, those archive-name rules are strict — do not freestyle them. 🫶

Optional parameters:

  • --all-file-systems <boolean> — default=false. Include all mounted subdirectories.
  • --auth-id <string> — Authentication ID.
  • --backup-id <string> — Backup ID.
  • --backup-time <integer> — (1 - N). Backup time (Unix epoch.)
  • --backup-type vm|ct|host — Backup type.
  • --burst <string> — Size of the token bucket (for Token bucket filter) in bytes with optional unit (B, KB (base 10), MB, GB, ..., KiB (base 2), MiB, Gib, ...).
  • --change-detection-mode legacy|data|metadata — default=legacy. Mode to detect file changes since last backup run.
  • --chunk-size <integer> — (64 - 4096), default=4096. Chunk size in KB. Must be a power of 2.
  • --crypt-mode none|encrypt|sign-only — default=encrypt. Defines whether data is encrypted (using an AEAD cipher), only signed, or neither.
  • --datastore <string> — Datastore name.
  • --dry-run <boolean> — default=false. Just show what backup would do, but do not upload anything.
  • --entries-max <integer> — default=1048576. Max number of entries to hold in memory.
  • --exclude <string> — List of paths or patterns for matching files to exclude. Can be specified more than once.
  • --include-dev <string> — Include mountpoints with same st_dev number (see man fstat) as specified files. Can be specified more than once.
  • --keyfd <integer> — (0 - N). Pass an encryption key via an already opened file descriptor.
  • --keyfile <string> — Path to encryption key. All data will be encrypted using this key.
  • --master-pubkey-fd <integer> — (0 - N). Pass a master public key via an already opened file descriptor.
  • --master-pubkey-file <string> — Path to master public key. The encryption key used for a backup will be encrypted using this key and appended to the backup.
  • --no-cache <boolean> — default=false. Bypass local datastore cache for network storages.
  • --ns <string> — Namespace.
  • --port <integer> — (1 - 65535), default=8007. Backup server port. Default: 8007.
  • --rate <string> — Rate limit (for Token bucket filter) in bytes/s with optional unit (B, KB (base 10), MB, GB, ..., KiB (base 2), MiB, Gib, ...).
  • --repository <string> — Repository URL: [[auth-id@]server[:port]:]datastore.
  • --server <string> — Backup server address (hostname or IP). Default: localhost.
  • --skip-e2big-xattr <boolean> — default=false. Ignore the E2BIG error when retrieving xattrs. This includes the file, but discards the metadata.
  • --skip-lost-and-found <boolean> — default=false. Skip lost+found directory.

⚡ benchmark — vibe check the server ⚡

proxmox-backup-client benchmark [OPTIONS]

Run benchmark tests.

Optional parameters:

  • --auth-id <string> — Authentication ID.
  • --datastore <string> — Datastore name.
  • --keyfile <string> — Path to encryption key. All data will be encrypted using this key.
  • --no-cache <boolean> — default=false. Bypass local datastore cache for network storages.
  • --output-format text|json|json-pretty — Output format.
  • --port <integer> — (1 - 65535), default=8007. Backup server port. Default: 8007.
  • --repository <string> — Repository URL: [[auth-id@]server[:port]:]datastore.
  • --server <string> — Backup server address (hostname or IP). Default: localhost.

🗂️ catalog dump — dump the catalog 🗂️

proxmox-backup-client catalog dump <snapshot> [OPTIONS]

Dump catalog.

<snapshot> (<string>) — Snapshot path.

Optional parameters:

  • --auth-id <string> — Authentication ID.
  • --datastore <string> — Datastore name.
  • --keyfd <integer> — (0 - N). Pass an encryption key via an already opened file descriptor.
  • --keyfile <string> — Path to encryption key.
  • --ns <string> — Namespace.
  • --port <integer> — (1 - 65535), default=8007. Backup server port. Default: 8007.
  • --repository <string> — Repository URL: [[auth-id@]server[:port]:]datastore.
  • --server <string> — Backup server address (hostname or IP). Default: localhost.

🐚 catalog shell — peek inside, bestie 🐚

proxmox-backup-client catalog shell <snapshot> <archive-name> [OPTIONS]

Shell to interactively inspect and restore snapshots.

<snapshot> (<string>) — Group/Snapshot path.

<archive-name> (<string>) — Backup archive name.

Optional parameters:

  • --auth-id <string> — Authentication ID.
  • --datastore <string> — Datastore name.
  • --keyfd <integer> — (0 - N). Pass an encryption key via an already opened file descriptor.
  • --keyfile <string> — Path to encryption key.
  • --ns <string> — Namespace.
  • --port <integer> — (1 - 65535), default=8007. Backup server port. Default: 8007.
  • --repository <string> — Repository URL: [[auth-id@]server[:port]:]datastore.
  • --server <string> — Backup server address (hostname or IP). Default: localhost.

👑 change-owner — hand over the group 👑

proxmox-backup-client change-owner <group> <new-owner> [OPTIONS]

Change owner of a backup group.

<group> (<string>) — Backup group.

<new-owner> (<string>) — Authentication ID.

Optional parameters:

  • --auth-id <string> — Authentication ID.
  • --datastore <string> — Datastore name.
  • --ns <string> — Namespace.
  • --port <integer> — (1 - 65535), default=8007. Backup server port. Default: 8007.
  • --repository <string> — Repository URL: [[auth-id@]server[:port]:]datastore.
  • --server <string> — Backup server address (hostname or IP). Default: localhost.

🧹 garbage-collect — clean it up 🧹

proxmox-backup-client garbage-collect [OPTIONS]

Start garbage collection for a specific repository.

Optional parameters:

  • --auth-id <string> — Authentication ID.
  • --datastore <string> — Datastore name.
  • --output-format text|json|json-pretty — Output format.
  • --port <integer> — (1 - 65535), default=8007. Backup server port. Default: 8007.
  • --repository <string> — Repository URL: [[auth-id@]server[:port]:]datastore.
  • --server <string> — Backup server address (hostname or IP). Default: localhost.

🙈 group forget — forget (remove) snapshots 🙈

proxmox-backup-client group forget <group> [OPTIONS]

Forget (remove) backup snapshots.

<group> (<string>) — Backup group.

Optional parameters:

  • --auth-id <string> — Authentication ID.
  • --datastore <string> — Datastore name.
  • --ns <string> — Namespace.
  • --port <integer> — (1 - 65535), default=8007. Backup server port. Default: 8007.
  • --repository <string> — Repository URL: [[auth-id@]server[:port]:]datastore.
  • --server <string> — Backup server address (hostname or IP). Default: localhost.

🦋 group move — new namespace, same datastore 🦋

proxmox-backup-client group move <group> --target-ns <string> [OPTIONS]

Move a backup group to a different namespace within the same datastore.

<group> (<string>) — Backup group.

--target-ns <string> — Namespace.

Optional parameters:

  • --auth-id <string> — Authentication ID.
  • --datastore <string> — Datastore name.
  • --merge-group <boolean> — default=true. If the group already exists in the target namespace, merge snapshots into it. Requires matching ownership and non-overlapping snapshot times.
  • --ns <string> — Namespace.
  • --output-format text|json|json-pretty — Output format.
  • --port <integer> — (1 - 65535), default=8007. Backup server port. Default: 8007.
  • --repository <string> — Repository URL: [[auth-id@]server[:port]:]datastore.
  • --server <string> — Backup server address (hostname or IP). Default: localhost.

🎀 help — when you need the lore 🎀

proxmox-backup-client help [{<command>}] [OPTIONS]

Get help about specified command (or sub-command).

<command> (<string>) — Command. This may be a list in order to specify nested sub-commands. Can be specified more than once.

Optional parameters:

  • --verbose <boolean> — Verbose help.

🔑 key change-passphrase — new password, who dis 🔑​

proxmox-backup-client key change-passphrase [<path>] [OPTIONS]

Change the encryption key's password.

<path> (<string>) — Key file. Without this the default key's password will be changed.

Optional parameters:

  • --hint <string> — Password hint.
  • --kdf none|scrypt|pbkdf2 — default=scrypt. Key derivation function for password protected encryption keys.

🧚 key create — make a new encryption key 🧚

proxmox-backup-client key create [<path>] [OPTIONS]

Create a new encryption key.

<path> (<string>) — Output file. Without this the key will become the new default encryption key.

Optional parameters:

  • --hint <string> — Password hint.
  • --kdf none|scrypt|pbkdf2 — default=scrypt. Key derivation function for password protected encryption keys.

💜 key create-master-key — RSA public/private key pair 💜

proxmox-backup-client key create-master-key

Create an RSA public/private key pair used to put an encrypted version of the symmetric backup encryption key onto the backup server along with each backup.

🌈 key import-master-pubkey — import that RSA public key 🌈

proxmox-backup-client key import-master-pubkey <path>

Import an RSA public key used to put an encrypted version of the symmetric backup encryption key onto the backup server along with each backup.

The imported key will be used as default master key for future invocations by the same local user.

<path> (<string>) — Path to the PEM formatted RSA public key.

⭐ key import-with-master-key — part 1 stops here ⭐

proxmox-backup-client key import-with-master-key [<path>] --encrypted-keyfile <string> --master-keyfile <string> [OPTIONS]

Okay so this next one is the key-import situation, and it's giving ✨security core✨ — it pulls in an encrypted backup of an encryption key using a (private) master key 🔐

  • <path> (string) — the output file, bestie. And lowkey the important bit: if you don't pass this, the imported key becomes the new default encryption key 👑
  • --encrypted-keyfile <string> — the RSA-encrypted keyfile you're importing 🎀
  • --master-keyfile <string> — the (private) master key to use with it 🗝️

Optional parameters:

  • --hint <string> — a password hint. Be nice to future you 💜
  • --kdf none|scrypt|pbkdf2 (default=scrypt) — which key derivation function to use for password-protected encryption keys 🧚

🎀 proxmox-backup-client key paperkey [<path>] [OPTIONS]

Not me being obsessed with this one — it generates a printable, human readable text file containing the encryption key 📄💖

And it also includes a scanable QR code for fast key restore, which is genuinely iconic for disaster recovery 🦋 (yes, scanable, that's the manpage's spelling, we respect it)

  • <path> (string) — the key file. If you don't give one, the default key's will be used 🗂️

Optional parameters:

  • --output-format text|html — paperkey output format ✨
  • --subject <string> — include the specified subject as title text 🏷️

💅 proxmox-backup-client key show [<path>] [OPTIONS]

Prints the encryption key's metadata — like, just the vibes, not the whole key 🔍

  • <path> (string) — key file. No path? Then the default key's metadata will be shown 🌸

Optional parameters:

  • --output-format text|json|json-pretty — output format 🎀

🌈 proxmox-backup-client key show-master-pubkey [<path>] [OPTIONS]

Lists info about the master key 🔑

  • <path> (string) — path to the PEM formatted RSA public key. If you don't specify it, the default location will be used 📍

Optional parameters:

  • --output-format text|json|json-pretty — output format ✨

🦋 proxmox-backup-client list [OPTIONS]

List backup groups. That's it, that's the whole thing 💅

Optional parameters:

  • --auth-id <string> — authentication ID 🪪
  • --datastore <string> — datastore name 🗄️
  • --ns <string> — namespace 📦
  • --output-format text|json|json-pretty — output format 🎀
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🔗
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️

⭐ proxmox-backup-client login [OPTIONS]

Try to login. If it works, it stores the ticket 🎟️ slay

Optional parameters:

  • --auth-id <string> — authentication ID 🪪
  • --datastore <string> — datastore name 🗄️
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🔗
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️

🙈 proxmox-backup-client logout [OPTIONS]

Logout. Translation: delete the stored ticket 💀 bye bestie

Optional parameters:

  • --auth-id <string> — authentication ID 🪪
  • --datastore <string> — datastore name 🗄️
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🔗
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️

🔥 proxmox-backup-client map <snapshot> <archive-name> [OPTIONS]

Maps a drive image from a VM backup onto a local loopback device 🌀 use unmap to undo it, iykyk

⚠️ WARNING: Only do this with trusted backups! Not me begging you to be careful, but like, I'm begging you to be careful 😭
  • <snapshot> (string) — group/snapshot path 📸
  • <archive-name> (string) — backup archive name 🗃️

Optional parameters:

  • --auth-id <string> — authentication ID 🪪
  • --datastore <string> — datastore name 🗄️
  • --keyfile <string> — path to encryption key 🔑
  • --ns <string> — namespace 📦
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🔗
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️
  • --verbose <boolean> (default=false) — verbose output and stay in foreground 👀

🌸 proxmox-backup-client mount <snapshot> <archive-name> <target> [OPTIONS]

Mount a pxar archive 🗂️✨

  • <snapshot> (string) — group/snapshot path 📸
  • <archive-name> (string) — backup archive name 🗃️
  • <target> (string) — target directory path 📁

Optional parameters:

  • --auth-id <string> — authentication ID 🪪
  • --datastore <string> — datastore name 🗄️
  • --keyfile <string> — path to encryption key 🔑
  • --ns <string> — namespace 📦
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🔗
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️
  • --verbose <boolean> (default=false) — verbose output and stay in foreground 👀

🧚 proxmox-backup-client namespace create [<ns>] [OPTIONS]

Creates a shiny new namespace ✨📦

  • <ns> (string) — namespace 📦

Optional parameters:

  • --auth-id <string> — authentication ID 🪪
  • --datastore <string> — datastore name 🗄️
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🔗
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️

💀 proxmox-backup-client namespace delete [<ns>] [OPTIONS]

Deletes an existing namespace. This is the main character energy of irreversible, so read the flags 😭

  • <ns> (string) — namespace 📦

Optional parameters:

  • --auth-id <string> — authentication ID 🪪
  • --datastore <string> — datastore name 🗄️
  • --delete-groups <boolean> — destroys all groups in the hierarchy 💀 like, all of them, bestie
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🔗
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️

🎀 proxmox-backup-client namespace list [<ns>] [OPTIONS]

Lists the namespaces in a repository 📋🦋

  • <ns> (string) — namespace 📦

Optional parameters:

  • --auth-id <string> — authentication ID 🪪
  • --datastore <string> — datastore name 🗄️
  • --max-depth <integer> (0 - N) — maximum recursion depth 🌀
  • --output-format text|json|json-pretty — output format ✨
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🔗
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️

🌀 proxmox-backup-client namespace move [<ns>] --target-ns <string> [OPTIONS]

Moves a backup namespace to a new location within the same datastore 🚚📦

  • <ns> (string) — namespace 📦
  • --target-ns <string> — namespace 🎯

Optional parameters:

  • --auth-id <string> — authentication ID 🪪
  • --datastore <string> — datastore name 🗄️
  • --delete-source <boolean> (default=true) — remove the source namespace after moving all contents. Defaults to true 🧹
  • --max-depth <integer> (0 - 7) (default=7) — how many levels of namespaces should be operated on (0 == no recursion) 🪆
  • --merge-groups <boolean> (default=true) — if a group with the same name already exists in the target namespace, merge snapshots into it. Requires matching ownership and non-overlapping snapshot times ⚠️ don't skip that part
  • --output-format text|json|json-pretty — output format ✨
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🔗
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️

🍓 proxmox-backup-client prune <group> [OPTIONS]

Prunes a backup repository ✂️🔥 this is the "keep only what sparks joy" command

  • <group> (string) — backup group 👯

Optional parameters:

  • --auth-id <string> — authentication ID 🪪
  • --datastore <string> — datastore name 🗄️
  • --dry-run <boolean> — just show what prune would do, but do not delete anything. Lowkey the self-care flag 🧘‍♀️
  • --keep-daily <integer> (1 - N) — number of daily backups to keep 🌞
  • --keep-hourly <integer> (1 - N) — number of hourly backups to keep ⏰
  • --keep-last <integer> (1 - N) — number of backups to keep 🫶
  • --keep-monthly <integer> (1 - N) — number of monthly backups to keep 🗓️
  • --keep-weekly <integer> (1 - N) — number of weekly backups to keep 📆
  • --keep-yearly <integer> (1 - N) — number of yearly backups to keep 🎆
  • --max-depth <integer> (0 - 7) — how many levels of namespaces should be operated on (0 == no recursion, empty == automatic full recursion, namespace depths reduce maximum allowed value) 🪆
  • --ns <string> — namespace 📦
  • --output-format text|json|json-pretty — output format ✨
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌
  • --quiet <boolean> (default=false) — minimal output, only show removals 🤫
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🔗
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️

💖 proxmox-backup-client restore <snapshot> <archive-name> <target> [OPTIONS]

Restores a backup repository 🫶 the reverse-uno card of backups

  • <snapshot> (string) — group/snapshot path 📸
  • <archive-name> (string) — backup archive name 🗃️
  • <target> (string) — target directory path. Use '-' to write to standard output 📤
Heads up bestie: we do not extract '.pxar' archives when writing to standard output 🙅‍♀️

Optional parameters:

  • --allow-existing-dirs <boolean> (default=false) — do not fail if directories already exists 🗂️
  • --auth-id <string> — authentication ID 🪪
  • --burst <string> — size of the token bucket (for Token bucket filter) in bytes with optional unit (B, KB (base 10), MB, GB, ..., KiB (base 2), MiB, Gib, ...) 🪣
  • --crypt-mode none|encrypt|sign-only (default=encrypt) — the vibe check for your data 🔐: encrypt means it's encrypted with an AEAD cipher, sign-only means it's just signed, and none means neither. Choose wisely bestie.
  • --datastore <string> — the datastore name 💾.
  • --ignore-acls <boolean> (default=false) — literally just ignore acl settings, no thoughts head empty 🙈.
  • --ignore-extract-device-errors <boolean> (default=false) — ignore errors that happen while extracting device nodes 🫶.
  • --ignore-ownership <boolean> (default=false) — ignore owner settings, i.e. no chown 👑.
  • --ignore-permissions <boolean> (default=false) — ignore permission settings, i.e. no chmod 🔒.
  • --ignore-xattrs <boolean> (default=false) — ignore xattr settings ✨.
  • --keyfd <integer> (0 - N) — hand over an encryption key through an already opened file descriptor 🗝️.
  • --keyfile <string> — path to the encryption key; all data gets encrypted using this key 💖.
  • --ns <string> — namespace 🌸.
  • --overwrite <boolean> (default=false) — overwrite files that already exist 😤.
  • --overwrite-files <boolean> (default=false) — same energy: overwrite already existing files 🔥.
  • --overwrite-hardlinks <boolean> (default=false) — overwrite already existing entries with the archive's hardlink ⛓️.
  • --overwrite-symlinks <boolean> (default=false) — overwrite already existing entries with the archive's symlink 🪢.
  • --pattern <string> — a path or match pattern to limit which files get restored; you can pass it more than once 🎯.
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌.
  • --prelude-target <string> — path to restore the prelude to (pxar v2 archives only, so don't come for me if it's not that) 🧚.
  • --rate <string> — rate limit (for a Token bucket filter) in bytes/s, with an optional unit: B, KB (base 10), MB, GB, ..., KiB (base 2), MiB, Gib, ... 🏃‍♀️💨.
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🗂️.
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️.

🛰️ proxmox-backup-client server-identity

proxmox-backup-client server-identity [OPTIONS]

Returns the server identity info for this Proxmox Backup Server — like sliding into its DMs and asking who it is 💌.

Optional parameters:

  • --auth-id <string> — authentication ID 🪪.
  • --datastore <string> — datastore name 💾.
  • --output-format text|json|json-pretty — output format 📄.
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌.
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🗂️.
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️.

📂 proxmox-backup-client snapshot files

proxmox-backup-client snapshot files <snapshot> [OPTIONS]

List the files inside a snapshot — literally snooping through the archives, but make it authorized 🕵️‍♀️.

<snapshot> (<string>) — snapshot path 📸.

Optional parameters:

  • --auth-id <string> — authentication ID 🪪.
  • --datastore <string> — datastore name 💾.
  • --ns <string> — namespace 🌸.
  • --output-format text|json|json-pretty — output format 📄.
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌.
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🗂️.
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️.

💀 proxmox-backup-client snapshot forget

proxmox-backup-client snapshot forget <snapshot> [OPTIONS]

Forget (remove) backup snapshots. It's giving "we are never ever getting back together" 🎶 — except the snapshot's actually gone.

<snapshot> (<string>) — snapshot path 📸.

Optional parameters:

  • --auth-id <string> — authentication ID 🪪.
  • --datastore <string> — datastore name 💾.
  • --ns <string> — namespace 🌸.
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌.
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🗂️.
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️.

📜 proxmox-backup-client snapshot list

proxmox-backup-client snapshot list [<group>] [OPTIONS]

List your backup snapshots — the full camera roll, no filters 📱✨.

<group> (<string>) — backup group 👯‍♀️.

Optional parameters:

  • --auth-id <string> — authentication ID 🪪.
  • --datastore <string> — datastore name 💾.
  • --ns <string> — namespace 🌸.
  • --output-format text|json|json-pretty — output format 📄.
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌.
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🗂️.
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️.

📝 proxmox-backup-client snapshot notes show

proxmox-backup-client snapshot notes show <snapshot> [OPTIONS]

Show notes 📖 — the little diary entry attached to a snapshot.

<snapshot> (<string>) — snapshot path 📸.

Optional parameters:

  • --auth-id <string> — authentication ID 🪪.
  • --datastore <string> — datastore name 💾.
  • --ns <string> — namespace 🌸.
  • --output-format text|json|json-pretty — output format 📄.
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌.
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🗂️.
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️.

✏️ proxmox-backup-client snapshot notes update

proxmox-backup-client snapshot notes update <snapshot> <notes> [OPTIONS]

Update Notes — rewriting history, but the cute, sanctioned kind 🎀.

<snapshot> (<string>) — snapshot path 📸.

<notes> (<string>) — the Notes 📝.

Optional parameters:

  • --auth-id <string> — authentication ID 🪪.
  • --datastore <string> — datastore name 💾.
  • --ns <string> — namespace 🌸.
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌.
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🗂️.
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️.

🛡️ proxmox-backup-client snapshot protected show

proxmox-backup-client snapshot protected show <snapshot> [OPTIONS]

Show the protection status of the specified snapshot — is it guarded or is it free-range? 👀

<snapshot> (<string>) — snapshot path 📸.

Optional parameters:

  • --auth-id <string> — authentication ID 🪪.
  • --datastore <string> — datastore name 💾.
  • --ns <string> — namespace 🌸.
  • --output-format text|json|json-pretty — output format 📄.
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌.
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🗂️.
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️.

🔐 proxmox-backup-client snapshot protected update

proxmox-backup-client snapshot protected update <snapshot> <protected> [OPTIONS]

Update the protection status of a snapshot — toggling the do-not-touch shield 🛡️✨.

<snapshot> (<string>) — snapshot path 📸.

<protected> (<boolean>) — the protection status 🚦.

Optional parameters:

  • --auth-id <string> — authentication ID 🪪.
  • --datastore <string> — datastore name 💾.
  • --ns <string> — namespace 🌸.
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌.
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🗂️.
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️.

📤 proxmox-backup-client snapshot upload-log

proxmox-backup-client snapshot upload-log <snapshot> <logfile> [OPTIONS]

Upload a backup log file — receipts, but make them permanent 🧾💅.

<snapshot> (<string>) — Group/Snapshot path 🗃️.

<logfile> (<string>) — the path to the log file you want to upload 📄.

Optional parameters:

  • --auth-id <string> — authentication ID 🪪.
  • --crypt-mode none|encrypt|sign-only (default=encrypt) — defines whether data is encrypted (using an AEAD cipher), only signed, or neither 🔐.
  • --datastore <string> — datastore name 💾.
  • --keyfd <integer> (0 - N) — pass an encryption key via an already opened file descriptor 🗝️.
  • --keyfile <string> — path to the encryption key; all data will be encrypted using this key 💖.
  • --ns <string> — namespace 🌸.
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌.
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🗂️.
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️.

📊 proxmox-backup-client status

proxmox-backup-client status [OPTIONS]

Get the repository status — the "how are we doing bestie" check-in 💁‍♀️.

Optional parameters:

  • --auth-id <string> — authentication ID 🪪.
  • --datastore <string> — datastore name 💾.
  • --output-format text|json|json-pretty — output format 📄.
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌.
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🗂️.
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️.

🗒️ proxmox-backup-client task list

proxmox-backup-client task list [OPTIONS]

List the running server tasks for this repo user — the group chat of things currently happening 🔄.

Optional parameters:

  • --all <boolean> — also list stopped tasks, because the past matters too 💀.
  • --auth-id <string> — authentication ID 🪪.
  • --datastore <string> — datastore name 💾.
  • --limit <integer> (1 - 1000) (default=50) — the maximal number of tasks to list 🔢.
  • --output-format text|json|json-pretty — output format 📄.
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌.
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🗂️.
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️.

🧾 proxmox-backup-client task log

proxmox-backup-client task log <upid> [OPTIONS]

Display the task log — the full storytime for one task 📖✨.

<upid> (<string>) — Unique Process/Task Identifier 🆔.

Optional parameters:

  • --auth-id <string> — authentication ID 🪪.
  • --datastore <string> — datastore name 💾.
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007 🔌.
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore 🗂️.
  • --server <string> — backup server address (hostname or IP). Default: localhost 🖥️.

🛑 proxmox-backup-client task stop

proxmox-backup-client task stop <upid> [OPTIONS]

Try to stop a specific task — "you're done, bestie, wrap it up" ✋.

<upid> (<string>) — Unique Process/Task Identifier 🆔.

Optional parameters:

  • --auth-id <string> — authentication ID 🪪.
  • --datastore <string> — datastore name 💾.
  • --port <integer> (1 - 65535) (default=8007) — the port your backup server is listening on. Default? 8007, bestie, don't forget it 💅
  • --repository <string> — the repository URL, and the shape is exactly this: [[auth-id@]server[:port]:]datastore
  • --server <string> — where the backup server lives (hostname or IP). Default: localhost 🏠

🌀 proxmox-backup-client unmap [<name>]

Unmaps a loop device that was mapped with map, and releases all its resources. Cleanup era ✨

<name> (<string>) — the archive name, a path to the loopdev (/dev/loopX), or just the loop device number. Omit it entirely and you get a list of all current mappings, plus a forced cleanup of any leftover instances 🧹

🌈 proxmox-backup-client version [OPTIONS]

Shows the client version, and the server version too if you want it 👑

Optional parameters, incoming:

  • --auth-id <string> — authentication ID
  • --datastore <string> — datastore name
  • --output-format text|json|json-pretty — output format
  • --port <integer> (1 - 65535) (default=8007) — backup server port. Default: 8007
  • --repository <string> — repository URL: [[auth-id@]server[:port]:]datastore
  • --server <string> — backup server address (hostname or IP). Default: localhost

🐚 CATALOG SHELL COMMANDS 🐚

okay so these ones are only available once you start up the interactive restore shell, like so:

proxmox-backup-client shell <snapshot> <name.pxar>

cd [<path>]

Changes the current working directory to a new directory 📁

<path> (<string>) — target path

clear-selected

Clears the whole list of files you selected for restore. yeet, but for selections 🫧

deselect <path>

Deselects an entry for restore.

Heads up: you'll get an error back if that entry isn't actually in the list of entries selected for restore 🙈

<path> (<string>) — path to the entry you want removed from the list

exit

Exits the shell. bye bestie 👋

find <pattern> [OPTIONS]

Finds entries in the catalog that match your match pattern 🔍

<pattern> (<string>) — path or match pattern for matching filenames

Optional parameters:

  • --select <boolean> (default=false) — adds the matching filenames to the list for restore

help [{<command>}] [OPTIONS]

Gets help about a specified command (or sub-command) 🫶

<command> (<string>) — the command. This can be a list, so you can specify nested sub-commands. And yes, you can pass it more than once.

Optional parameters:

  • --verbose <boolean> — verbose help

list-selected [OPTIONS]

Lists the entries you currently have selected for restore 📋

Optional parameters:

  • --patterns <boolean> (default=false) — list the match patterns instead of the matching files

ls [<path>]

Lists the content of the working directory, or of the path you give it 👀

<path> (<string>) — target path

pwd

Lists the current working directory. classic, iconic, never misses 💅

restore <target> [OPTIONS]

Restores the sub-archive given by the current working directory into target.

And if you also hand it a pattern, the restore gets limited to a narrower subset of that sub-archive. No pattern, or an empty one? Then the full archive goes to target 🎯

<target> (<string>) — target path for restore on the local filesystem

Optional parameters:

  • --pattern <string> — path or match pattern for matching filenames

restore-selected <target>

Restores the selected entries to the given target path.

important: the target must not exist on the client's filesystem. Like, at all. It's giving "fresh start only" 😤

<target> (<string>) — target path for restore on the local filesystem

select <path>

Selects an entry for restore ✅

Heads up: this returns an error if the entry is already in the list, or if you handed it an invalid path.

<path> (<string>) — target path

stat <path>

Reads the metadata for a given directory entry 🕵️

lowkey a warning: this one is expensive, because the data has to be read from the pxar archive, which means reading over the network. so don't spam it fr fr 😭

<path> (<string>) — target path

✨ COMMON OPTIONS ✨

Most commands that produce output support the --output-format parameter. It accepts these values, slay:

  • text — text format (default). Structured data is rendered as a table.
  • json — JSON (single line).
  • json-pretty — JSON (multiple lines, nicely formatted).

Also, these environment variables can modify output behavior 🎀

  • PROXMOX_OUTPUT_FORMAT — defines the default output format.
  • PROXMOX_OUTPUT_NO_BORDER — if set (to any value), table borders are not rendered.
  • PROXMOX_OUTPUT_NO_HEADER — if set (to any value), table headers are not rendered.
Note: the text format is designed to be human readable, and it is not meant to be parsed by automation tools. So if you need to process the output, please use the json format 💀 (/gen)

💖 DESCRIPTION 💖

This tool implements a backup server client — meaning it can connect to backup servers to issue management commands, and to create or restore backups. that's the whole vibe 🦋

Copyright (C) 2019-2025, Proxmox Server Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <http://www.gnu.org/licenses/>

Author

Proxmox Support Team 🫶

2019-2025, Proxmox Server Solutions GmbH

and that's a wrap on PROXMOX-BACKUP-CLIENT(1) bestie!! 🎀 this page is version 4.2.0, dated Tuesday, 01 January 1980 (yes the date is silly, we love her for it 😭), and it lives in section 1 of the manual. go forth and back things up, you absolute icon 👑💜

📦 where this page comes from