CLI reference

Generated command reference for the SDK-backed alpha CLI plus the legacy restore-token command.

The walwarden binary has two separate command surfaces:

SDK-backed public commands for API-key automation, CI, and agents.
Legacy restore-token execution using npx --yes walwarden-cli restore --manifest ... from a dashboard one-liner.

This generated reference covers the public alpha commands from packages/cli/src/publicCommandMetadata.ts.

Install

npm install -g walwarden-cli
# installed binary: walwarden
# or run without installing
npx --yes walwarden-cli --json database list

Configuration precedence: flags, environment, legacy WALWARDEN_API_URL alias, then profile config at ~/.config/walwarden/config.json.

Global Flags

Flag	Description
`--json`	Emit structured JSON output.
`--profile <name>`	Select a profile from the Walwarden config file. Defaults to default.
`--config <file>`	Read profile configuration from a JSON config file.
`--api-url <url>`	Override WALWARDEN_BASE_URL for this invocation.
`--api-key <key>`	Override WALWARDEN_API_KEY for this invocation.
`--timeout-ms <ms>`	Set the SDK request timeout in milliseconds.

Public Commands

Command	Description	Scopes
`profile validate`	Validates local config/API-key wiring through the public profile endpoint.	none
`database list [--limit <1..100>] [--cursor <opaque>]`	Lists protected databases visible to the API key.	`databases:read`
`database get <databaseId>`	Reads one protected database.	`databases:read`
`destination list [--limit <1..100>] [--cursor <opaque>]`	Lists backup destinations visible to the API key without returning credential material.	`destinations:read`
`destination get <destinationId>`	Reads one backup destination summary without returning credential material.	`destinations:read`
`backup list --database <databaseId> [--limit <1..100>] [--cursor <opaque>]`	Lists backup jobs for a database.	`databases:read`
`backup trigger --database <databaseId> [--wait]`	Triggers an ad hoc backup and optionally polls backup status.	`backups:trigger`
`backup status <backupJobId>`	Reads backup job status and artifact metadata when available.	`databases:read`
`evidence list [--database <databaseId>] [--limit <1..100>] [--cursor <opaque>]`	Lists public evidence metadata, optionally filtered to one database.	`evidence:read`
`evidence get <backupJobId>`	Reads public evidence detail for one backup job.	`evidence:read`
`restore create (--backup <backupJobId> \| --window <recoveryWindowId> --cursor <replayCursor>) --target <dsn> --mode <new_database or in_place> [--created-database <name>] [--confirm-destructive]`	Creates a restore execution session from a completed backup or validated recovery-window cursor. Raw target DSN remains CLI-local. For new_database restores, pass a maintenance database DSN such as postgres; add --created-database to avoid source-name collisions on providers like Neon.	`restores:write`
`restore execute (--backup <backupJobId> \| --window <recoveryWindowId> --cursor <replayCursor>) --target <dsn> --mode <new_database or in_place> [--created-database <name>] [--confirm-destructive]`	Creates a restore session from a completed backup or validated recovery-window cursor, executes it locally, and reports terminal status. Raw target DSN and execution coordinates remain CLI-local. For new_database restores, pass a maintenance database DSN and optionally --created-database for the fresh database to create.	`restores:write`, `restores:read`
`restore status <restoreJobId>`	Reads restore job status.	`restores:read`
`capabilities list`	Lists the bundled Walwarden capability contract with registry compatibility and per-capability CLI support. Runs locally; no API call.	none
`capabilities describe <capabilityId>`	Describes one capability entry (auth, risk, human gate, schemas, structured errors) from the bundled contract. Runs locally; no API call.	none
`verify-environment`	Runs a local pre-flight over contract compatibility, Node runtime, and non-secret connection config. Never inspects or persists target-DB write credentials.	none
`explain-error --from-json <file>`	Explains a structured API/CLI error object from a file or stdin.	none

`profile validate`

Validates local config/API-key wiring through the public profile endpoint.

npx --yes walwarden-cli --json profile validate

Kind: profile.validate

Required flags: none

Optional flags: none

SDK methods: checkCompatibility, getProfile

`database list [--limit <1..100>] [--cursor <opaque>]`

Lists protected databases visible to the API key.

npx --yes walwarden-cli --json database list --limit 25

Kind: database.list

Required flags: none

Optional flags: --limit <1..100>, --cursor <opaque>

SDK methods: listDatabases

`database get <databaseId>`

Reads one protected database.

npx --yes walwarden-cli --json database get <databaseId>

Kind: database.get

Required flags: none

Optional flags: none

SDK methods: getDatabase

`destination list [--limit <1..100>] [--cursor <opaque>]`

Lists backup destinations visible to the API key without returning credential material.

npx --yes walwarden-cli --json destination list --limit 25

Kind: destination.list

Required flags: none

Optional flags: --limit <1..100>, --cursor <opaque>

SDK methods: listDestinations

`destination get <destinationId>`

Reads one backup destination summary without returning credential material.

npx --yes walwarden-cli --json destination get <destinationId>

Kind: destination.get

Required flags: none

Optional flags: none

SDK methods: getDestination

`backup list --database <databaseId> [--limit <1..100>] [--cursor <opaque>]`

Lists backup jobs for a database.

npx --yes walwarden-cli --json backup list --database <databaseId> --limit 25

