> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withrelic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secret History

> View previous versions of a secret and roll back, from the CLI or the TUI.

Every time a secret is changed or deleted, Relic keeps its previous encrypted value. You can list those versions, reveal them locally, and restore any of them as the current value. Deleted secrets can be restored the same way.

History follows the same zero-knowledge model as secrets: the server stores only ciphertext, and values are decrypted on your device.

## How Versions Work

Versions are numbered per secret, starting at `v1`. A new version is created whenever the value, type, scope, or key name changes, or when the secret is deleted or rolled back. Saving a secret without changes does not create a version.

| Change type | Recorded when |
| - | - |
| `updated` | The secret was edited (single edit or bulk import) |
| `deleted` | The secret was deleted. Its last value stays restorable |
| `restored` | The secret was rolled back. The value it replaced is kept |
| `current` | The live value. Shown first in the CLI and TUI, never stored |

Each history entry records who made the change and when. The current value shows who last set it.

<Note>
  Secrets that existed before history was enabled start at `v1` and gain history with their next
  change.
</Note>

## Viewing History

### CLI

```bash theme={null}
relic history DATABASE_URL -e production
```

```
  DATABASE_URL in production

  VERSION  CHANGE   WHEN    BY                 VALUE
  v3       current  2h ago  alice@example.com  ********
  v2       updated  2h ago  bob@example.com    ********
  v1       updated  5d ago  alice@example.com  ********
```

A row's `WHEN` and `BY` describe the change that replaced that version. For `current`, they describe who set the live value.

Values are masked by default. Pass `--reveal` to decrypt them locally. Relic asks for confirmation before printing plaintext to your terminal:

```bash theme={null}
relic history DATABASE_URL -e production --reveal
```

Use `--json` for scripting. Values are only included when `--reveal` is also set:

```bash theme={null}
relic history DATABASE_URL -e production --json
relic history DATABASE_URL -e production -f api --reveal --yes --json
```

### TUI

Select a secret and press `t` to open its history. Use `j`/`k` to move between versions. Values stay masked unless secrets are shown (`v`), which requires your master password.

## Rolling Back

Rolling back makes a previous version the current value. The value it replaces is recorded as a new `restored` entry, so a rollback can itself be undone.

### CLI

```bash theme={null}
relic rollback DATABASE_URL -e production --to 2
```

Relic shows what will change and asks for confirmation. In non-interactive shells such as CI, pass `--yes` to skip the prompt.

To restore a deleted secret, look up its versions and roll back to one of them:

```bash theme={null}
relic history OLD_TOKEN -e staging
relic rollback OLD_TOKEN -e staging --to 4
```

Restoring fails if a secret with the same key already exists in that location. Rename or delete it first.

### TUI

In the history view, select a version and press `r` (or `enter`), then `y` to confirm. Restored values appear in the list right away.

<Note>
  Deleted secrets are not listed in the TUI. Use `relic rollback` to restore them.
</Note>

A rollback restores the version's value, type, and scope. The key name stays the same. Every rollback is logged as `secret.restored` in the [audit log](/configuration/audit-logs).

## Retention

Relic keeps the most recent previous versions of each secret and prunes older ones automatically when new versions are recorded. The limit depends on the **project owner's** plan:

| Plan | Versions kept per secret |
| - | - |
| Free | 10 |
| Pro | 50 |

The current value doesn't count toward the limit. `relic history` shows the active limit.

Deleting an environment or folder permanently deletes the history of the secrets inside it. Deleting your account deletes the history of your projects.

## Access

History has the same access rules as the secret itself:

* **Owners** can view history and roll back.
* **Active collaborators** can view history. Shared projects are read-only, so only the owner can roll back.
* **Revoked collaborators** lose access immediately.
* **Restricted or archived projects** block history and rollback, just like their secrets.
* **Service accounts and API keys** can't access history. History requires a signed-in user.

## Key Rotation

When the owner revokes a collaborator with key rotation, history is re-encrypted with the new project key on the owner's device, together with the current secrets. Any history the owner's client couldn't re-encrypt (for example, when rotating from an older Relic version) is deleted on the server, so no ciphertext under the old key survives rotation.

See [Security](/configuration/security#revoking-access) for details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.