# 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](organizing.md)
