Files

adlee-was-taken 59ebc28e7e docs(user): fix getting-started blockers (add git prereq + git clone command) + clarify sync remote setup

2026-06-20 22:30:07 -04:00

7.1 KiB

Raw Blame History

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 two tools installed first:

git — used to clone the source now, and to sync your vault later. If you don't have it, see git-scm.com/downloads.
The Rust toolchain (cargo) — if you don't have it yet, visit rustup.rs and follow the instructions there.

Clone the Relicario repository and move into it:

git clone ssh://git@git.adlee.work:2222/alee/relicario.git
cd relicario

Substitute the URL of whichever Relicario repository you were given access to.

Then, from the project root, build the CLI:

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

cp target/release/relicario ~/.local/bin/relicario

Or run it in place using cargo run:

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.

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`

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.
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).
It sets up the git repository, creates the encrypted vault files, adds a .gitignore, and makes the first commit.

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). 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 and the threat model is in ../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:

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:.
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:

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.

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:

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

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:

relicario get GitHub --show

To copy the primary secret (the password for a login) to your clipboard:

relicario get GitHub --copy

The clipboard is automatically cleared after 30 seconds.

List all items

relicario list

Filter by type, group, or tag:

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 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.
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.

Next: Concepts

7.1 KiB Raw Blame History