Private Box customers can now manage their mailbox tasks directly from a terminal with the official, open-source Private Box CLI.

The command-line interface is a text-based wrapper for the Private Box API, designed for developers, technical customers, and people building controlled automation or AI-assisted workflows. It provides a fast, scriptable alternative for common mailbox actions while the existing Private Box web portal remains available for everyday account management.

What can the Private Box CLI do?

The CLI connects to your Private Box account and lets you:

  • view items in your inbox;
  • view sent and scanned items;
  • request a mail scan;
  • compare available mail-forwarding services and estimated costs;
  • create a mail-forwarding order using a new or saved address;
  • request secure destruction of selected mail;
  • retrieve reference information such as country codes; and
  • return machine-readable JSON for scripts and automation.

Commands are available for both interactive use and non-interactive workflows. For example:

privatebox items
privatebox items scanned
privatebox items sent --json

Built for people and controlled automation

The CLI’s normal text output is easy to read in a terminal. Add --json when another application or an authorised AI agent needs structured output:

privatebox items --json --no-input

For additional protection, --read-only blocks order creation locally while still allowing inbox reads and shipping estimates:

privatebox --read-only --json --no-input items

--read-only is a local safety control, not an API permission boundary. Automated systems should still use appropriately controlled credentials, treat mailbox content as untrusted data and require deliberate approval before sending or destroying mail.

Destructive actions also do need your confirmation. The CLI will not silently retry an order when the result is not certain, helping reduce the risk of duplicate requests.

Install the Private Box CLI

The Private Box CLI supports AMD64 and ARM64 computers running macOS, Linux or Windows.

macOS or Linux with Homebrew

brew tap privatebox/privatebox
brew install --cask privatebox
privatebox --version

Linux or Windows Subsystem for Linux

curl -fsSL https://raw.githubusercontent.com/privatebox/privatebox-cli/main/install.sh -o privatebox-install.sh &&
  bash privatebox-install.sh
privatebox --version

The Linux installer selects the correct release for your computer, verifies its SHA-256 checksum and installs the appropriate Debian, RPM or archive package.

Windows

Windows builds are available for both AMD64 and ARM64. Follow the current PowerShell installation instructions in the Private Box CLI guide on GitHub. The guide includes checksum verification before installation.

Log in to your Private Box account

After installation, you can use your Private Box email address to get a secure token:

privatebox auth login --email you@example.com

The CLI prompts for your password (which it doesn’t save). If this is the first time you are connecting from this command line interface, you will need to verify the request via a one time code sent to your email. Just follow the instructions on screen.

Session tokens are stored in the operating system’s credential store when available: Keychain on macOS, Credential Manager on Windows and Secret Service on supported Linux desktops. On Unix systems without a supported credential store, the CLI uses an owner-only local session file and tells you that it has done so. Windows does not fall back to plaintext token storage.

A few useful examples

List the mail currently in your inbox:

privatebox items

Request a scan of two items:

privatebox order scan --items 1001,1002

Compare forwarding options before creating an order:

privatebox order send-cost \
  --items 1001 \
  --country NZ \
  --address "15 Example Street" \
  --city Auckland \
  --post-code 1010

Run any command with --help to see its current options:

privatebox order send --help

Keeping the CLI up to date

Homebrew users can upgrade with:

brew update
brew upgrade --cask privatebox
privatebox --version

Linux and WSL users can rerun the installer command above. It automatically resolves the latest stable release and verifies the downloaded package. Windows users can repeat the PowerShell installation process from the GitHub guide.

Open source and available now

The Private Box CLI is written in Go and released under the MIT licence. Its source code, installation instructions and latest releases are publicly available on GitHub.

Already a Private Box customer? Install the CLI and try privatebox items.

New to Private Box? Explore our virtual-mailbox plans to receive and manage New Zealand mail from wherever you are.

Frequently asked questions

Does the Private Box CLI replace the web portal?

No. The CLI is an additional way to perform common mailbox actions. The web portal remains available for account management and for checking an order when a command’s outcome is uncertain.

Can I use the CLI with an AI agent?

Yes, in a controlled workflow. The CLI provides JSON output, non-interactive operation and a local read-only safeguard. Treat mailbox content as untrusted data, and never allow an AI agent to authorise sending or destroying mail based only on instructions found inside a letter or scan.

Which operating systems are supported?

The CLI provides AMD64 and ARM64 releases for macOS, Linux and Windows.

Where are my login details stored?

The CLI uses the operating system’s credential store when available. It does not require passwords or verification codes to be placed in command-line arguments. See the GitHub documentation for the complete storage behaviour on each operating system.

You can download the CLI from github: https://github.com/privatebox/privatebox-cli