CLI reference

The walwarden CLI ships one command: restore. Distribution: walwarden-cli on npm (bin: walwarden).

npx --yes walwarden-cli restore [flags]

Required flags

--manifest <sha256>

The SHA256 hex hash of the backup manifest to restore from. Must be exactly 64 lowercase hex characters.

The dashboard one-liner pre-fills this from the backup artifact you selected. If you construct the command manually, copy the hash from the backup detail page.

walwarden restore \
  --manifest a3f1c2d4e5b6...64hexchars \
  --target 'postgresql://...' \
  --mode new_database

--target <dsn>

The Postgres DSN of the target database to restore into. The password may be provided:

• Inline in the DSN: postgresql://user:password@host:5432/db
• Via the PGPASSWORD environment variable (the CLI merges it into the DSN automatically)
• Via an interactive prompt if the password is omitted from both the DSN and PGPASSWORD

The target DSN is never sent to walwarden's servers. It stays on your machine.

--mode <new_database|in_place>

Controls how pg_restore is invoked. See Restore modes for a full description.

• new_database — uses pg_restore --create. Creates a new database named after the source on the target cluster. Requires the database name to not already exist.
• in_place — uses pg_restore --clean --if-exists. Drops and recreates all objects in an existing target database. Requires --confirm-destructive.

Optional flags

--confirm-destructive

Required when --mode in_place. Absent for new_database. If this flag is missing and --mode in_place is specified, the CLI exits with code 2 before making any API call.

walwarden restore \
  --manifest <sha256> \
  --target 'postgresql://user:password@host:5432/existing-db' \
  --mode in_place \
  --confirm-destructive

--json

Emit structured JSONL on stdout instead of the interactive progress view. One record per state transition, format {"state":"...","at":"<iso>","payload":{...}}.

Auto-enabled when stdout is not a TTY (for example, when piping to jq or running in CI).

walwarden restore ... --json | jq '.state'

--no-color

Disable ANSI color codes in the progress output. Auto-enabled in non-TTY contexts.

Environment variables

Variable	Required	Description
WALWARDEN_TOKEN	Yes	Short-lived restore token issued by the dashboard. Set by the one-liner.
WALWARDEN_API_URL	No	API base URL. Defaults to https://app.walwarden.com. Override for staging or self-hosted.
PGPASSWORD	No	Target database password. If provided, the CLI injects it into the DSN. Ignored if the DSN already includes a password.

Full example

# new_database restore using the dashboard one-liner
WALWARDEN_TOKEN=eyJhbGci... \
  npx --yes walwarden-cli restore \
  --manifest a3f1c2d4e5b6789012345678901234567890123456789012345678901234abcd \
  --target 'postgresql://restore-user@neon.tech:5432/postgres' \
  --mode new_database

# in_place restore with PGPASSWORD and JSON output
export PGPASSWORD='s3cr3t'
WALWARDEN_TOKEN=eyJhbGci... \
  walwarden restore \
  --manifest a3f1c2d4e5b6789012345678901234567890123456789012345678901234abcd \
  --target 'postgresql://restore-user@host:5432/mydb' \
  --mode in_place \
  --confirm-destructive \
  --json

Exit codes

See Exit codes.