# 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 --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 ` 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 ``` `` 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 ``` 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 [--out ] ``` - `` — item ID or title substring - `` — attachment ID from `relicario attachments` - `--out ` — 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 ``` Example: ``` relicario detach "GitHub" a3f8c1d2e5b6 ``` This is different from `relicario purge `, 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 ` | Maximum size of a single attachment | | `--per-item-max-count ` | Maximum number of attachments on one item | | `--per-vault-soft-cap-bytes ` | Vault-wide soft cap (warning threshold) | | `--per-vault-hard-cap-bytes ` | 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 --title …` | | Attach a file to an existing item | `relicario attach ` | | List an item's attachments (get AIDs) | `relicario attachments ` | | Extract an attachment to disk | `relicario extract [--out ]` | | Remove one attachment (keep the item) | `relicario detach ` | | Remove the whole item + all attachments | `relicario purge ` | | View attachment size limits | `relicario settings show` | | Change attachment size limits | `relicario settings attachment-cap [OPTIONS]` | --- **Next:** [Organizing your vault](organizing.md)