CLI manual

Azivault CLI

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

Download the CLI installer

Download the installer package, open it, and follow the prompts. After installation, run azi in Terminal.

Download azi.pkg Download Azivault for Mac

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.

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='...'
azi hydrate-s3 ~/Desktop/HydratedAzivaultRepository \
  --bucket my-azivault-backups \
  --region auto \
  --endpoint https://storage.example.com \
  --path-style true \
  --access-key-id EXAMPLEKEY

azi verify ~/Desktop/HydratedAzivaultRepository \
  --recovery-password-file ~/Documents/azivault-recovery-password.txt

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

Password options

Use one recovery password option per command. A password file is usually the best choice during a real restore.

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

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

Global options

Option	Use it for
`--help` or `-h`	Show general help or command-specific help.
`--version`	Print the installed CLI version.
`--json` or `--output json`	Return structured output for scripts and dry runs.
`--quiet`	Suppress successful command output.
`--no-color`	Turn off ANSI color in text output.

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, and agent-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. Use list-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='...'
azi hydrate-s3 ~/Desktop/HydratedAzivaultRepository \
  --bucket my-azivault-backups \
  --region auto \
  --endpoint https://storage.example.com \
  --path-style true \
  --access-key-id EXAMPLEKEY

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

export AWS_SECRET_ACCESS_KEY='...'
azi hydrate-s3 ~/Desktop/HydratedAzivaultRepository \
  --bucket my-azivault-backups \
  --region us-east-1 \
  --access-key-id AKIAEXAMPLE

Exit codes

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

Code	Meaning
`0`	The command succeeded.
`1`	An unexpected failure occurred.
`2`	The command was missing information or used an invalid option.
`3`	The command refused to make a risky change without explicit approval.
`4`	The requested backup item or metadata was not found.
`5`	The backup did not pass integrity verification.
`6`	The backup could not be unlocked or credentials were rejected.
`7`	A network or storage-provider operation failed.

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 the S3-compatible backup guide and 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.