# backup and restore

```sh
scribase backup list    <org> <project> <env> [--limit N]
scribase backup create  <org> <project> <env> <idempotency-key>
scribase backup get     <org> <project> <env> <backup>
scribase backup verify  <org> <project> <env> <backup> <idempotency-key>
scribase restore start  <org> <project> <backup> <target-env> <idempotency-key> [--source <env>]
scribase restore list   <org> <project> <env>
scribase restore get    <org> <project> <env> <restore>
```

Each command is one authenticated request to the `/v1` API. Backups and
restores are long-running jobs: `create`, `verify` and `restore start` return
the record at once, and `backup get` / `restore get` poll it until it finishes.
Scheduled backups and retention also run on their own inside the control API.

## Take a backup

```sh
scribase backup create acme my-app production nightly-2026-09-25
scribase backup list acme my-app production --limit 20
scribase backup get acme my-app production <backup-id>
```

`--limit` takes 1 to 200.

## Verify a backup

```sh
scribase backup verify acme my-app production <backup-id> verify-2026-09-25
```

Verify restores the backup into a throwaway database, counts its relations and
the tables protected by row-level security, then drops it. It never touches the
environment's own database. The control plane needs a scratch Postgres for this
(`SCRIBASE_RESTORE_VERIFY_DATABASE_URL`; the single-box layout bundles one).
Without it, verify answers `503 verification_not_configured`.

## Restore

```sh
# Restore a production backup into production.
scribase restore start acme my-app <backup-id> production restore-1

# Restore a production backup into a staging environment.
scribase restore start acme my-app <backup-id> staging restore-2 --source production

scribase restore list acme my-app production
scribase restore get acme my-app production <restore-id>
```

`--source` names the environment the backup was taken from. It defaults to the
target environment.

On the [single-box layout](https://docs.scribase.com/docs/single-box.md), a restore into an environment
that already has data lands in a new `restore_<id>` database next to the
current one. The environment keeps serving its current database until you
switch it to the restored one in the console (restore history, **Switch**).
Switching back works the same way.

## Extend a preview

```sh
scribase env renew <org> <project> <env> <ttl-hours> <idempotency-key>
```

Sets a preview environment's expiry to `ttl-hours` from now, so it is not swept.

See also the API reference: [Backups & restore](https://docs.scribase.com/docs/api/backups.md).