relicario/user_docs/items.md

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:

relicario add login --title "GitHub" --username octocat --url https://github.com --password-prompt

Example — scripted, password from stdin:

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 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:

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:

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:

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:

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:

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 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:

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 for how to view live codes.

---

Viewing items

Get a single item

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:

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

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:

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

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:

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:

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

relicario rm <QUERY>       # move to trash (reversible)
relicario restore <QUERY>  # pull it back out of the trash

Permanent purge

relicario purge <QUERY>    # delete the item AND all its attachments, forever

There is no undo for purge.

Trash management

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