CLI reference

The purros binary is the API server, the background worker and the admin tool for setting up, recovering and backing up an install. In Docker, run it inside the api container:

docker compose exec api purros <command> [options]

Outside Docker, configuration comes from the environment and from config/purros.env (or $PURROS_CONFIG_DIR/purros.env) when that file exists. Use --env-file <path> (or PURROS_ENV_FILE) to load a different file. In local development: go run ./cmd/purros <command> in api/.

purros help lists every command, and purros <command> --help explains one with examples. Shell completion: purros completion bash|zsh|fish|powershell.

Global optionsCopy Anchor Link

Commands prompt only when run in a terminal. Destructive commands ask for confirmation. Restoring over existing data asks you to type the company name.

Every command that changes data is recorded in the audit log as the system actor named cli.

ServerCopy Anchor Link

doctorCopy Anchor Link

doctor runs these checks:

Warnings (!) don't fail the run.

Setup & configurationCopy Anchor Link

initCopy Anchor Link

Writes purros.env (with a new PURROS_SECRET) and postgres.env (with a new database password) into the configuration directory, ./config by default ($PURROS_CONFIG_DIR). Both are readable only by you. --force rewrites existing files, but always keeps their PURROS_SECRET and passwords.

purros init --url https://erp.example.com [--dir /opt/purros]

setupCopy Anchor Link

Creates the company, the system roles, the first Owner and, optionally, the first location. It then prints a one-time link (valid 7 days) for the Owner to set a password. It only works once.

In a terminal it asks for everything, with suggestions such as the server's time zone. For scripted installs, pass every value as flags:

purros setup --company "Acme Coffee" --owner-email [email protected] --owner-name "Alex Kim" \
  --timezone America/Chicago --currency USD \
  --location-name "Store 101" --location-external-id 101 --location-cutoff 04:00

configCopy Anchor Link

purros config show      # the effective configuration, secrets masked
purros config check     # validate it

secretCopy Anchor Link

purros secret generate                          # a new random secret
purros secret check                             # does PURROS_SECRET decrypt the stored data?
purros secret rotate --new-secret-file new      # re-encrypt everything with a new secret

Use rotate if PURROS_SECRET may have leaked:

1. Stop PurrOS.
2. Run the rotation. It re-encrypts integration settings, webhook secrets and authenticator secrets in one transaction, and aborts without changes if any value can't be decrypted.
3. Put the new secret in config/purros.env and start PurrOS again.

Keep the old secret as long as you keep backups made before the rotation.

storageCopy Anchor Link

purros storage test [--backups]            # write, read and delete a test file (--backups: the backup bucket)
purros storage init [--backups]            # create the S3 bucket if it doesn't exist
purros storage verify [--checksums]        # every attachment's file is in storage (and matches, with --checksums)
purros storage migrate --to s3|local       # copy all files to the other storage; resumable

emailCopy Anchor Link

purros email test --to [email protected]     # send a test email, showing the SMTP error if it fails
purros email log [--limit 30]              # recent emails: recipient, kind, status and errors

Accounts & recoveryCopy Anchor Link

All account commands take the email address as an argument (or --email).

The last Owner can't be demoted or deactivated.

recover ownerCopy Anchor Link

This is break-glass access for when nobody can sign in. It makes the account an Owner, activates it, clears its lockout, removes its 2FA (unless --keep-mfa) and sessions, and prints a sign-in link.

purros recover owner [email protected]
purros recover owner [email protected] --create --name "Pat Lee"

BackupsCopy Anchor Link

Backups are complete and consistent, and taken while PurrOS keeps running. PurrOS makes them itself, so no pg_dump is needed. Each is a single .purros-backup file, optionally encrypted, and optionally including uploaded files. With PURROS_BACKUP_S3_ENABLED, backups are also uploaded to an S3 bucket. See Backups & upgrades for how they work and how to schedule them.

purros backup create [--dir DIR | --out FILE] [--encrypt] [--passphrase-file F] [--keep N]
                     [--files | --no-files] [--no-upload]
purros backup list [--dir DIR | --remote]          # files (or the S3 bucket), and recent backup runs
purros backup download <name> [--out PATH]         # copy a backup from the S3 bucket
purros backup verify <file | s3:name>              # complete and undamaged?
purros backup inspect <file | s3:name>             # what it contains, and whether PURROS_SECRET matches
purros backup restore <file | s3:name> [--replace] [--no-safety-backup]
purros backup prune [--keep N] [--older-than 30d] [--remote] [--dry-run]

• Where backups go: the default directory is PURROS_BACKUP_DIR, or $PURROS_STATE_DIR/backups when S3 uploads are off. With S3 on and no directory, backups go only to the bucket.
• Remote backups: refer to a backup in the bucket as s3:<name>.
• Passphrase: it comes from --passphrase-file, then PURROS_BACKUP_PASSPHRASE, then a prompt.

ManagementCopy Anchor Link

Integrations, webhook endpoints and the organization can also be managed through the API; see Integrations, Webhooks and Organization & locations.

Planned commandsCopy Anchor Link