CLI

Every reliquary command and option, with exit codes, environment variables and the project file.

Install: npm install -g @reliquary-ai/cli (Node 20 or later), or prefix every command with npx @reliquary-ai/cli. How to use it day to day: Use the CLI.

Help

The CLI's own help, generated from its source:

reliquary: a vault's environment variables on this computer

Usage:
  reliquary login [--no-browser]        sign in with your browser
  reliquary logout                      revoke this computer's sign-in and forget it
  reliquary vaults                      the vaults and environments you can read
  reliquary run [--vault V] [--env E] -- <command> [args...]
                                        run a command with the variables in its environment
  reliquary env pull [--vault V] [--env E] [--file .env] [--outside-repo]
                                        write them to a file git ignores (mode 600)
  reliquary env push [--vault V] [--env E] [--file .env] [--wait [--timeout 15m]]
                                        send a .env's values for a person to apply
                                        in the web UI (nothing is set until then)

Options:
  --server <url>   the Reliquary server (else RELIQUARY_URL, else "server" in
                   .reliquary.json, else https://app.reliquary.redmage.cc)
  --vault <v>      a vault's name or id (else "vault" in .reliquary.json;
                   not needed if you can reach only one)
  --env <e>        development (the default), preview or production
                   (else "environment" in .reliquary.json)
  --file <path>    env pull's or push's file (default .env)
  --wait           env push: wait until a person applies or rejects it
  --timeout <t>    env push --wait: how long, like 90s, 15m or 2h (default 15m)
  --outside-repo   env pull: allow a file outside any git repository
  --no-browser     login: print the link without opening a browser
  -h, --help       this help
  -v, --version    the version

Values are never printed. Sign-ins are kept in the OS keychain when there is
one (macOS Keychain, Secret Service, Windows DPAPI), else in
~/.config/reliquary/credentials.json (mode 600); RELIQUARY_CREDENTIALS=file or keychain
chooses.

Commands

reliquary login

Signs this computer in with your browser. Opens the consent page (and prints its link), where you choose the vaults the CLI may read and whether it may send .env files for approval. Waits up to 5 minutes, then lists the vaults and environments it can read. Signing in again revokes the previous sign-in on this computer.

reliquary logout

Revokes this computer's sign-in on the server, then forgets it. Takes --server <url>.

reliquary vaults

Prints each vault the sign-in reaches, one per line: its id, name, your role, and the environments you may read. Takes --server <url>.

reliquary run

reliquary run [--vault V] [--env E] -- <command> [args...]

Fetches one environment's variables and starts the command directly (no shell), with your environment plus the variables. Nothing is written to disk. Standard input, output and error are the command's; SIGINT, SIGTERM, SIGHUP, SIGQUIT and SIGUSR2 are passed on. A variable that replaces one already in your environment is named on stderr. Takes --vault, --env and --server.

Exit code: the command's own; 128 plus the signal number if a signal ended it; 127 if the command wasn't found.

On Windows:

• A bare command name is looked up on PATH with PATHEXT, like cmd.exe does, but not in the current directory; write .\tool.exe for one there.
• .exe and .com files start directly. .cmd and .bat files, like the npm, npx, pnpm and yarn shims, start through cmd.exe /d /v:off /s /c with every argument in double quotes, so &, |, <, >, ^ and parentheses reach the command as text. An argument holding a double quote, a % or a line break can't be passed to a .cmd or .bat safely, so the CLI refuses it with exit code 2 and runs nothing; run the program the shim wraps directly (for example node <script>) instead. Other files (.ps1, .js) are refused: run them through their interpreter.
• Variable names are case-insensitive: a variable replaces an inherited one whatever its case, and two variables whose names differ only in case are refused.
• Ctrl+C reaches the command directly, and the CLI waits for it to finish; closing the console window ends the command and everything it started.

reliquary env pull

reliquary env pull [--vault V] [--env E] [--file .env] [--outside-repo]

Writes one environment to a file (default .env), mode 600, one NAME="value" per line in name order, under a header saying where it came from. Backslash, double quote, newline and carriage return are escaped. Prints the names, never the values.

The file must be inside a git work tree and ignored by git; a file that isn't ignored, is tracked, or is a symbolic link is refused and nothing is written. The check runs before fetching and again before writing.

Also takes --vault, --env and --server.

reliquary env push

reliquary env push [--vault V] [--env E] [--file .env] [--wait [--timeout 15m]]

Sends a .env file's variables to the vault for approval. Nothing is set until an owner or editor applies it in the web app, within 24 hours. Lines it can't take are listed with their reasons and not sent. Prints the names (new, or replacing a value) on stderr and the approval link on stdout, never a value. The sign-in must have been allowed to send .env files; an editor can't push to an owners-only environment.

Also takes --vault, --env and --server.

Exit code: 0 when sent (with --wait, when applied); 1 when refused, rejected or expired; 3 when --wait ran out of time first (the push stays pending).

Options for every command

How the vault, environment and server are chosen

A vault name that two of your vaults share is an error listing their ids.

.reliquary.json

A project file the CLI finds from the current directory upwards. Commit it; it holds ids and names, never values:

{ "server": "https://app.reliquary.redmage.cc", "vault": "<vault id>", "environment": "development" }

All three keys are optional.

Environment variables

Where sign-ins are kept

One sign-in per server, in the operating system's keychain when there is one:

Without one (a server, a container, Linux without secret-tool), sign-ins are kept in credentials.json in the config directory, mode 600 in a mode 700 directory. reliquary login says which it used. The config directory is RELIQUARY_CONFIG_DIR, else %APPDATA%\reliquary on Windows, else $XDG_CONFIG_HOME/reliquary, else ~/.config/reliquary; it also holds the lock file that keeps two commands from refreshing at once.

RELIQUARY_CREDENTIALS=file always uses the file. RELIQUARY_CREDENTIALS=keychain always uses the keychain, and fails if none answers instead of falling back to the file.

A token never goes into a command's arguments, where other programs could see it: the keychain tools get it on standard input.

A sign-in made before the keychain, in credentials.json, keeps working. The next time it changes (a refresh within the hour, a new login, or logout), it moves into the keychain and out of the file.

Exit codes and errors

Common errors: your sign-in was revoked or expired (run reliquary login); the keychain is locked or doesn't answer (unlock it, or set RELIQUARY_CREDENTIALS=file); your role can't read that environment; no such vault or environment for this sign-in; the server has no key for variables. No error prints a value, a token or a server response.