CLI manual

Azivault CLI

The azi command-line tool lets you inspect, verify, search, restore, export, and hydrate Azivault backups without installing the app.

Published June 27, 2026 · Commands checked with azi 2026.3 (build 8) on August 31, 2026

Start here

Run azi with no arguments for a short overview, or ask for command-specific help before doing anything that writes files.

azi
azi --help
azi restore --help

What you need before recovery

• The folder that contains your Azivault backup, or access to the S3-compatible bucket that stores it.
• The recovery password saved when the backup plan was created.
• A safe destination folder for restored files or exported backups.

Keep the recovery password outside the Mac being backed up. The CLI can read it from a file or from an environment variable, which is safer than typing the password directly into a command.

Common recovery flow

These commands show a typical local recovery: check the backup, find the right plan and run, browse or search files, then restore to a safe destination.

The examples use /Volumes/Backup/AzivaultRepository as the repository, personal-documents as the plan ID, and8 as the run ID. Replace those values with the paths and IDs shown by your backup.

azi info /Volumes/Backup/AzivaultRepository
azi list-plans /Volumes/Backup/AzivaultRepository
azi verify /Volumes/Backup/AzivaultRepository \
  --recovery-password-file ~/Documents/azivault-recovery-password.txt

azi list-runs /Volumes/Backup/AzivaultRepository \
  --plan personal-documents

azi list /Volumes/Backup/AzivaultRepository \
  --plan personal-documents \
  --run 8 \
  --path documents/taxes \
  --recovery-password-file ~/Documents/azivault-recovery-password.txt

azi search /Volumes/Backup/AzivaultRepository \
  --plan personal-documents \
  --run 8 \
  --name summary \
  --limit 10 \
  --recovery-password-file ~/Documents/azivault-recovery-password.txt

azi restore /Volumes/Backup/AzivaultRepository \
  --plan personal-documents \
  --run 8 \
  --path documents/taxes/summary.pdf \
  --to ~/Desktop/summary.pdf \
  --recovery-password-file ~/Documents/azivault-recovery-password.txt

To recover everything from a run instead of one file, export to a clean folder.

azi export /Volumes/Backup/AzivaultRepository \
  --plan personal-documents \
  --run 8 \
  --to ~/Desktop/AzivaultExport \
  --recovery-password-file ~/Documents/azivault-recovery-password.txt

If the backup is only in S3-compatible storage, hydrate it first and then run the same commands against the local hydrated folder.

export AWS_SECRET_ACCESS_KEY='SECRET_ACCESS_KEY'
azi hydrate-s3 /PATH/TO/HYDRATED_REPOSITORY \
  --bucket BUCKET_NAME \
  --region REGION \
  --endpoint S3_ENDPOINT \
  --path-style true \
  --access-key-id ACCESS_KEY_ID

azi verify /PATH/TO/HYDRATED_REPOSITORY \
  --recovery-password-file /PATH/TO/PASSWORD_FILE

azi export /PATH/TO/HYDRATED_REPOSITORY \
  --plan personal-documents \
  --run 8 \
  --to /PATH/TO/EXPORT_FOLDER \
  --recovery-password-file /PATH/TO/PASSWORD_FILE

Replace the following values:

• SECRET_ACCESS_KEY: the provider's secret access key.
• /PATH/TO/HYDRATED_REPOSITORY: an empty local destination for the hydrated repository.
• BUCKET_NAME: the S3-compatible bucket name.
• REGION: the bucket region, or auto when the provider requires it.
• S3_ENDPOINT: the provider's endpoint URL.
• ACCESS_KEY_ID: the provider's access key ID.
• /PATH/TO/PASSWORD_FILE: the file that contains the Azivault recovery password.
• /PATH/TO/EXPORT_FOLDER: a new or empty folder for the restored files.

Password options

Use one recovery password option per command. During a real restore, a password file avoids exposing the password in command history.

azi verify /Volumes/Backup/AzivaultRepository \
  --recovery-password-file ~/Documents/azivault-recovery-password.txt

export AZI_RECOVERY_PASSWORD='RECOVERY_PASSWORD'
azi search /Volumes/Backup/AzivaultRepository \
  --plan personal-documents \
  --run 8 \
  --name invoice \
  --recovery-password-env AZI_RECOVERY_PASSWORD
unset AZI_RECOVERY_PASSWORD

Replace RECOVERY_PASSWORD with the repository recovery password.

Global options

The following table describes the global command options.

Discovery commands

Use these commands to learn what the installed CLI supports. They are helpful before writing a restore script or asking an agent to inspect a backup.

azi commands --json
azi describe restore --json
azi agent-context --json

commands lists available commands,describe explains one command, andagent-context prints safe workflow guidance for automated callers.

Check a backup location

Start with commands that do not write files. These help you confirm that the backup location is present, readable, and unlockable.

azi info /Volumes/Backup/AzivaultRepository
azi list-plans /Volumes/Backup/AzivaultRepository
azi verify /Volumes/Backup/AzivaultRepository \
  --recovery-password-file ~/Documents/azivault-recovery-password.txt

Find the right plan and run

