Environment Snapshots
Snapshots capture the exact state of all secrets in an environment at a point in time. Use them for safe deployments, disaster recovery, or auditing.
When to Use Snapshots
| Scenario | Why |
|---|---|
| Before a deployment | Roll back all secrets if something goes wrong |
| Before bulk changes | Safety net when updating many secrets at once |
| Compliance audits | Prove what values were live at a specific time |
| Environment cloning | Capture state before modifying a copied environment |
Creating a Snapshot
CLI
envshed snapshot create --name "Before v2.1 deploy"
Options:
| Flag | Description |
|---|---|
-n, --name <name> | Optional human-friendly name |
-d, --desc <description> | Optional description |
-o, --org <slug> | Organization slug |
-p, --project <slug> | Project slug |
-e, --env <slug> | Environment slug |
API
curl -X POST https://app.envshed.com/api/v1/snapshots/my-org/my-project/production \
-H "Authorization: Bearer $ENVSHED_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Before v2.1 deploy"}'
Listing Snapshots
CLI
envshed snapshot list
API
curl https://app.envshed.com/api/v1/snapshots/my-org/my-project/production \
-H "Authorization: Bearer $ENVSHED_TOKEN"
Response:
{
"snapshots": [
{
"id": "uuid-1",
"name": "Before v2.1 deploy",
"description": null,
"createdBy": "user-uuid",
"createdAt": "2026-02-19T11:00:00Z"
}
]
}
Restoring from a Snapshot
Restoring puts back the keys that changed since the snapshot was taken, and only those:
- A key whose value differs from the snapshot goes back to the snapshot value and gets a new version entry with change type
rolled_back. - A key whose disabled state differs gets its snapshot state back (no new version).
- A key that is the same as in the snapshot is not touched: no new version, no webhook.
- A key added after the snapshot stays as it is.
- A key deleted after the snapshot is not brought back (restore it from Trash).
- A linked key is written on its link source, so the other projects that share it change too.
Dashboard
On the project page, pick the environment in the environment switcher, open More and pick Snapshots. Then pick Compare on a snapshot. The comparison lists what a restore would do, without showing any value: the keys that go back (with who changed them last and when), the keys that are not touched (added or deleted since) and how many are the same. Restore N keys opens a confirmation with the real numbers and the linked keys, and by default takes a snapshot of the current state first, so the restore can be undone in one step by restoring that snapshot.
Anyone with access to the environment can take a snapshot and compare. Editors and admins can restore.
Deleting a Snapshot
In the dashboard, open the menu next to a snapshot and pick Delete snapshot. Deleting removes the saved point only: no secret changes, and every key keeps its current value. A deleted snapshot can no longer be compared or restored. Editors and admins can delete snapshots, and each delete is recorded in the audit log (snapshot.delete).
CLI
envshed snapshot restore <snapshot-id>
API
curl -X POST https://app.envshed.com/api/v1/snapshots/my-org/my-project/production/restore \
-H "Authorization: Bearer $ENVSHED_TOKEN" \
-H "Content-Type: application/json" \
-d '{"snapshotId": "uuid-1"}'
How Snapshots Work Internally
A snapshot stores a JSON mapping of each secret key to its version record ID (and its disabled state) at the time of creation. When restoring, the system:
- Looks up each version record by ID and compares it with the current value
- Skips every key that is the same as now
- Updates each changed secret with that version's value and creates a new version record (type:
rolled_back) - Records the restore in the audit log; the API response's
restoredCountis the number of keys that changed
This means:
- Snapshots reference specific version records, not raw values
- Restoring is non-destructive: it creates new versions rather than rewriting history
- If a secret was deleted after the snapshot, it will be skipped during restore