OptiTech CLI command: snapshots

The snapshots command creates, lists, updates, deletes, and restores snapshots of your OptiTech branches, and manages the automatic backup schedule of a branch. A snapshot captures the state of a branch at a point in time, so you can restore it later. For background on the feature, plans, and limits, see Backup and restore.

If --project-id is omitted, the CLI resolves it from your context file, auto-selects when your account has only one project, and prompts otherwise.

Subcommands: create, delete, finalize, get, list, restore, schedule, update

optitech snapshots create

Creates a snapshot from a branch. By default, it snapshots the head of the branch from your context or the project's default branch. Use --lsn or --timestamp to capture an earlier point within the branch's restore window; the two options are mutually exclusive.

optitech snapshots create [options]

Option	Description	Type	Default	Required
`--branch`, `-b`	Branch id or name to snapshot. Defaults to the branch in your context, or the project's default branch.	string	—	No
`--expires-at`	When the snapshot is automatically deleted (RFC 3339, e.g. 2025-12-31T23:59:59Z). Omit to keep it indefinitely.	string	—	No
`--lsn`	Take the snapshot at this LSN (e.g. 0/1F3C8A0). Must fall within the branch's restore window. Mutually exclusive with --timestamp.	string	—	No
`--name`	A name for the snapshot	string	—	No
`--timestamp`	Take the snapshot at this point in time (RFC 3339, e.g. 2025-01-01T00:00:00Z). Must fall within the branch's restore window. Mutually exclusive with --lsn.	string	—	No
`--project-id`	Project ID	string	—	No

Snapshot the head of a branch with a name:

optitech snapshots create --branch main --name pre-migration

Snapshot a branch at a specific LSN and set an expiration:

optitech snapshots create --branch main --lsn 0/1F3C8A0 --expires-at 2025-12-31T23:59:59Z

Snapshot a branch at a point in time:

optitech snapshots create --branch main --timestamp 2025-01-01T00:00:00Z

Timestamps and expiration times use RFC 3339 format. Omit --expires-at to keep the snapshot indefinitely.

optitech snapshots list

Lists the snapshots in a project.

optitech snapshots list [options]

Option	Description	Type	Default	Required
`--project-id`	Project ID	string	—	No

optitech snapshots list

optitech snapshots get

Retrieves a snapshot by ID or name.

optitech snapshots get <id> [options]

Option	Description	Type	Default	Required
`--project-id`	Project ID	string	—	No

optitech snapshots get snap-1234

optitech snapshots update

Renames a snapshot or changes its expiration. Use --clear-expiration to keep a snapshot indefinitely; it's mutually exclusive with --expires-at.

optitech snapshots update <id> [options]

Option	Description	Type	Default	Required
`--clear-expiration`	Clear the expiration so the snapshot is kept indefinitely.	boolean	—	No
`--expires-at`	Set when the snapshot expires (RFC 3339). Mutually exclusive with --clear-expiration.	string	—	No
`--name`	Rename the snapshot	string	—	No
`--project-id`	Project ID	string	—	No

Rename a snapshot:

optitech snapshots update snap-1234 --name pre-migration

Clear a snapshot's expiration:

optitech snapshots update snap-1234 --clear-expiration

optitech snapshots delete

Deletes a snapshot by ID or name.

optitech snapshots delete <id> [options]

Option	Description	Type	Default	Required
`--project-id`	Project ID	string	—	No

optitech snapshots delete snap-1234

optitech snapshots restore

Restores a snapshot into a branch. By default, the restore is left un-finalized so you can inspect the restored branch first, then swap it in with snapshots finalize. Pass --finalize to move computes onto the restored branch and swap it in for the target immediately.

optitech snapshots restore <id> [options]

