---
title: The relic command | Relic Help
description: A small command that reads and writes the same vault the app does, on this computer, with no account and no network. The lines to type first.
canonical: https://relic.space/help/cli
source: https://relic.space/llms.txt
---
Agents and the CLI

# The relic command

A small command that reads and writes the same vault the app does, on this computer, with no account and no network. The lines to type first.

Updated 10 September 2026 · Windows, Mac, Linux

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](#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](#where-it-lives)

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](#first-commands)

1. 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
2. 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
3. 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
4. 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
5. 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](#output)

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](#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 status`is 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](#deleting)

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_delete`in 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](#what-happens)

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](https://relic.space/features#ai) 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](#full-reference)

Every command, every option and the exact shape of the JSON is in the reference at [relic.space/docs/cli.md](https://relic.space/docs/cli.md). The [developer docs](https://relic.space/developers) 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](https://relic.space/help/ai-agents).

Related

[Use Relic with an AI agentAgents and the CLI](https://relic.space/help/ai-agents)[The Relic windowGet started](https://relic.space/help/the-popup)[Keyboard shortcutsShortcuts](https://relic.space/help/shortcuts)[Settings: GeneralSettings reference](https://relic.space/help/settings-general)