Kind: backup.list

Required flags: --database <databaseId>

Optional flags: --limit <1..100>, --cursor <opaque>

SDK methods: listDatabaseBackups

`backup trigger --database <databaseId> [--wait]`

Triggers an ad hoc backup and optionally polls backup status.

npx --yes walwarden-cli --json backup trigger --database <databaseId> --wait

Kind: backup.trigger

Required flags: --database <databaseId>

Optional flags: --wait

SDK methods: triggerBackup, pollBackup

`backup status <backupJobId>`

Reads backup job status and artifact metadata when available.

npx --yes walwarden-cli --json backup status <backupJobId>

Kind: backup.status

Required flags: none

Optional flags: none

SDK methods: getBackup

`evidence list [--database <databaseId>] [--limit <1..100>] [--cursor <opaque>]`

Lists public evidence metadata, optionally filtered to one database.

npx --yes walwarden-cli --json evidence list --database <databaseId>

Kind: evidence.list

Required flags: none

Optional flags: --database <databaseId>, --limit <1..100>, --cursor <opaque>

SDK methods: listEvidence

`evidence get <backupJobId>`

Reads public evidence detail for one backup job.

npx --yes walwarden-cli --json evidence get <backupJobId>

Kind: evidence.get

Required flags: none

Optional flags: none

SDK methods: getEvidence

`restore create (--backup <backupJobId> | --window <recoveryWindowId> --cursor <replayCursor>) --target <dsn> --mode <new_database or in_place> [--created-database <name>] [--confirm-destructive]`

Creates a restore execution session from a completed backup or validated recovery-window cursor. Raw target DSN remains CLI-local. For new_database restores, pass a maintenance database DSN such as postgres; add --created-database to avoid source-name collisions on providers like Neon.

npx --yes walwarden-cli --json restore create --backup <backupJobId> --target "$TARGET_MAINTENANCE_DATABASE_URL" --mode new_database --created-database restored_db_20260608

npx --yes walwarden-cli --json restore create --window <recoveryWindowId> --cursor <replayCursor> --target "$TARGET_MAINTENANCE_DATABASE_URL" --mode new_database --created-database restored_db_20260608

Kind: restore.create

Required flags: --backup <backupJobId> or --window <recoveryWindowId>, --target <dsn>, --mode <new_database or in_place>

Optional flags: --cursor <replayCursor> (required with --window), --created-database <name>, --confirm-destructive

SDK methods: createRestore

`restore execute (--backup <backupJobId> | --window <recoveryWindowId> --cursor <replayCursor>) --target <dsn> --mode <new_database or in_place> [--created-database <name>] [--confirm-destructive]`

Creates a restore session from a completed backup or validated recovery-window cursor, executes it locally, and reports terminal status. Raw target DSN and execution coordinates remain CLI-local. For new_database restores, pass a maintenance database DSN and optionally --created-database for the fresh database to create.

npx --yes walwarden-cli --json restore execute --backup <backupJobId> --target "$TARGET_MAINTENANCE_DATABASE_URL" --mode new_database --created-database restored_db_20260608

npx --yes walwarden-cli --json restore execute --window <recoveryWindowId> --cursor <replayCursor> --target "$TARGET_MAINTENANCE_DATABASE_URL" --mode new_database --created-database restored_db_20260608

Kind: restore.execute

Required flags: --backup <backupJobId> or --window <recoveryWindowId>, --target <dsn>, --mode <new_database or in_place>

Optional flags: --cursor <replayCursor> (required with --window), --created-database <name>, --confirm-destructive

SDK methods: createRestore, getRestore

`restore status <restoreJobId>`

Reads restore job status.

npx --yes walwarden-cli --json restore status <restoreJobId>

Kind: restore.status

Required flags: none

Optional flags: none

SDK methods: getRestore

`capabilities list`

Lists the bundled Walwarden capability contract with registry compatibility and per-capability CLI support. Runs locally; no API call.

npx --yes walwarden-cli --json capabilities list

Kind: capabilities.list

Required flags: none

Optional flags: none

SDK methods: none

`capabilities describe <capabilityId>`

Describes one capability entry (auth, risk, human gate, schemas, structured errors) from the bundled contract. Runs locally; no API call.

npx --yes walwarden-cli --json capabilities describe backup.trigger

Kind: capabilities.describe

Required flags: none

Optional flags: none

SDK methods: none

`verify-environment`

Runs a local pre-flight over contract compatibility, Node runtime, and non-secret connection config. Never inspects or persists target-DB write credentials.

npx --yes walwarden-cli --json verify-environment

Kind: verify-environment

Required flags: none

Optional flags: none

SDK methods: none

`explain-error --from-json <file>`

Explains a structured API/CLI error object from a file or stdin.

npx --yes walwarden-cli --json explain-error --from-json ./error.json

Kind: explain-error

Required flags: none

Optional flags: --from-json <file>

SDK methods: none

Explicit Public CLI Non-Goals

The alpha public CLI does not include destination write/verify commands, login, whoami, PITR, or offline evidence bundle verification.

Legacy Restore-Token Command

The dashboard-generated restore command remains available for customer-side restore execution. The target DSN stays on the customer machine.

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

For --mode in_place, pass --confirm-destructive. See restore docs for the legacy restore-token walkthrough.

On this page