# 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)