How to Use bzCLI

bzCLI is a cross-platform tool designed to enable Remote Monitoring and Management (RMM) systems to configure and administer the Backblaze Backup Client. It provides enterprise IT administrators with the ability to remotely manage backup configurations on client computers without requiring direct user interaction.

The tool follows a Git-style command syntax, offering an intuitive interface with named arguments instead of position-based parameters, making it easier to use correctly and debug when issues arise.

Installation

No separate installation of bzCLI is required. The tool is installed automatically as part of the Backup Client installation.

Installation Paths

Command Syntax

Two primary syntax forms are supported:

Global Options

bzcli [-h|--help] [-v|--version] [--verbose]

Each option begins with a hyphen (-) for short form or double hyphen (--) for long form.

Command Execution

bzcli <command> [<args>]

Where command specifies the operation to perform, followed by optional arguments.

Output and Exit Status

Non-error results are printed to stdout. If an error occurs, bzCLI prints details about the error to stderr. The utility returns 0 on success, or a non-zero value on error.

Commands

action

Causes the backup software to perform a single operation. Only one operation is allowed per command invocation; to run multiple operations, invoke bzcli more than once.

Syntax

bzcli action [--group <groupid:grouptoken>] --<operation> [arguments...]

Options

Account Authentication

Some action operations require account authentication to prevent unauthorized changes. Provide a group ID and group token separated by a colon:

bzcli action --group groupid:grouptoken --operation [arguments...]

This example shows how to set a PEK using group authentication:

bzcli action --group 27194:c24a998252466cb --set-pek foobar

Private Encryption Key (PEK) Operations

A PEK provides an additional layer of security for backed-up data. When a PEK is set, it is impossible to access backup data without it. If you forget a PEK, Backblaze cannot reset it or recover your data.

To check whether a backup already has a PEK set, run:

bzcli report -v /backup/installation/has_pek

This command returns true or false.

configure

Updates the configuration of Backblaze's backup software using key-value pairs to specify what to change.

Syntax

bzcli configure [-j|--json <filepath>] [--json-example] [-p|--print] [-v|--value <key=val>]

Options

Input Methods

There are two ways to specify configuration changes:

• Single value: Use -v or --value with a key=value argument. For example, to change the computer name:
  

  bzcli configure -v online_hostname=MyNewComputerName

• JSON file: Use -j or --json to apply one or more changes from a JSON input file. Use --json-example to print a sample file.

Operation

The configure command validates and parses the input, reads the current bzinfo.xml configuration file, applies the specified settings, and writes the updated configuration back to bzinfo.xml. Unrecognized configuration keys are silently ignored.

Exit Status

report

Prints information about Backblaze's backup software and status. Reports any problems analyzing backup status to stderr.

Syntax

bzcli report [--exit-on-error] [-f|--format <format>] [-v|--value <query>]

Options

Output Format

Reports are output to stdout in JSON format. Two formats are supported:

• json — Pretty-printed JSON with line breaks and indentation (default).

• minijson — Minified JSON, all on one line with whitespace omitted.

Timestamps

Reports include timestamps in two formats:

• gmt_millis — Number of non-leap milliseconds since the Unix epoch (00:00:00 UTC, 1 January 1970).

• gmt_time — UTC time in YYYYMMDDhhmmss format.

Timestamps may also be the string none when a value is not applicable. For example, if license renewal has never failed, the renewal failure time is none.

Querying Single Values

Use the -v or --value option with a slash-delimited query path to retrieve a specific value from the report:

bzcli report -v /backup/account/email

If the query resolves to a JSON object or array rather than a scalar value, the full matching element is printed. For more advanced querying (such as extracting individual values from arrays), pipe the full JSON output to a tool like jq.

Examples

# Get the account email address
bzcli report -v /backup/account/email

# Check whether a PEK is set
bzcli report -v /backup/installation/has_pek

# Get the full report in minified JSON
bzcli report --format minijson

Configuration Settings Reference

The following settings can be configured using the configure command, either via the -v flag or a JSON input file.

Backup Settings

File Exclusion Settings

Identity and Preferences

Administrative Lock Settings

Network Settings

Example JSON Configuration File

Run bzcli configure --json-example to print a full sample. The following is an abbreviated example:

{
        "settings": {
        "online_hostname": "MyComputerName",
        "backup_schedule_type": "continuously",
        "num_backup_threads": 8,
        "net_auto_throttle": true,
        "excludefiletypes_add": [
        {
        "ext": "xxx"
        },
        {
        "ext": "yyy"
        }
        ],
        "blocked_networks_add": [
        {
        "blocked_network_name": "CafeWifi",
        "blocked_network_mac_addr": "10:c4:ca:69:66:64"
        }
        ],
        "lock_schedule": true
        }
        }

Error Handling

Descriptive error messages are provided to help administrators diagnose and resolve issues. Common error scenarios include:

• Invalid or malformed JSON configuration file

• Missing or inaccessible configuration files

• Insufficient permissions to modify settings

• Unrecognized configuration keys (these are silently ignored)

Platform Notes

Unicode Support

Unicode is fully supported in command-line arguments. On macOS, arguments are interpreted as UTF-8. On Windows, the tool uses the wmain() entry point to accept UTF-16LE encoded arguments, which are automatically converted to UTF-8 for internal processing.

RMM Integration

bzCLI is designed for integration with enterprise RMM systems. These systems typically invoke bzcli through shell scripts to automate backup configuration across managed devices.