# 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)