A backup location can contain more than one plan. Uselist-plans to find the plan ID, then list completed runs for that plan.

azi list-plans /Volumes/Backup/AzivaultRepository

personal-documents    Personal Documents
photo-library         Photo Library

The Mac app creates plans and manages excluded files and folders. To audit that configuration from Terminal, request JSON output. Each plan includes exclusionCount and exclusionGlobs; the glob rules are the same path-aware rules used by the backup engine.

azi list-plans /Volumes/Backup/AzivaultRepository --output json

{
  "schemaVersion": 1,
  "command": "list-plans",
  "plans": [
    {
      "planID": "personal-documents",
      "name": "Personal Documents",
      "exclusionCount": 2,
      "exclusionGlobs": ["Caches/**", "*.tmp"]
    }
  ]
}

azi list-runs /Volumes/Backup/AzivaultRepository \
  --plan personal-documents

The first column from list-runs is the run ID. Use a run from before the file was deleted, corrupted, or changed.

Browse files in a run

File names are protected, so browsing a run requires your recovery password.

azi list /Volumes/Backup/AzivaultRepository \
  --plan personal-documents \
  --run 8 \
  --recovery-password-file ~/Documents/azivault-recovery-password.txt

azi list /Volumes/Backup/AzivaultRepository \
  --plan personal-documents \
  --run 8 \
  --path documents/taxes \
  --recovery-password-file ~/Documents/azivault-recovery-password.txt

Search for a file

Use search when you remember part of a filename but not the exact folder.

azi search /Volumes/Backup/AzivaultRepository \
  --plan personal-documents \
  --run 8 \
  --name invoice \
  --limit 10 \
  --recovery-password-file ~/Documents/azivault-recovery-password.txt

For more predictable matching, add one search mode:--exact, --prefix, or --contains.

Restore one file

Restore to a temporary location first. Azivault refuses to overwrite an existing destination unless you explicitly ask it to.

azi restore /Volumes/Backup/AzivaultRepository \
  --plan personal-documents \
  --run 8 \
  --path documents/taxes/summary.pdf \
  --to ~/Desktop/summary.pdf \
  --recovery-password-file ~/Documents/azivault-recovery-password.txt

If you intentionally want to replace the destination, add--overwrite true. Use a dry run first when you want to check the restore without writing the file.

azi restore /Volumes/Backup/AzivaultRepository \
  --plan personal-documents \
  --run 8 \
  --path documents/taxes/summary.pdf \
  --to ~/Desktop/summary.pdf \
  --dry-run \
  --output json \
  --recovery-password-file ~/Documents/azivault-recovery-password.txt

Export a whole backup run

Use export when you want a full copy of every restorable file and folder from a run.

azi export /Volumes/Backup/AzivaultRepository \
  --plan personal-documents \
  --run 8 \
  --to ~/Desktop/AzivaultExport \
  --recovery-password-file ~/Documents/azivault-recovery-password.txt

Export to a new folder or an empty folder when you want the safest behavior. Add --overwrite true only when replacing matching files is intentional.

Hydrate a backup from object storage

If your only copy is in S3-compatible storage, hydrate it to a local folder first. After hydration, run normal commands against the local folder.

export AWS_SECRET_ACCESS_KEY='SECRET_ACCESS_KEY'
azi hydrate-s3 /PATH/TO/HYDRATED_REPOSITORY \
  --bucket BUCKET_NAME \
  --region REGION \
  --endpoint S3_ENDPOINT \
  --path-style true \
  --access-key-id ACCESS_KEY_ID

Replace the uppercase values with your provider credentials, bucket, region, endpoint, and local destination path.

For AWS S3, use the AWS region and omit --endpoint unless your provider gives you a custom endpoint.

export AWS_SECRET_ACCESS_KEY='SECRET_ACCESS_KEY'
azi hydrate-s3 /PATH/TO/HYDRATED_REPOSITORY \
  --bucket BUCKET_NAME \
  --region AWS_REGION \
  --access-key-id ACCESS_KEY_ID

Exit codes

Scripts must check the exit code. In JSON mode, failures also include a machine-readable error code.

The following table lists the exit codes.

Safety notes

• Prefer --recovery-password-file for real recovery work.
• Use --dry-run --output json before scripted restore or export commands.
• Restore to a temporary folder before replacing current files.
• Do not add --overwrite true unless replacement is intentional.
• Clear environment variables that contain passwords after use.

Related guides

For app-based recovery, read the file restore guide. For storage setup, see theS3-compatible backup guideand external drive guide.

FAQs

Do I need the Azivault app to use the CLI?

No. The CLI is designed for recovery and verification when you prefer Terminal or when the app is unavailable. The Mac app is still the easiest way to create and manage backup plans.

Can the CLI restore files after a subscription expires?

Yes. Existing backups remain recoverable. You still need access to the backup location and the recovery password needed to unlock the backup.

Should I put my recovery password directly in a command?

Avoid that for real recovery work. Prefer a password file or environment variable so the password is not saved in shell history.

Can the CLI recover from S3-compatible storage?

Yes. Use hydrate-s3 to copy the remote backup to a local folder first, then verify, search, restore, or export from that local folder.