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).
178 lines
6.7 KiB
Markdown
178 lines
6.7 KiB
Markdown
# Getting started with Relicario
|
|
|
|
This page walks you through building Relicario from source, creating your first vault, and adding your first login — from zero to password manager in about ten minutes.
|
|
|
|
---
|
|
|
|
## 1. Build and install the CLI
|
|
|
|
Relicario is currently distributed as source code, so you will need the Rust toolchain (`cargo`) installed. If you do not have it yet, visit [rustup.rs](https://rustup.rs) and follow the instructions there.
|
|
|
|
Clone the Relicario repository, then build the CLI:
|
|
|
|
```bash
|
|
# Fast debug build (good for trying things out)
|
|
cargo build -p relicario-cli
|
|
|
|
# Optimized release build (recommended for everyday use)
|
|
cargo build --release -p relicario-cli
|
|
```
|
|
|
|
The debug binary ends up at `target/debug/relicario`. The release binary ends up at `target/release/relicario`. You can copy either one to somewhere on your `$PATH`, for example:
|
|
|
|
```bash
|
|
cp target/release/relicario ~/.local/bin/relicario
|
|
```
|
|
|
|
Or run it in place using `cargo run`:
|
|
|
|
```bash
|
|
cargo run -p relicario-cli -- --help
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Create your first vault
|
|
|
|
A Relicario vault is a regular git repository, and `relicario init` sets that up for you. Create an empty directory, move into it, and initialize the vault inside.
|
|
|
|
```bash
|
|
mkdir ~/my-vault
|
|
cd ~/my-vault
|
|
relicario init --image /path/to/your-photo.jpg
|
|
```
|
|
|
|
Replace `/path/to/your-photo.jpg` with any JPEG you own — a snapshot from your phone, a landscape photo, anything works.
|
|
|
|
### What happens during `init`
|
|
|
|
1. Relicario asks you to **choose a passphrase**, then to type it again to confirm. Pick something memorable but not trivial — Relicario rejects very weak passphrases. Your typing is not echoed to the terminal.
|
|
2. It generates a random 256-bit secret and hides it inside the pixels of your photo, writing a new file called `reference.jpg` (in the vault directory by default).
|
|
3. It sets up the git repository, creates the encrypted vault files, adds a `.gitignore`, and makes the first commit.
|
|
4. It prints something like:
|
|
|
|
```
|
|
Vault initialized at /home/you/my-vault
|
|
Reference image: reference.jpg
|
|
→ back this file up somewhere safe; it is your second factor.
|
|
```
|
|
|
|
### The two factors — and why the reference image matters
|
|
|
|
Relicario uses **two factors** to unlock your vault:
|
|
|
|
- **Factor 1 — your passphrase:** something you memorize and type at the terminal.
|
|
- **Factor 2 — your reference image:** the `reference.jpg` file produced during `init`. It carries the hidden secret that, combined with your passphrase, derives the decryption key. Neither factor alone can unlock anything.
|
|
|
|
**Critical:** `reference.jpg` is intentionally **not** committed to your git repository (it is listed in `.gitignore`). This means if you push your vault to a git remote, the second factor does NOT go with it — which is exactly the point.
|
|
|
|
> **Back this file up separately.** Copy `reference.jpg` to a USB drive, encrypted cloud storage, or a printed recovery QR (see [Recovery](recovery.md)). If you lose your reference image AND your recovery QR, your vault data is gone for good — there is no backdoor.
|
|
|
|
For the technically curious, the cryptographic details are in [../docs/CRYPTO.md](../docs/CRYPTO.md) and the threat model is in [../docs/SECURITY.md](../docs/SECURITY.md).
|
|
|
|
---
|
|
|
|
## 3. Your first unlock
|
|
|
|
Every Relicario command that reads or writes vault data unlocks the vault first, then drops the key when it exits. There is no persistent "unlocked session" in the CLI.
|
|
|
|
Run commands from **inside your vault directory** (the one containing `.relicario/`) or any subdirectory of it — Relicario walks up to find the vault, just like git does.
|
|
|
|
When you run a vault command, Relicario:
|
|
|
|
1. Looks for your reference image via the `RELICARIO_IMAGE` environment variable; if not set, checks for `reference.jpg` in the vault directory; if neither is found, prompts `Reference image path:`.
|
|
2. Prompts `Passphrase:` (input is hidden).
|
|
|
|
If both are correct, the vault opens. If either is wrong or the image has been modified, the command fails.
|
|
|
|
### Set `RELICARIO_IMAGE` to avoid the prompt
|
|
|
|
If `reference.jpg` is not in the vault directory (for example, you keep it on a separate USB drive), set the environment variable so you are not prompted every time:
|
|
|
|
```bash
|
|
export RELICARIO_IMAGE=/media/usb/my-vault-reference.jpg
|
|
```
|
|
|
|
Add that line to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) to make it permanent. If `reference.jpg` lives right in the vault directory, Relicario finds it automatically and you do not need to set this variable.
|
|
|
|
---
|
|
|
|
## 4. Add your first login
|
|
|
|
```bash
|
|
relicario add login \
|
|
--title "GitHub" \
|
|
--username "yourname@example.com" \
|
|
--url "https://github.com" \
|
|
--password-prompt
|
|
```
|
|
|
|
- `--title` is the name you will use to find the item later.
|
|
- `--username` and `--url` are stored in plaintext (visible in listings).
|
|
- `--password-prompt` asks for your password at a hidden prompt. Alternatively, pass `--password <PASSWORD>` inline or `--password-stdin` to pipe it in from a script.
|
|
|
|
Any flag you leave out is asked interactively, so you can also just run:
|
|
|
|
```bash
|
|
relicario add login
|
|
```
|
|
|
|
...and answer the prompts one at a time.
|
|
|
|
After entering your vault passphrase, the item is encrypted and committed to git.
|
|
|
|
---
|
|
|
|
## 5. View and list your items
|
|
|
|
### View a specific item
|
|
|
|
```bash
|
|
relicario get GitHub
|
|
```
|
|
|
|
Pass an item's title (or any case-insensitive substring of it) as the query. Secrets like the password are **masked** by default — they show as `********`.
|
|
|
|
To reveal the actual values:
|
|
|
|
```bash
|
|
relicario get GitHub --show
|
|
```
|
|
|
|
To copy the primary secret (the password for a login) to your clipboard:
|
|
|
|
```bash
|
|
relicario get GitHub --copy
|
|
```
|
|
|
|
The clipboard is automatically cleared after **30 seconds**.
|
|
|
|
### List all items
|
|
|
|
```bash
|
|
relicario list
|
|
```
|
|
|
|
Filter by type, group, or tag:
|
|
|
|
```bash
|
|
relicario list --type login
|
|
relicario list --group Work
|
|
relicario list --tag important
|
|
```
|
|
|
|
---
|
|
|
|
## 6. What to do next
|
|
|
|
You now have a working vault with your first login. A few things worth doing right away:
|
|
|
|
- **Back up your reference image.** Copy `reference.jpg` somewhere safe before you add more data to the vault. See [Recovery](recovery.md) for the recovery QR option.
|
|
- **Push your vault to a remote.** Add a Gitea or GitHub remote and run `relicario sync` to push. Your ciphertext is safe to store on a server — the server never sees your passphrase or your reference image.
|
|
- **Learn about the item types.** Relicario can store logins, secure notes, identities, payment cards, API/SSH keys, documents, and TOTP codes. See [Items](items.md).
|
|
- **Try the browser extension.** Relicario has a Chrome/Chromium extension with autofill, live TOTP codes, and a full-featured vault tab. See [The browser extension](the-browser-extension.md).
|
|
|
|
---
|
|
|
|
**Next:** [Concepts](concepts.md)
|