docs(user): add user_docs/ end-user guide (12 pages)

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).
2026-06-20 21:05:04 -04:00
parent b09e0ce036
commit 3ab1320f42
12 changed files with 1698 additions and 0 deletions
--- a/user_docs/items.md
+++ b/user_docs/items.md
@@ -0,0 +1,317 @@
+# Items: the 7 types, and how to add, view, edit, and delete them
+
+This page covers every item type Relicario supports, the exact flags for creating each one, and all the commands for viewing, updating, and removing items.
+
+---
+
+## How items work
+
+Relicario stores secrets as *typed items* — each type has a fixed set of fields that match what you'd expect for that kind of secret (a login has a username and password; a card has a number and CVV; and so on).
+
+Secret fields — passwords, card numbers, TOTP secrets, key material — are entered at a **hidden prompt** by default so they never appear on screen. If you're scripting or piping input, use the corresponding `--*-stdin` flag to read the value from standard input instead.
+
+Every item type shares three optional organizational flags:
+
+| Flag | What it does |
+|------|--------------|
+| `--title <TITLE>` | Human-readable name shown in lists |
+| `--group <GROUP>` | A single folder-like label |
+| `--tags <TAGS>` | Comma-separated labels, e.g. `--tags work,banking` |
+
+Any field you don't pass on the command line is prompted for interactively — so you can run `relicario add login` with no flags at all and fill everything in at the prompts.
+
+---
+
+## The 7 item types
+
+### Login
+
+A username/password pair, optionally with a URL and a TOTP secret baked in.
+
+```
+relicario add login [OPTIONS]
+
+  --title <TITLE>
+  --username <USERNAME>
+  --url <URL>
+  --password <PASSWORD>      set password from the command line (visible in shell history)
+  --password-prompt          prompt for password (hidden input)
+  --password-stdin           read password from stdin (one line)
+  --favorite                 mark as a favorite
+  --totp-qr <PATH>           decode an otpauth:// QR image to fill the TOTP secret
+  --group <GROUP>
+  --tags <TAGS>
+```
+
+**Example — create a login, prompting for the password:**
+
+```bash
+relicario add login --title "GitHub" --username octocat --url https://github.com --password-prompt
+```
+
+**Example — scripted, password from stdin:**
+
+```bash
+echo "hunter2" | relicario add login --title "GitHub" --username octocat --password-stdin
+```
+
+If you have a TOTP QR code saved as an image, `--totp-qr` decodes the `otpauth://` URI and links the TOTP secret to this login automatically. See [TOTP codes](totp.md) for more.
+
+---
+
+### Secure note
+
+A free-form text note. The body is entered interactively (type your note and press Ctrl-D to finish), or piped in via `--body-stdin`.
+
+```
+relicario add secure-note [OPTIONS]
+
+  --title <TITLE>
+  --body-stdin     read the note body from stdin (to EOF)
+  --group <GROUP>
+  --tags <TAGS>
+```
+
+**Example — pipe a note body from a file:**
+
+```bash
+relicario add secure-note --title "Wi-Fi passwords" --body-stdin < notes.txt
+```
+
+---
+
+### Identity
+
+Personal details: full name, email, phone, and date of birth. None of these are secret fields — they're all prompted as plain text.
+
+```
+relicario add identity [OPTIONS]
+
+  --title <TITLE>
+  --full-name <FULL_NAME>
+  --email <EMAIL>
+  --phone <PHONE>
+  --date-of-birth <DATE_OF_BIRTH>
+  --group <GROUP>
+  --tags <TAGS>
+```
+
+**Example:**
+
+```bash
+relicario add identity --title "Personal" --full-name "Alex Rivera" --email alex@example.com
+```
+
+---
+
+### Card
+
+A payment card. The card number, CVV, and PIN are secrets — they're prompted (hidden input) unless you use the `--*-stdin` flags. The holder name and expiry are plain text.
+
+```
+relicario add card [OPTIONS]
+
+  --title <TITLE>
+  --holder <HOLDER>      cardholder name (plain text)
+  --expiry <EXPIRY>      expiry date (plain text)
+  --kind <KIND>          card type [default: credit]
+  --number-stdin         read card number from stdin (one line)
+  --cvv-stdin            read CVV from stdin (one line)
+  --pin-stdin            read PIN from stdin (one line)
+  --group <GROUP>
+  --tags <TAGS>
+```
+
+**Example — create a credit card, entering number/CVV/PIN at hidden prompts:**
+
+```bash
+relicario add card --title "Chase Sapphire" --holder "Alex Rivera" --expiry "12/28"
+```
+
+Relicario will prompt you for the card number, CVV, and PIN in turn, with each hidden.
+
+---
+
+### Key
+
+A cryptographic key or any block of key material (SSH private key, API key, certificate, etc.). The material itself is a multiline secret entered interactively (Ctrl-D to finish) or via `--material-stdin`.
+
+```
+relicario add key [OPTIONS]
+
+  --title <TITLE>
+  --label <LABEL>
+  --algorithm <ALGORITHM>
+  --material-stdin         read key material from stdin (to EOF)
+  --group <GROUP>
+  --tags <TAGS>
+```
+
+**Example — store an SSH private key:**
+
+```bash
+relicario add key --title "Server deploy key" --label "id_ed25519" --algorithm ed25519 \
+  --material-stdin < ~/.ssh/id_ed25519
+```
+
+---
+
+### Document
+
+A file stored encrypted inside your vault. The `--file` flag is required; the file's bytes are encrypted and kept as an attachment on the item.
+
+```
+relicario add document --file <FILE> [OPTIONS]
+
+  --title <TITLE>
+  --file <FILE>    path to the file to encrypt and store (required)
+  --group <GROUP>
+  --tags <TAGS>
+```
+
+**Example:**
+
+```bash
+relicario add document --title "Passport scan" --file ~/Documents/passport.pdf
+```
+
+To get the file back out later: `relicario attachments "Passport scan"` to find the attachment ID, then `relicario extract "Passport scan" <AID> --out passport.pdf`. See [Attachments & Documents](attachments-and-documents.md) for more.
+
+---
+
+### TOTP
+
+A standalone TOTP authenticator entry (think: an item that generates the rotating 6-digit codes for two-factor login). If you want to attach a TOTP secret to an existing Login instead, use `--totp-qr` on `add login` or `edit`.
+
+```
+relicario add totp [OPTIONS]
+
+  --title <TITLE>
+  --issuer <ISSUER>
+  --label <LABEL>
+  --secret <SECRET>        base32-encoded TOTP secret (visible in shell history)
+  --secret-stdin           read TOTP secret from stdin (one line)
+  --period <PERIOD>        [default: 30]
+  --digits <DIGITS>        [default: 6]
+  --algorithm <ALGORITHM>  [default: sha1]
+  --group <GROUP>
+  --tags <TAGS>
+```
+
+**Example — add a TOTP entry, secret from stdin:**
+
+```bash
+echo "JBSWY3DPEHPK3PXP" | relicario add totp --title "GitHub 2FA" \
+  --issuer GitHub --label octocat --secret-stdin
+```
+
+Most services use the defaults (30-second period, 6 digits, SHA-1), so you usually only need `--issuer`, `--label`, and `--secret`/`--secret-stdin`. See [TOTP codes](totp.md) for how to view live codes.
+
+---
+
+## Viewing items
+
+### Get a single item
+
+```bash
+relicario get <QUERY>
+```
+
+`<QUERY>` is either an item ID or a **case-insensitive title substring** — so `relicario get github` finds any item with "github" in the title.
+
+By default, secret fields are **masked** (shown as `********`). Two flags change that:
+
+| Flag | Effect |
+|------|--------|
+| `--show` | Print all secret values in plaintext |
+| `--copy` | Copy the primary secret (Login password, Card number, etc.) to the clipboard — auto-clears after 30 seconds |
+
+**Examples:**
+
+```bash
+relicario get "Chase Sapphire"          # shows masked fields
+relicario get "Chase Sapphire" --show   # reveals card number and CVV
+relicario get "GitHub" --copy           # copies password; clears in 30s
+```
+
+### List all items
+
+```bash
+relicario list [OPTIONS]
+
+  --type <TYPE>    filter by item type (login, card, totp, …)
+  --group <GROUP>  filter by group label
+  --tag <TAG>      filter by tag
+  --trashed        show trashed items instead of live ones
+```
+
+**Examples:**
+
+```bash
+relicario list                   # all live items
+relicario list --type login      # logins only
+relicario list --group banking   # everything in the "banking" group
+relicario list --tag work        # everything tagged "work"
+```
+
+---
+
+## Editing items
+
+```bash
+relicario edit <QUERY>
+```
+
+Editing is interactive: Relicario shows each field's current value and lets you type a new one. **Leave a prompt blank and press Enter to keep the existing value.**
+
+For login items, you can update the linked TOTP secret from a QR code image:
+
+```bash
+relicario edit "GitHub" --totp-qr /path/to/qr.png
+```
+
+### Field history
+
+Relicario captures the previous value of secret fields whenever you change them (e.g., after a password rotation). To see that history:
+
+```bash
+relicario history <QUERY>                        # all captured changes, masked
+relicario history <QUERY> --show                 # reveal old values
+relicario history <QUERY> --field login_password # one field only
+```
+
+Field key examples: `login_password`, `card_number`, `totp_secret`.
+
+---
+
+## Deleting items
+
+Relicario has two deletion modes: **soft delete** (reversible, moves to trash) and **permanent purge**.
+
+### Soft delete and restore
+
+```bash
+relicario rm <QUERY>       # move to trash (reversible)
+relicario restore <QUERY>  # pull it back out of the trash
+```
+
+### Permanent purge
+
+```bash
+relicario purge <QUERY>    # delete the item AND all its attachments, forever
+```
+
+There is no undo for `purge`.
+
+### Trash management
+
+```bash
+relicario trash list    # see what's in the trash
+relicario trash empty   # permanently purge all items past the trash retention window
+```
+
+The retention window is configurable via `relicario settings trash-retention`.
+
+---
+
+**Next:** [Passwords & generators](passwords-and-generators.md)