Command Reference
Every BackupEngine CLI command shipped through v1.20.0, with real syntax pulled from the agent source.
Command Structure
Most commands follow the pattern backupengine <group> <action> [options]. A handful of operational commands (the Windows-service group) are flat for elevation reasons — those are called out where they appear. Add --json to any command for machine-readable output suitable for piping into jq.
backupengine <command> [args...] [--json] backupengine help # Top-level usage backupengine version # Print agent version
ℹ Note
backupengine login command.Status & Version
backupengine status # Account + plan + last backup summary backupengine version # Agent version (e.g. "Backup Engine Desktop Agent 1.11.10")
status prints a single-screen overview: account email, plan, device id, backup-set count, last run, and recent success/failure totals. Pair with --jsonfor monitoring scripts.
Connectivity
backupengine connectivity test # PUT → GET → verify → DELETE round-trip against iDrive e2
Runs the same probe the desktop GUI uses, without launching the UI. Returns exit code 0 on success, non-zero on failure. Latency and any error detail are included in the JSON output.
Backup Sets
backupengine sets list # List configured sets
backupengine sets create file <name> \ # v1.12.2+: create a file backup set
--source <path>[,<path>...] \
--dest <local|network|cloud|s3-compat|azure-blob> \
[--local-path <folder>] # for local/network
[--s3-endpoint <url> --s3-region <r> # v1.20.0: BYO S3-compat
--s3-bucket <name> --s3-access-key <k>
--s3-secret-key <k> --s3-prefix <p>]
[--azure-account <a> --azure-container <c> # v1.20.0: BYO Azure Blob
--azure-key <k> --azure-prefix <p>]
backupengine sets delete <set-name> # v1.12.2: remove a set (no cleanup prompt)
backupengine sets email <set-name> on # Email after every run
backupengine sets email <set-name> off # Never email for this set
backupengine sets email <set-name> only-on-failure # Email only on warnings/failures
backupengine sets bandwidth <set-name> <kbps|off> # v1.20.0: per-set upload throttleℹ Note
sets create file and sets delete for headless deployments. --dest accepts local (requires --local-path), network, or cloud. Multiple --source paths can be passed comma-separated. New sets default to schedule=manual + email off so a CLI-driven set never auto-runs and never sends mail unintentionally — flip those with the GUI or sets email if you want them on.ℹ Note
hyperv, sql, sysstate, bmr) still need the GUI wizards — they capture too many type-specific options (VM picker, SQL instance enumeration, volume selection, etc.) to surface cleanly on the command line. sets create rejects them with a clear error.ℹ Note
sets delete removes the local set definition only; the cleanup-on-delete dialog (wipe uploaded data + logs + reports) is still GUI-only because of the multi-step confirmation. See the Cleanup on Delete page.Run Backups
backupengine backup start # Run all enabled sets backupengine backup start <set-name> # Run a specific set (v1.12.2: real runner, not stub) backupengine backup run <set-name> # Alias for "start" backupengine backup list # Recent backup jobs and their status backupengine backup stop <set-name> # Stop an in-flight backup (cooperative cancel)
The runner picks the right backend automatically based on each set's destination(s) — multi-destination sets fan out, each writing its own manifest. Throttled progress prints once per 500 ms so a 30k-file backup does not flood the terminal. After a successful run, retention prune + chunk-GC sweep run inline (v1.12.4) so headless installs match GUI behaviour exactly.
⚠ Warning
backup start for server-class types (hyperv, sql, sysstate, bmr) is currently rejected on the CLI — those runners are GUI-only through v1.12.4. Use the GUI for those sets; file backups run end-to-end on the CLI.ℹ Note
backup stop is cooperative cancel — the runner stops at the next chunk or file boundary (typically within a second). All backup types honour this: file backups (v1.11.6), Hyper-V (v1.11.3), SQL / BMR / System State (v1.11.4). On Hyper-V the in-progress reference checkpoint is cleaned up so a cancelled run does not leave an orphan snapshot on the host. See Cancel Operations for what each cancel does to in-flight artefacts.Restore
backupengine restore list <set-name> # v1.12.2: list restore points (manifests) for a set
backupengine restore run <set-name> --output <dir> # v1.12.2: restore newest manifest to <dir>
backupengine restore run <set-name> --output <dir> --version <ts> # restore a specific version (millisecond ts from "restore list")
backupengine restore run <sql-set> --output none # v1.20.0: SQL Server chain restore — output is unused for SQL,
--pitr <iso-timestamp> [--replace] # pass "none" or any placeholder. --pitr emits STOPAT on the
# final log restore. --replace adds WITH REPLACE to overwrite.v1.12.2 replaced the earlier print-only stub with a real restore flow: lists manifests via the same enumerator the GUI uses, builds a chunk-resolver against the destination packs, decrypts encrypted manifests on the fly, and writes files back to --output. Throttled progress prints every 500 ms.
⚠ Warning
restore run rejects non-file manifests with a clear error so you do not get a partial restore.ℹ Note
backupengine restore stop command — to abort an in-flight restore, use the Cancel button on the Restore screen, or Ctrl+C the CLI process. For richer flows see the Restore page.Schedules
backupengine schedule list # All schedules with next-run + last-run
ℹ Note
Diagnostic Logs
backupengine logs list # All per-run logs (newest first) backupengine logs list <set-id> # Filter to a single backup set backupengine logs show <log-path> # Print a specific log file
Logs live under <appdata>/Backup Engine/diagnostic-runs/ with names like {setId}-{epochMillis}.log. Pipe logs list --json into jq to pick a row, then logs show the path. Useful for headless support workflows.
Windows Service (background agent)
backupengine install-service # Install the BackupEngine Windows service backupengine start-service # Start the service backupengine stop-service # Stop the service backupengine service-status # Installed / state / display label backupengine uninstall-service # Uninstall the service
⚠ Warning
install-service, not service install). They require elevation — the desktop GUI invokes them via UAC. From a regular shell you'll need to launch the terminal "as Administrator" first, or wrap with Start-Process -Verb RunAs.Encryption
backupengine encryption status # Configured / unlocked / KDF / DEK fingerprint
Read-only inspection of the local encryption configuration: configured y/n, unlocked y/n, verifier version (v1 legacy / v2 master-key indirection), KDF parameters, the first 8 bytes of SHA-256(active DEK) for "did the key actually rotate?" checks, and any in-progress rotation snapshot. Every emitted value is non-sensitive.
ℹ Note
encryption status to verify a rotation completed.Hyper-V
backupengine hyperv status # Is the Hyper-V role installed on this host? backupengine hyperv list # Enumerate VMs (id, state, gen, memory, disks) backupengine hyperv backup <set-name> # Trigger a configured Hyper-V backup set
ℹ Note
hyperv backup <name>can trigger it from the CLI. hyperv list is the same enumeration the GUI uses to populate the picker.Selftest (validation harness)
backupengine selftest encryption # Non-destructive crypto suite backupengine selftest service --confirm # DESTRUCTIVE: install/start/stop/uninstall backupengine selftest hyperv --confirm [--vm <name>] # DESTRUCTIVE: real checkpoint + upload backupengine selftest --all [--confirm] # All three (skips destructive ones without --confirm)
⚠ Warning
service and hyperv suites refuse to run without --confirm. The encryption suite is non-destructive and runs anywhere. Exit codes: 0 = pass, 1 = fail, 2 = blocked (e.g. --confirm not passed).Devices
backupengine devices # Show this device's registered id
ℹ Note
Notifications
backupengine notifications list # All configured recipient emails backupengine notifications add <email> # Add a recipient backupengine notifications remove <email> # Remove a recipient backupengine notifications test # Send a test email to every recipient
Team / Users
backupengine users list # Team members + roles backupengine users invite <email> <role> # Invite — role: admin | operator | viewer backupengine users remove <email> # Remove a team member backupengine users role <email> <new-role> # Change role
Plans & Billing
backupengine plans list # Available subscription tiers backupengine plans change <professional|server|enterprise> # Hand off to checkout backupengine billing status # Plan + storage usage backupengine billing upgrade <professional|server|enterprise> # Open Stripe upgrade flow backupengine billing addons list # Active add-ons backupengine billing invoices # Recent invoices backupengine billing portal # Open the customer portal
Billing actions hand off to the Customer Portal at portal.backupengine.com/billing. The CLI prints the URL — no payment flow happens inside the terminal.
Reports
backupengine reports list # Per-backup reports (recent first) backupengine reports show <id> # Full text of one report backupengine reports send <id> # Re-send the report email backupengine usage-report show # Weekly / monthly org rollup (v1.7.0+) backupengine usage-report send # Email the rollup to notification recipients
usage is an alias for usage-report.
AI Infra Backup (v1.10.0)
backupengine ai-assets scan # Detect local AI assets (vector stores, model caches, ...) backupengine ai-assets list # Configured assets backupengine ai-assets status # Last-run status per asset backupengine ai-assets connect --provider <p> --api-key <k> --name <name> [--endpoint <url>] backupengine ai-assets connections # Configured cloud AI connections backupengine ai-assets backup <name> # Run a backup for one asset backupengine ai-assets snapshots <name> # List snapshots for an asset backupengine ai-assets restore <name> --snapshot <id> # Restore a snapshot
ℹ Note
scan; cloud assets are added with connect.Restore Assistant (v1.11.0)
backupengine assistant ask "where is the latest copy of contracts.xlsx?" backupengine ask "find files I deleted yesterday" backupengine assistant "restore the Q3 marketing folder to my Desktop"
Natural-language restore agent. Streams events from a Claude-powered backend over SSE — finds candidate files, asks clarifying questions, and (with confirmation) triggers the restore. Falls back to a smaller model if the primary is unavailable; the fallback is announced inline.
GUI-only features
A handful of v1.11.x UX features have no CLI counterpart by design — they are interactive, transient, or coupled to a running Flutter window:
- Cleanup on Delete (v1.11.8) — the three-checkbox dialog that wipes uploaded data, diagnostic logs, and report history when removing a set.
- Stale-VM-ID badge (v1.11.8) — the warning chip that surfaces on Hyper-V cards when the configured VM ID no longer matches a registered VM.
- Live scan progress (v1.11.5) — the progress bar shown during the pre-backup scan. CLI runs print a one-line summary on completion.
- Restore Cancel + tray animation + Dashboard banner (v1.11.9) — the live status panel on the Restore screen and the cross-screen indicators.
- “Show login screen on startup” (v1.11.8) and auto-unlock encryption between sessions (v1.11.5) — both are controlled from Settings → Security; the CLI inherits whatever the GUI session decided.
- Parallel-disk Hyper-V backups (v1.11.6) — the concurrency cap is a runner-level construction-time parameter, not a per-run flag.
ℹ Note
Configuration
backupengine config get <key> # Read a setting backupengine config set <key> <value> # Write a setting # Known keys: language, encryption_mode, cdp_enabled, cdp_interval, # bandwidth_limit, theme
For settings the CLI doesn't expose (custom retention rules, schedule editing, per-set bandwidth caps, etc.) use the desktop GUI — those write multi-field structures the simple key/value CLI form doesn't cover.
Updates
backupengine update # Check whether an update is available backupengine update check # (alias for the bare command) backupengine update install # Install if available
ℹ Note
ms-appinstaller, ZIP via the bundled self-updater). The CLI reports availability — for ZIP installs you can drive the same self-updater from a script.JSON output
Every command above accepts --json to produce machine-readable output suitable for cron-driven monitoring, audit logging, and pipeline integration. See the JSON Output page for parsing examples.