Command Reference
Every BackupEngine CLI command in the v1.37.0 agent, with the syntax taken from the agent source and what each command does today.
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 the commands that report (the JSON Output page lists them) for machine-readable output suitable for piping into jq; commands that do work, such as backup start, print text.
General syntax
backupengine <command> [args...] [--json] backupengine help # Top-level usage backupengine version # Print agent version
ℹ Note
Sign-in is GUI-only. The CLI inherits the desktop session — once you have signed in through the desktop app, the CLI uses the same access token and device key. There is no
backupengine login command.⚠ Warning
Locked computers (v1.37.0). While the app asks for sign-in (Stay signed in off, or required by your organization), commands that restore data, reveal backed-up data or change settings — all of
restore, config set, sets email, backup stop, update install, enroll, the service install / remove commands, the assistant — must be run from an elevated (Administrator) prompt. Otherwise they stop with exit code 1 and "This computer is locked. Run this from an elevated prompt, or unlock the app." Status, version, help, gui-status, service-status, update check, listing commands and backup start stay available.Status & Version
backupengine status
backupengine status # Account + plan + last backup summary backupengine version # Agent version (e.g. "Backup Engine Desktop Agent v1.37.0")
status prints a single-screen overview: account email, plan, device id, backup-set and active-set counts, the start time and result of the latest job, and the success/failure totals of the last five jobs. It reports what has run, not when the next backup is due; schedule list shows each set's schedule. Pair with --jsonfor monitoring scripts.
Connectivity
backupengine 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
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
v1.12.2 added
sets create file and sets delete for headless deployments. --dest accepts local and network (both require --local-path), cloud, s3-compat or azure-blob. 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
Server-class set types (
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
backupengine backup start <set-name> # Run one set now, in this console (v1.12.2: real runner, not stub) backupengine backup run <set-name> # Alias for "start" backupengine backup list [N] # The last N jobs (default 10) recorded by the app and the background service
backup start needs a set name (there is no run-all form), waits until the run is finished and exits 0 when every destination succeeded or 1 when one failed. Its result is stamped on the set (last_run and last_run_status in sets list --json), but it is not added to backup list or counted by status. 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.⚠ Warning
There is no working command-line cancel in this release.
backup stop only prints a message; it does not stop anything. To end a run you started with backup start, press Ctrl+C in its console. To cancel a backup running in the app, use Cancel on the set's card (see Cancel Operations for what each cancel does to in-flight artefacts).Restore
backupengine 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
CLI restore handles file backups only through v1.12.4. Server-workload restore (SQL chain replay, Hyper-V VM restore with chain reassembly, BMR/System State image restore) is still GUI-only.
restore run rejects non-file manifests with a clear error so you do not get a partial restore.ℹ Note
v1.37.0:
restore list tells “no backups” apart from “could not reach the storage” — a destination that did not answer is listed with its reason (unreachable_destinations in JSON), a manifest that failed to download counts in fetch_error_count, and a newest restore point that could not be loaded appears in latest_load_failures. restore run without --version refuses (exit 1) when the newest point could not be loaded rather than quietly restoring an older one; with --version it restores the point you asked for and prints the warning. Listing from a script waits longer than the app does (up to five minutes per cloud request) so a slow link is not mistaken for an empty one.ℹ Note
There is no
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
backupengine schedule list # Every set's schedules, extra times included, and its last run
backupengine schedule list --json # The same, machine-readable ("additional_schedules", "summary")ℹ Note
Schedules, extra times included, are edited in the app or the customer portal. The CLI is read-only here so cron jobs and monitoring scripts can audit cadence drift without modifying state. Scripts read schedules from
schedule list --json; sets list --json prints each set as stored, with its extra times as JSON text.Diagnostic Logs
backupengine 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)
Service management — flat command names, require admin
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
These are flat commands (
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
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
Setting/changing the passphrase, scheduling DEK rotation, and triggering an immediate rotation are GUI-only — the rotation flow has a triple-confirm prompt intentionally not exposed on the CLI. Use
encryption status to verify a rotation completed.Hyper-V
backupengine hyperv
backupengine hyperv status # Is the Hyper-V role installed on this host? backupengine hyperv list # Enumerate VMs (id, state, gen, memory, disks) backupengine hyperv cleanup-checkpoints [vm] [--list] # Merge leftover BackupEngine-Reference-* checkpoints (--list previews) backupengine hyperv merge-checkpoints <vm> --yes # Fold a VM's foreign checkpoint chain into its base disk (irreversible)
ℹ Note
Hyper-V backup sets (which VMs, RPO preset, retention) are created and run from the app — the wizard writes the set to the local DB and the scheduler or Run Now starts it.
hyperv list is the same enumeration the GUI uses to populate the picker.⚠ Warning
backupengine hyperv backup <set-name> exists, but in this release it only checks that a Hyper-V set with that name exists and prints a message; it does not start a backup. Run Hyper-V sets from the app.Selftest (validation harness)
backupengine selftest
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
backupengine devices # Show this device's registered id
ℹ Note
Listing and managing all registered devices on the account is done through the Customer Portal. The CLI surfaces only the local device id for scripting.
Notifications
backupengine 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 # Lists the recipients; it does not send an email in this release
Team / Users
backupengine users
backupengine users list # Prints the portal's Team page link (no team data in the CLI) backupengine users invite <email> <role> # Does NOT invite — manage the team in the portal backupengine users remove <email> # Does NOT remove backupengine users role <email> <new-role> # Does NOT change a role
⚠ Warning
The
users commands do not read or change your team, and the desktop app has no team management of its own. From version 1.38 they print the Team page link, and invite, remove and role exit with code 1; version 1.37 and earlier print a sample row or a confirmation such as “Invitation sent” although nothing changed. Invite, remove and change team members in the customer portal (Team) — roles are Admin, Operator, Viewer and User, and every invited person uses a seat. See Team members, roles and seats.Plans & Billing
backupengine plans / backupengine billing
backupengine plans list # Available subscription tiers backupengine plans change <plan-id> # Change plan; a plan that needs a subscription prints the checkout link backupengine billing status # Plan + storage usage backupengine billing upgrade <professional|server|ai_infra|enterprise> # Prints the portal billing link backupengine billing addons list # Prints the portal billing link (add-ons are managed there) backupengine billing invoices # Prints the portal billing link (invoices are listed there) backupengine billing portal # Prints the portal billing link
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, and billing addons and billing invoices do not list anything themselves.
Reports
backupengine reports / backupengine usage-report
backupengine reports list [N] # The last N per-backup reports (default 20), recent first backupengine reports show <id> # Full text of one report backupengine reports send <id> [email,email] # Re-send the report email (optionally to these addresses) backupengine reports retry-pending # Re-submit reports that could not be posted when the backup finished backupengine usage-report show <weekly|monthly> [start-date] # Org rollup; start-date is YYYY-MM-DD (v1.7.0+) backupengine usage-report send <weekly|monthly> [emails] # Email the rollup (default: the notification recipients)
usage is an alias for usage-report.
AI Assets (v1.10.0)
backupengine ai-assets (alias: ai)
backupengine ai-assets scan # Detect local AI assets (vector stores, model caches, ...)
backupengine ai-assets list [--type <t>] [--provider <p>] # Detected assets, optionally filtered
backupengine ai-assets status # Whether AI backup is enabled on your plan, and what was detected
backupengine ai-assets connect --provider <p> --api-key <k> [--name <name>] [--endpoint <url>]
backupengine ai-assets connections [list|delete <id>] # Saved cloud AI connections
backupengine ai-assets backup --connection <id> --index <name> # Snapshot one index of a connected vector DB
backupengine ai-assets snapshots --asset <id> # List the snapshots of an asset
backupengine ai-assets restore --connection <id> --to <new-name> \
[--snapshot-file <path>] [--from-snapshot <id> --asset <id>] # Restore a snapshot into a new indexℹ Note
AI asset backup ships with the Infra Teams Edition (formerly AI Infra Backup), the v1.10.0 tier for protecting model caches, vector databases (Pinecone, Weaviate, Qdrant, Chroma), and AI workspace exports. Local assets are discovered with
scan; cloud assets are added with connect.Restore Assistant (v1.11.0)
backupengine assistant (aliases: ask, assistant)
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.
- The lock screen (v1.37.0, replaces “Show login screen on startup”) and auto-unlock encryption between sessions (v1.11.5) — the CLI uses the signed-in session and follows the lock (see Locked computers above); the “Stay signed in” preference itself can be read and set with
backupengine config(keystay_signed_in). - Parallel-disk Hyper-V backups (v1.11.6) — the concurrency cap is a runner-level construction-time parameter, not a per-run flag.
ℹ Note
The full list of GUI-driven settings (per-set retention, multi-destination edits, schedule cadence, encryption mode) is documented under Backup Sets and Key Management.
Configuration
backupengine config
backupengine config get <key> # Read a setting backupengine config set <key> <value> # Write a setting # config get reads: language, encryption_mode, cdp_enabled, cdp_interval, # bandwidth_limit, theme, stay_signed_in, # run_backups_in_worker # v1.37.0: on (default) runs each backup in its own # # process; off runs it inside the app window as before # config set stores the value under exactly the key you type. Two keys that config get shows # are stored under a longer name, and config set needs that name: backupengine config set bandwidth_limit_mbps 10 # global upload limit in Mbps, 0 = unlimited backupengine config set cdp_interval_minutes 30 # CDP check interval backupengine config set cdp_enabled 1 # CDP on (1) or off (0) backupengine config set stay_signed_in on # on | off
config get bandwidth_limit and config get cdp_interval read those stored values back. The app reads its settings when it starts, so reopen it to see a value set here. For the global upload limit use 0, 1, 5, 10, 25, 50 or 100, the values the app's Upload limit list offers (see Bandwidth Throttling). For settings the CLI doesn't expose (custom retention rules and schedule editing, for example) use the desktop GUI — those write multi-field structures the simple key/value CLI form doesn't cover. The per-set upload limit is the opposite case: it is set only from the command line, with sets bandwidth.
Updates
backupengine update
backupengine update # Check whether an update is available backupengine update check # (alias for the bare command) backupengine update install # Install if available (v1.37.0: refuses while anything is running) backupengine update install --force # v1.37.0: install anyway — only when you are sure nothing is running
ℹ Note
The desktop GUI shows an in-app update banner that handles install-type-aware paths (MSIX via
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.⚠ Warning
v1.37.0:
update install checks the whole machine first — a backup or restore in the app, a scheduled backup in the background service, a command-line backup, restore or Hyper-V checkpoint merge in another console — and refuses with exit code 1 naming what is running. It also refuses when it cannot tell (for example a process it is not allowed to inspect from an unelevated prompt); retry from an elevated prompt, or pass --force if you are certain. A job row left behind by a crash is called out as possibly stale so --force is an informed choice.Installer / maintenance (v1.37.0)
backupengine gui-status
backupengine gui-status # exit 0 = no app running, 10 = app idle, 11 = app busy (backup or restore),
# 12 = background service or command-line job running, 1 = could not tell
backupengine gui-status --json # same, with pid, mode, running jobs and the heartbeat details
backupengine request-gui-quit # ask the running app to close itself gracefully (writes a marker the app polls)
backupengine request-gui-quit --wait 30 # ...and wait up to 30 s for it to goℹ Note
These two commands exist for the installer: the v1.37.0 setup detects an update, asks the running agent whether it is busy, closes it gracefully when it is idle and asks you to retry when a backup or restore is in progress. They are safe to call from your own scripts — both answer within 20 seconds and exit 1 when they cannot tell — but they never stop a backup.
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.