The desktop app comes with a small command called relic. It is for the terminal, and for anything you script there. It is also how an AI agent works with your vault, which is the next page.

What it is

relic reads and writes the same vault the app is using on this computer. It goes straight at the local database and the local copies of your files. It has no account, no passphrase, no network of its own, and it never talks to the cloud. Anything the app has captured is there the second it lands, and anything you add through the command shows up in the Relic window straight away.

Because it works through the app, it needs the app. If Relic is not installed on this computer, or you have not made a vault yet, every command except relic status stops with exit code 3.

Getting to it

On Windows the installer puts relic in a folder next to the app and adds that folder to your PATH, so open a new terminal and the command is there. Check with relic --version.

On a Mac and on Linux the command ships with the app but nothing puts it on your PATH for you. On a Mac it is inside the app bundle, at /Applications/Relic.app/Contents/Helpers/relic. On Linux it sits beside relic_app in the folder you extracted the tarball into. Point at it once and you are done.

terminal

# Mac: make one link
sudo ln -s /Applications/Relic.app/Contents/Helpers/relic /usr/local/bin/relic

# Linux: link the copy from the tarball folder
sudo ln -s ~/relic-linux-x64/relic /usr/local/bin/relic

If you run the Linux AppImage

An AppImage unpacks itself somewhere new every time you run it, so the copy of relic inside it is at a different path each run and a link to it goes stale. Take the tarball if you want the command.

The first commands

Check that it is there
It prints Relic app: installed and a line of local counts. If it prints Relic app: not installed (no local vault found). instead, open the desktop app and make a vault first. This is the one command that never fails, so it is the one to start with.
terminal
```
relic status
```
Search
Search works on everything the app has captured on this computer. Add --vault to search only the things you kept, and --tag to narrow to one tag.
terminal
```
relic search "boarding pass" --limit 5
```
Read one item
Every item has a uid, and search prints it. --raw gives you just the text, with none of the surrounding detail, so you can pipe it somewhere. You can type the first few characters of a uid instead of the whole thing, as long as they only match one item.
terminal
```
relic get <uid> --raw
```
Add something
This puts a new item in your vault. With no text after it, it reads whatever you pipe in. Add --title to name it, --tag as many times as you like, --vault to keep it straight away, and --file to add a picture or a document instead of text.
terminal
```
relic add "remember this" --tag idea
```
Browse and get things back out
relic list shows recent items, newest first. relic tags shows every tag and how often it is used, with your own tags separated from the ones Relic worked out. relic export writes a picture or a file out to a path you choose. relic copy puts an item back on your clipboard, ready to paste.
terminal
```
relic list --vault
relic tags
relic export <uid> ./file.png
relic copy <uid>
```

relic --help lists every command, and relic search --help and the rest list the options for one of them.

Output you can parse

By default the output is laid out for a person to read. Three flags change that, and they work on any command.

--json prints one JSON object. Searching and listing give you { count, items }, and an error becomes an object with a code and a message.
--ndjson prints one JSON object per line, which is easier to read as it arrives.
-q prints bare uids and nothing else, which is what you want at the front of a pipeline.

Anything that changes your vault also takes --dry-run, which tells you what it would have done and writes nothing.

Exit codes

These do not change, so a script can rely on them.

0 it worked.
2 the command or one of its options was wrong.
3 the desktop app is not installed here, or there is no vault yet.
4 nothing matched.
5 the vault refused the change.
6 the delete guard stopped it.

relic statusis the exception. It always finishes with 0, because a plain answer of "the app is not installed" is not a failure. Read what it prints.

Deleting is off until you allow it

Reading is always allowed. Adding and editing are allowed. Deleting is not. relic rm, relic tag-rm and relic purge refuse with exit code 6 until you say otherwise. Set RELIC_ALLOW_DELETE=1 for one session, put allow_deletein the command's own config file to make it stick, or pass --allow-delete on the line itself, which asks you to confirm unless you add --yes.

Even then it is careful. relic rm writes a copy of the item into its own local trash before it removes it from the vault, and the removal syncs to your other devices the same way it would from the app. relic purge with --hard is the one that is permanent, with no copy kept.

Every change the command makes is written to a log in its own folder, whether it came from you or from an agent. relic where prints where that folder is, along with the vault database and the local file cache.

What happens to what you add

Items added through the command are ordinary items. The running app picks them up, gives them a title and tags them in the background, reads any text inside a picture you added, and queues them for sync like anything else. See what runs on your device for what that involves.

The command does none of that itself and it never reaches the network. If the app is closed when you add something, the item is still in your local vault, and the app picks up the work and the sync the next time it runs.

The full reference

Every command, every option and the exact shape of the JSON is in the reference at relic.space/docs/cli.md. The developer docs put it next to the sync API, the encryption notes and how to run your own server. To let an AI agent use the same command, see Use Relic with an AI agent.