Docs/CLI Reference/Overview

CLI Overview

Get started with the BackupEngine command-line interface for automation, scripting, and headless operation.

Dual-Mode Agent

The BackupEngine desktop agent operates in two modes: a graphical user interface (GUI) for interactive use, and a command-line interface (CLI) for automation, scripting, and headless server environments. Both modes share the same backup engine, local configuration, and encryption: they are two interfaces to the same underlying agent.

•GUI mode: Launched from the Start menu or the desktop shortcut. Best for interactive setup and monitoring.
•CLI mode: Invoked from a terminal or script using the backupengine command. Best for automation, scheduled tasks, and headless servers.
•Both modes can run at the same time and use the same local database. The app reads its settings when it starts, so reopen it to see a setting changed on the command line.
•The CLI covers status, file backups and restores, listing sets and schedules, reports, diagnostics, the background service and updates. Creating and editing schedules, the server backup wizards (Hyper-V, SQL Server, System State, bare-metal) and encryption setup are done in the app. The Command Reference marks what each command can and cannot do.

When to Use the CLI

The CLI is the preferred interface for several common scenarios.

•Headless servers: Windows servers without a desktop session, where you check and run backups from a remote shell.
•Automation: Running BackupEngine from RMM tools or CI/CD pipelines that can execute a PowerShell script.
•Scripting: Writing PowerShell or bash scripts that include backup and restore operations.
•Monitoring: Querying backup status programmatically with JSON output for dashboards and alerting.
•Fleet checks: Running the same status or health script on many computers through your RMM tool. Each command acts on the computer it runs on; the customer portal is where you manage devices across the account.

Installation and Setup

The CLI is included with the standard BackupEngine desktop agent installer. No separate installation is needed.

Verify CLI installation

# Check that the CLI is available
backupengine version
# Backup Engine Desktop Agent v1.37.0

# The installer adds its folder (C:\Program Files\Backup Engine) to the machine PATH.
# A console that was already open when you installed does not see the new PATH entry:
# open a new console, or call the command by its full path:
& "C:\Program Files\Backup Engine\backupengine.cmd" version

ℹ Note

Today the pre-built agent is for Windows. See Installation for the status of the macOS and Linux builds.

Authentication

The CLI has no login command. It uses the session of the signed-in agent: sign in once in the app, and the CLI, the background service and the app all use that session. backupengine status shows the signed-in account, or Not logged in.

Signing in a computer that has no one at the keyboard

# Redeem an activation code from the customer portal (Device enrollment codes).
# It signs the computer in to the account and registers it as a device.
# If the computer is already signed in, it does nothing and says so.
backupengine enroll --code XXXX-XXXX-XXXX

# Then confirm which account and device this is
backupengine status

⚠ Warning

Never hardcode passwords or activation codes in scripts that are shared or stored in source control. Pass them in through environment variables or your RMM tool's secret store. An activation code works until it expires, reaches its maximum number of uses or is revoked in the portal, so treat it like a password until then.

💡 Tip

For many computers, create one multi-use activation code per site and push the silent-install script through your RMM tool. See Scripting & Automation for the script and Device Enrollment Codes for how codes work.

Compliance Command Reference