Backup EnginebackupEngine
Docs/CLI Reference/JSON Output

JSON Output Mode

Use the --json flag for machine-readable output, enabling automation and integration with other tools.

Using the --json Flag

Every BackupEngine CLI command supports the --json flag. When enabled, the command outputs structured JSON instead of human-readable text. This makes it straightforward to parse output in scripts, feed data into monitoring tools, or build custom dashboards.

Basic usage
# Human-readable output (default)
backupengine backup status "Documents"
# Output: Backup set "Documents": Completed at 2025-12-15 02:15:00 (1.2 GB uploaded)

# JSON output
backupengine backup status "Documents" --json
# Output:
{
  "backup_set": "Documents",
  "status": "completed",
  "start_time": "2025-12-15T02:00:00Z",
  "end_time": "2025-12-15T02:15:00Z",
  "bytes_scanned": 5368709120,
  "bytes_uploaded": 1288490188,
  "chunks_new": 1842,
  "chunks_deduped": 14203,
  "files_processed": 3847,
  "errors": []
}

JSON Response Structure

All JSON responses follow a consistent envelope format. Successful commands include a data payload, while failed commands include an error object.

Success response
{
  "success": true,
  "data": {
    // Command-specific response data
  },
  "meta": {
    "timestamp": "2025-12-15T02:15:00Z",
    "agent_version": "2.4.1",
    "device_id": "dev_abc123"
  }
}
Error response
{
  "success": false,
  "error": {
    "code": "BACKUP_SET_NOT_FOUND",
    "message": "Backup set 'Documents' does not exist",
    "details": "Available backup sets: Source Code, Photos"
  },
  "meta": {
    "timestamp": "2025-12-15T02:15:00Z",
    "agent_version": "2.4.1",
    "device_id": "dev_abc123"
  }
}

Parsing with jq (bash)

jq is the standard tool for parsing JSON in bash scripts. Here are common patterns for extracting data from BackupEngine JSON output.

jq parsing examples
# Get backup status
backupengine backup status "Documents" --json | jq -r '.status'
# Output: completed

# Get bytes uploaded (human-readable)
backupengine backup status "Documents" --json | jq '.bytes_uploaded / 1048576 | floor | tostring + " MB"'
# Output: "1228 MB"

# List all backup set names
backupengine backup-set list --json | jq -r '.backup_sets[].name'
# Output:
# Documents
# Source Code
# Photos

# Find failed backups across all sets
backupengine backup-set list --json | jq -r '.backup_sets[].name' | while read set; do
  STATUS=$(backupengine backup history "$set" --json --limit 1 | jq -r '.runs[0].status')
  if [ "$STATUS" = "failed" ]; then
    echo "FAILED: $set"
  fi
done

# Get deduplication ratio
backupengine backup status "Documents" --json | \
  jq '(.chunks_deduped / (.chunks_new + .chunks_deduped) * 100 | floor | tostring) + "% dedup ratio"'
# Output: "88% dedup ratio"

Parsing with PowerShell

PowerShell natively converts JSON to objects with ConvertFrom-Json, making structured data processing clean.

PowerShell parsing examples
# Get backup status as an object
$status = backupengine backup status "Documents" --json | ConvertFrom-Json
Write-Host "Status: $($status.status)"
Write-Host "Uploaded: $([math]::Round($status.bytes_uploaded / 1MB, 1)) MB"

# List all backup sets with their last status
$sets = (backupengine backup-set list --json | ConvertFrom-Json).backup_sets
foreach ($set in $sets) {
    $history = backupengine backup history $set.name --json --limit 1 | ConvertFrom-Json
    $lastStatus = $history.runs[0].status
    Write-Host "$($set.name): $lastStatus"
}

# Export backup report to CSV
$report = @()
$sets = (backupengine backup-set list --json | ConvertFrom-Json).backup_sets
foreach ($set in $sets) {
    $history = backupengine backup history $set.name --json --limit 1 | ConvertFrom-Json
    $run = $history.runs[0]
    $report += [PSCustomObject]@{
        Name = $set.name
        Status = $run.status
        Time = $run.end_time
        UploadedMB = [math]::Round($run.bytes_uploaded / 1MB, 1)
    }
}
$report | Export-Csv -Path "backup-report.csv" -NoTypeInformation

💡 Tip

The --json flag suppresses all non-JSON output (progress bars, spinners, warnings). If a command produces both stdout (JSON) and stderr (warnings), pipe stderr to null if you only need the JSON data.
Scripting & AutomationAPI Authentication