walwarden-cli

walwarden-cli

Customer-side CLI for Walwarden. Published on npm as walwarden-cli; the installed binary is walwarden.

What it does

The CLI has two isolated command surfaces:

• Public SDK-backed commands for API-key automation, CI, and agents.
• Legacy restore-token commands generated by the Walwarden dashboard for customer-side restore execution.

Usage

Public SDK-backed commands

Public commands call @walwarden/sdk and require an API base URL plus API key.

Configuration precedence:

• Flags: --api-url, --api-key, --profile, --config
• Environment: WALWARDEN_BASE_URL, WALWARDEN_API_KEY
• Legacy environment alias: WALWARDEN_API_URL
• Profile config: ~/.config/walwarden/config.json

Examples:

walwarden --json --api-url https://api.example.com --api-key wal_... profile validate
walwarden --json database list --limit 25
walwarden --json database get <databaseId>
walwarden --json backup list --database <databaseId> --limit 25
walwarden --json backup trigger --database <databaseId> --wait
walwarden --json backup status <backupJobId>
walwarden --json evidence list --database <databaseId> --limit 25
walwarden --json evidence get <backupJobId>
walwarden --json restore status <restoreJobId>
walwarden --json explain-error --from-json ./error.json

Supported alpha public commands:

Command	Description
profile validate	Validates local config/API-key wiring against the SDK compatibility profile
database list [--limit 1..100] [--cursor <opaque>]	Emits one protected-database page
database get <databaseId>	Reads one protected database
backup list --database <databaseId> [--limit 1..100] [--cursor <opaque>]	Emits one backup-job page
backup trigger --database <databaseId> [--wait]	Triggers an ad hoc backup and optionally polls status
backup status <backupJobId>	Reads backup job status
evidence list [--database <databaseId>] [--limit 1..100] [--cursor <opaque>]	Emits one evidence page
evidence get <backupJobId>	Reads public evidence detail for one backup job
restore status <restoreJobId>	Reads restore job status
explain-error --from-json <file>	Explains a structured API/CLI error object

Current non-goals for the public command surface: destination commands, restore creation/wait, login/whoami, and offline evidence bundle verification.

List commands never auto-drain. Their JSON result includes pageInfo; pass its opaque nextCursor back with --cursor to request the next page. This is an additive alpha wire change, but older CLI versions silently consume only page one and should be upgraded.

Legacy restore-token command

The Walwarden dashboard generates the exact command. General form:

WALWARDEN_TOKEN=<token> npx --yes walwarden-cli restore \
  --manifest <sha256> \
  --target postgres://user:pass@host:5432/dbname \
  --mode new_database

For an in-place restore (overwrites the target):

WALWARDEN_TOKEN=<token> npx --yes walwarden-cli restore \
  --manifest <sha256> \
  --target postgres://user:pass@host:5432/dbname \
  --mode in_place \
  --confirm-destructive

Flags

Flag	Required	Description
--manifest <sha256>	yes	SHA-256 of the backup manifest (64 hex chars)
--target <dsn>	yes	Target Postgres DSN
--mode new_database|in_place	yes	Restore into a fresh database or overwrite existing
--confirm-destructive	if in_place	Explicit acknowledgement for destructive restore
--json	no	Emit JSONL progress to stdout (auto-enabled when not a TTY)
--no-color	no	Disable ANSI color output

walwarden --version (or -v) prints the installed CLI version and exits.

Environment

Variable	Required	Description
WALWARDEN_TOKEN	yes	Short-lived restore token from the dashboard
WALWARDEN_API_URL	no	Override API base URL (default https://api.walwarden.com)
PGPASSWORD	no	If set and target DSN has no password, merged automatically

Requirements

Node.js >= 20.