3ab1320f42
A friendly, task-oriented guide for non-technical users: README index, getting-started, concepts, items, passwords-and-generators, totp, attachments-and-documents, organizing, sync-and-backup, the-browser-extension, recovery, faq. Every command/flag derived from the actual CLI surface (`relicario --help` tree) and real extension behavior — no invented flags. Org item-type parity is covered high-level pending the v0.8.1 B/C merge (two TODO markers left for the rebase).
155 lines
4.3 KiB
Markdown
155 lines
4.3 KiB
Markdown
# 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)
|