relicario/user_docs/attachments-and-documents.md

Files: documents & attachments

This page covers two related ideas: storing a file as its own vault item (a Document), and attaching extra files to any existing item — like pinning a recovery-codes PDF to a login.

---

Documents vs. attachments — what's the difference?

	What it is	How you create it
Document item	A file that is the item — a passport scan, a signed contract, a certificate.	relicario add document
Attachment	A file pinned to an existing item — a recovery-codes PDF on a login, a photo on an identity.	relicario attach

Both are encrypted the same way. The git server only ever sees ciphertext — your file bytes never leave your device in plaintext.

---

Storing a file as a Document item

A Document item holds exactly one file, encrypted, as part of the vault.

relicario add document --file <FILE> --title "My Title"

--file is required. Any fields you leave out are prompted for interactively. You can also set --group and --tags (comma-separated):

relicario add document --file passport-scan.pdf --title "Passport scan" --group identity --tags travel,official

Once stored, use relicario get <QUERY> to look it up and relicario extract (see below) to pull the file back out.

---

Attaching a file to any item

You can pin one or more files to a login, secure note, identity, card, TOTP item, or Document. The item stays intact; the file is stored alongside it as an attachment.

relicario attach <QUERY> <FILE>

<QUERY> is the item's ID or a case-insensitive title substring. Example:

relicario attach "GitHub" recovery-codes.txt

---

Listing an item's attachments

relicario attachments <QUERY>

This prints the item's attachments with their attachment IDs (AIDs) — you need an AID to extract or remove a specific file.

Example output (format may vary):

attachments on "GitHub login":
  a3f8c1d2e5b6…  recovery-codes.txt  (4.2 KB)

---

Getting a file back out — extract

relicario extract <QUERY> <AID> [--out <PATH>]

• <QUERY> — item ID or title substring
• <AID> — attachment ID from relicario attachments
• --out <PATH> — where to write the file (defaults to the original filename in the current directory if omitted)

Example:

relicario attachments "GitHub"
# note the AID, e.g. a3f8c1d2e5b6…

# Extract to a specific path:
relicario extract "GitHub" a3f8c1d2e5b6 --out ~/Downloads/recovery-codes.txt

# Or omit --out to write it under its original name in the current folder:
relicario extract "GitHub" a3f8c1d2e5b6

---

Removing one attachment — detach

detach removes a single attachment blob. The item itself stays in the vault.

relicario detach <QUERY> <AID>

Example:

relicario detach "GitHub" a3f8c1d2e5b6

This is different from relicario purge <QUERY>, which permanently deletes the entire item and all its attachments at once.

---

Size limits

Relicario enforces configurable size caps to keep your vault from ballooning. View the current limits:

relicario settings show

To change them:

relicario settings attachment-cap [OPTIONS]

Available options:

Flag	What it controls
--per-attachment-max-bytes <N>	Maximum size of a single attachment
--per-item-max-count <N>	Maximum number of attachments on one item
--per-vault-soft-cap-bytes <N>	Vault-wide soft cap (warning threshold)
--per-vault-hard-cap-bytes <N>	Vault-wide hard cap (blocks new attachments)

Pass any combination of flags; omitted flags keep their current values.

---

Quick reference

Goal	Command
Store a file as its own vault item	relicario add document --file <FILE> --title …
Attach a file to an existing item	relicario attach <QUERY> <FILE>
List an item's attachments (get AIDs)	relicario attachments <QUERY>
Extract an attachment to disk	relicario extract <QUERY> <AID> [--out <PATH>]
Remove one attachment (keep the item)	relicario detach <QUERY> <AID>
Remove the whole item + all attachments	relicario purge <QUERY>
View attachment size limits	relicario settings show
Change attachment size limits	relicario settings attachment-cap [OPTIONS]

---

Next: Organizing your vault