3ab1320f42
A friendly, task-oriented guide for non-technical users: README index, getting-started, concepts, items, passwords-and-generators, totp, attachments-and-documents, organizing, sync-and-backup, the-browser-extension, recovery, faq. Every command/flag derived from the actual CLI surface (`relicario --help` tree) and real extension behavior — no invented flags. Org item-type parity is covered high-level pending the v0.8.1 B/C merge (two TODO markers left for the rebase).
4.7 KiB
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 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