Option	Description	Type	Default	Required
`--finalize`	Finalize the restore immediately: move computes onto the restored branch and swap it in for the target. Without this, the restore is left un-finalized so you can inspect it first, then run `snapshots finalize <branch>`.	boolean	`false`	No
`--name`	Name for the newly restored branch. Auto-generated when omitted.	string	—	No
`--target-branch`	Branch id or name to restore the snapshot onto. Defaults to the snapshot's source branch. Recommended when you intend to finalize (replace an existing branch).	string	—	No
`--project-id`	Project ID	string	—	No

Restore a snapshot to a new branch:

optitech snapshots restore snap-1234 --name recovered

Restore onto an existing branch un-finalized to preview, then finalize:

optitech snapshots restore snap-1234 --target-branch main

Restore onto a branch and swap it in immediately:

optitech snapshots restore snap-1234 --target-branch main --finalize

optitech snapshots finalize

Finalizes a previewed snapshot restore, swapping the restored branch in for the target. Use this after running snapshots restore without --finalize. The argument is the ID of the restored branch that snapshots restore created, not the target branch. The restore command prints the exact finalize command to run.

optitech snapshots finalize <branch> [options]

Option	Description	Type	Default	Required
`--name`	Name to give the replaced (old) branch. Auto-generated when omitted.	string	—	No
`--project-id`	Project ID	string	—	No

optitech snapshots finalize br-summer-water-au2msxjn

The replaced (old) branch is kept under an auto-generated name unless you set one with --name.

Snapshot schedule

The snapshots schedule subcommands get and set the automatic snapshot (backup) schedule of a branch.

Subcommands: get, set

optitech snapshots schedule get

Gets a branch's automatic snapshot schedule.

optitech snapshots schedule get [options]

Option	Description	Type	Default	Required
`--branch`, `-b`	Branch id or name. Defaults to the branch in your context, or the project's default branch.	string	—	No
`--project-id`	Project ID	string	—	No

optitech snapshots schedule get --branch main

optitech snapshots schedule set

Sets a branch's automatic snapshot schedule. Build a single-entry schedule with --frequency and its companion flags, or pass a full JSON schedule with --schedule for a multi-entry schedule (this overrides the single-entry flags).

Pick one --frequency; that choice determines which of --day and --hour you must also set. The supported frequencies are:

`--frequency`	Also required	`--day` range
`daily`	`--hour` (0-23)	not used
`weekly`	`--day`, `--hour`	1-7 (Monday-Sunday)
`monthly`	`--day`, `--hour`	1-31

Use --retention with any frequency to set how long each snapshot is kept.

optitech snapshots schedule set [options]

Option	Description	Type	Default	Required
`--branch`, `-b`	Branch id or name. Defaults to the branch in your context, or the project's default branch.	string	—	No
`--day`	Day of the week/month (1-31) to take the snapshot (used with --frequency).	number	—	No
`--frequency`	How often to take snapshots. Combine with --hour, --day, and --retention to build a single-entry schedule. Possible values: `daily`, `weekly`, `monthly`	string	—	No
`--hour`	Hour of the day (0-23) to take the snapshot (used with --frequency).	number	—	No
`--month`	Month of the year (1-12) to take the snapshot (used with --frequency).	number	—	No
`--retention`	How long to keep each snapshot, in seconds (min 3600). Omit to keep indefinitely.	number	—	No
`--schedule`	Full schedule as JSON, for multi-entry schedules, e.g. '[{"frequency":"daily","hour":3,"retention_seconds":604800}]'. Overrides the single-entry flags.	string	—	No
`--project-id`	Project ID	string	—	No

Set a daily 03:00 snapshot kept for 7 days (604800 seconds):

optitech snapshots schedule set --branch main --frequency daily --hour 3 --retention 604800

Set a weekly snapshot on Mondays at 04:00:

optitech snapshots schedule set --branch main --frequency weekly --day 1 --hour 4

Set a multi-entry schedule with JSON:

optitech snapshots schedule set --branch main --schedule '[{"frequency":"daily","hour":3},{"frequency":"weekly","day":1,"hour":4}]'

Retention is set in seconds (minimum 3600). Omit --retention to keep snapshots indefinitely.