Quickstart: agent-assisted backup

This is the agent-assisted path: copy-paste commands a coding agent can run on your behalf to take a first backup and confirm the evidence it produced. If you would rather drive the dashboard yourself, take the CLI-first quickstart. Both paths reach the same success state — a signed manifest and an RPO figure on the dashboard.

Prerequisites

• A configured, preflight-verified destination — see BYO AWS S3.
• A connected protected database — see Connect Supabase or Connect Neon.
• An API key scoped for databases:read, destinations:read, backups:trigger, and evidence:read. Set it as WALWARDEN_API_KEY and the database id as WALWARDEN_DATABASE_ID.

Step 1: The safe CLI pattern

Give your agent this exact sequence. Every command is read-only or an explicit backup trigger; --json makes the output machine-readable.

walwarden --json profile validate
walwarden --json database list
walwarden --json destination list
walwarden --json backup trigger --database "$WALWARDEN_DATABASE_ID" --wait
walwarden --json evidence list --database "$WALWARDEN_DATABASE_ID"

The backup trigger --wait call returns when the job reaches a terminal state. The evidence the backup produced is what the agent must check next — not the trigger's exit code alone.

Step 2: Command beside the evidence it produces

The trigger command on the left produces the signed evidence on the right. The agent confirms success by reading the evidence, not by assuming a completed job is recoverable.

# command
walwarden --json evidence list \
  --database "$WALWARDEN_DATABASE_ID"

// signed output
{
  "artifact": "backup-2026-05-26T14:30:12Z",
  "state": "completed",
  "manifest": {
    "sha256": "8f3c…a1d7",
    "signature": "ed25519:…",
    "signed": true
  },
  "rpoMinutes": 12
}

Step 3: Or use the SDK

If your agent works through the TypeScript SDK instead of the CLI, the same flow is a few calls:

import { createWalwardenClient } from '@walwarden/sdk';

const walwarden = createWalwardenClient({
  baseUrl: process.env.WALWARDEN_BASE_URL!,
  apiKey: process.env.WALWARDEN_API_KEY!,
  userAgent: 'my-agent/1.0',
});

const { databases } = await walwarden.listDatabases();
// trigger a backup, then read the evidence the backup produced
// before reporting success.

See the SDK reference for the full method list and the agent integration recipes for scopes.

The evidence-before-success rule

An agent must not mark a backup, migration, or restore drill successful until it has checked the relevant command result and the evidence metadata. Backup completion alone proves only that a job completed; it is not the same as proven recoverability.

Forbidden claims

Carry these constraints into anything the agent reports. (Source of truth: agent integration recipes.)

• Do not claim the alpha public CLI can wait for or complete restore jobs through restore create; use explicit restore execute for local execution.
• Do not claim destination write, verify, attach, detach, or delete commands exist in the public CLI.
• Do not claim login or whoami commands exist.
• Do not claim PITR support.
• Do not claim offline evidence bundle verification through the public CLI/SDK alpha surface.
• Do not claim recoverability unless restore or evidence semantics support that exact claim.

Next: prove you can restore

A backup you have never restored from is a backup you have not yet proven recoverable. Run a restore drill against a non-production target.