# Two-factor (TOTP) codes

This page covers how to store TOTP authenticator secrets in Relicario and view live codes in the browser extension.

---

## What is a TOTP code?

When a website offers "two-factor authentication" or "authenticator app" support, it gives you a short secret — usually as a QR code — that your authenticator app uses to generate a fresh 6-digit code every 30 seconds. Those rolling codes are called TOTP codes (Time-based One-Time Passwords).

Relicario can store that secret alongside your login, so you never have to hunt for a separate app. The browser extension then shows live codes that tick down in real time, right next to your password.

---

## Where to find the TOTP secret on a website

Look for any of these on the site's security or two-factor settings page:

- A QR code labeled something like "Scan with your authenticator app"
- A text link or button that says "Can't scan the QR code?", "Enter key manually", or "Show secret key"

The manual key is a string of letters and numbers (Base32 encoded — it looks like `JBSWY3DPEHPK3PXP`). You can use either the QR image file or that manual key with Relicario.

Keep this secret safe. Anyone who has it can generate codes for your account.

---

## Two ways to add a TOTP secret

### Option 1 — Standalone TOTP item

Use this when the account is purely authenticator-based and you don't have a separate login item for it, or when you just want to keep the TOTP separate.

```
relicario add totp --title "GitHub 2FA" --issuer "GitHub" --label "you@example.com"
```

Relicario will prompt for the Base32 secret at a hidden prompt. Or pass it via flag or stdin:

```
# Pass the secret as a flag (shows in your shell history — prefer the prompt or --secret-stdin)
relicario add totp --title "GitHub 2FA" --issuer "GitHub" --label "you@example.com" \
  --secret JBSWY3DPEHPK3PXP

# Read it from stdin (keeps it out of shell history)
echo "JBSWY3DPEHPK3PXP" | relicario add totp --title "GitHub 2FA" --issuer "GitHub" \
  --label "you@example.com" --secret-stdin
```

Available flags for `relicario add totp`:

| Flag | Default | What it sets |
|---|---|---|
| `--title <TITLE>` | prompted | Item name shown in the vault |
| `--issuer <ISSUER>` | prompted | Service name (e.g. `GitHub`) |
| `--label <LABEL>` | prompted | Account identifier (e.g. your email) |
| `--secret <SECRET>` | prompted | Base32-encoded TOTP secret |
| `--secret-stdin` | — | Read secret from stdin instead of prompting |
| `--period <PERIOD>` | `30` | Code rotation interval in seconds |
| `--digits <DIGITS>` | `6` | Code length |
| `--algorithm <ALGORITHM>` | `sha1` | Hash algorithm |
| `--group <GROUP>` | — | Folder-like label |
| `--tags <TAGS>` | — | Comma-separated tags |

Most sites use the defaults (30 seconds, 6 digits, SHA-1). Only change these if the site's setup instructions specifically say otherwise.

### Option 2 — Attach TOTP to an existing Login item

If you already have (or are creating) a login item for the site, you can attach the TOTP secret directly to it using a QR image file.

**At creation time:**

```
relicario add login --title "GitHub" --username "you@example.com" \
  --totp-qr /path/to/github-totp-qr.png
```

**On an existing login:**

```
relicario edit "GitHub" --totp-qr /path/to/github-totp-qr.png
```

The `--totp-qr <PATH>` flag decodes the `otpauth://` QR image and stores the TOTP secret on the login item. No manual typing of the secret required.

---

## Viewing live codes

**In the browser extension:** open the popup and find your TOTP or login item. The extension shows the current 6-digit code with a countdown timer. The code refreshes automatically every 30 seconds. See [The browser extension](the-browser-extension.md) for how to install and use the extension.

**From the CLI:** the CLI stores the secret but does not display live rotating codes. Run `relicario get "GitHub"` to see the item (the TOTP secret is masked by default; add `--show` to reveal the stored secret).

---

## Changing or rotating a TOTP secret

If a site asks you to reset your authenticator (or you're migrating to a new device), run:

```
relicario edit "GitHub"
```

Relicario prompts you for each field. Press Enter to keep the current value; type (or paste) the new secret when you reach the TOTP secret field. To set it from a new QR image instead:

```
relicario edit "GitHub" --totp-qr /path/to/new-qr.png
```

The old secret is automatically captured in field history before it's overwritten. To review previous secrets:

```
relicario history "GitHub" --field totp_secret
```

Add `--show` to reveal the masked values:

```
relicario history "GitHub" --field totp_secret --show
```

---

**Next:** [Attachments & documents](attachments-and-documents.md)