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:

1. Flags: --api-url, --api-key, --profile, --config
2. Environment: WALWARDEN_BASE_URL, WALWARDEN_API_KEY
3. Legacy environment alias: WALWARDEN_API_URL
4. 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.