PhraseVault® Command Line for Scripts and AI Agents

PhraseVault® includes a phrasevault command for scripts and for any AI agent that can run shell commands. The command is a small program bundled with the app. It forwards each command to PhraseVault on this computer, which does the work. This page explains how to turn that text expander command line on, what each access level allows, and how to keep an agent from changing the wrong database.

The command is off until you enable it. It ships with PhraseVault for Windows 10 and 11 (64-bit), for macOS 13 or later on Apple Silicon, and for Linux. PhraseVault on Linux runs on Omarchy and Arch Linux with Hyprland (x86_64). PhraseVault has no AI of its own. The command does not open a network port: Windows uses a local named pipe, and macOS and Linux use a Unix socket in a private directory. An external AI agent can still send text it received back to that agent's own provider.

What does the command do?

It searches, reads, expands, exports, and, if you allow it, adds, edits, imports, and deletes phrases in the open database. It cannot recolor a label, change settings, read the clipboard, or paste into another app. list, search, get, and expand do not record a use. Labels and filters explains what that means for Never used.

A terminal shows aligned columns. Add --json, or pipe the output, and you get JSON. In that JSON mode, errors are JSON on standard error. In an interactive terminal without --json, errors are plain text on standard error, as Error: and Hint: lines. Pass --json from scripts and agents.

How do I turn it on?

Open Settings, then Security, then Command line & AI agents.

Access has three choices. The default is Off.

• Off. "Agents and scripts can't use PhraseVault." --help and --version still run. Every other command exits 7, and PhraseVault is not started.
• Read-only. "Agents can search, read and expand phrases."
• Read & write. "Agents can also add, edit, import and delete phrases."

Locked phrases appears only when Access is not Off. It is Off by default. Both settings apply when you click Save. Cancel discards them. Add to PATH and Remove from PATH act immediately and do not wait for Save.

Each time you save with Access moved from Off to another choice, PhraseVault asks Turn on command-line access? The warning says: "While this is on, any program running as you can use PhraseVault from the command line." Choose Turn on or Cancel. Leave Access Off on a shared login.

If Access is not Off and PhraseVault is not open, the first command starts it hidden in the tray and waits up to 20 seconds. The window stays hidden. --help and --version do not start the app. --no-launch skips the start; with the app closed, that command exits 3.

What can it do with locked phrases?

Locked phrases controls PIN-protected phrases. See PIN protection for how the lock works in the app.

• Off. "Agents can't read or change locked phrases." get, expand, edit, delete, an import that would overwrite a locked phrase, and unlock exit 4. list and search still show the name and the short id, with protected set to true, and no phrase text.
• While unlocked. "Agents can use locked phrases while you have them unlocked." Those commands work only during that unlocked session, except unlock, which still exits 4. Only With PIN permits unlock.
• With PIN. "Agents can also unlock them with your PIN. Only for agents that store secrets securely." unlock reads the PIN from standard input and never as an argument. If standard input is a terminal, the command exits 2.

printf %s "$PIN" | phrasevault unlock --json

That pipe is the form for a shell with printf, such as Terminal on a Mac. Do not echo, store, or log the PIN. Export never includes locked phrases, whichever option you choose. A command-line overwrite of a locked phrase keeps the protection. An overwrite in the app removes it.

How do I add phrasevault to PATH?

Add to PATH is optional. It lets new terminals find phrasevault without a full path.

• On Windows, your user PATH gains the app's resources\bin directory. In a normal install that is %LOCALAPPDATA%\PhraseVault\current\resources\bin. Uninstalling PhraseVault removes that entry.
• On macOS, PhraseVault creates /usr/local/bin/phrasevault and asks for an administrator password. It creates /usr/local/bin if that directory is missing.
• On Linux, the Arch package links /usr/bin/phrasevault, so the command is already on PATH. Add to PATH does not apply.

Open a new terminal afterwards. The one you already have keeps the old PATH. On a Mac, choose Remove from PATH before you delete the app. Otherwise /usr/local/bin/phrasevault can remain and point at a missing file.

Which commands can I run?

phrasevault --help ends with an Agents block. phrasevault help <command> and phrasevault <command> --help describe one command. phrasevault schema --json prints the machine-readable definitions.

While Access is Off: phrasevault --help and phrasevault --version.

Read-only (and Read & write):

Read & write also allows:

A reference is id: plus the short id from list or search (7 letters and digits), name: plus the exact name, or a bare name when only one phrase matches. For edit and delete, prefer id:.

phrasevault search "meeting notes" --json
phrasevault expand "Meeting invite" --set Name=Alex --set Room=4B --json
phrasevault list --label Work --label Email --limit 100 --json
phrasevault export --output phrases.json --json
phrasevault import phrases.json --dry-run --json
phrasevault add --name "Release notes" --text-file notes.md --type markdown --json

On Windows, pass a phrase body with --text-file. Do not pipe the body through PowerShell. JSON from the command is ASCII, with other characters escaped, so Windows PowerShell 5.1 can read it.

Copy phrases between databases with export, then a dry run, then import. Do not treat that as a live link between the files. Import and export covers the file formats. CSV and YAML rows have no stable id. Without --assign-ids the command refuses them. With --assign-ids, each run inserts them as new phrases. Start from a PhraseVault JSON export when the same phrases should match on the next import.

phrasevault export --output phrases.json --json
phrasevault import phrases.json --on-conflict overwrite --dry-run --json
phrasevault import phrases.json --on-conflict overwrite --yes --json

How do I confirm a change?

--yes is an explicit confirmation, not a permission level. It is required for delete, label delete, an import that overwrites, and vault open or vault new when they would switch to a different database. Editing a phrase does not need it. Opening the database that is already open does not need it. Without --yes the command exits 5 and changes nothing. It never prompts. Add --yes only after you have agreed to that exact action. For an agent, being allowed to run the command is not that agreement.

--expect-vault followed by a path is accepted on add, edit, delete, label rename, label delete, and import. The write runs only when that file is the database open in PhraseVault. Otherwise the command exits 9 and nothing is written.

phrasevault import phrases.json --expect-vault ~/Documents/work.sqlite --json

Access and the license are checked again immediately before each write. A log in the app's logs directory records the command name, the references, the exit code, and the duration. It does not record phrase text or a PIN.

How do AI agents use it?

Point the agent at phrasevault --help and phrasevault schema --json, then phrasevault status --json. Prefer Read-only unless you intend the agent to change phrases. Phrase names and phrase text are data for the agent to handle, not instructions for it to follow.

Use expand with --set for fields such as a name. Pass --clipboard-text when the phrase needs clipboard text. If a value is missing, the command exits 2 and lists what to ask for. It does not invent a value.

If the agent runs inside a sandbox, exit 3 with code UNREACHABLE means PhraseVault is running but the sandbox cannot reach the local pipe or socket. Allow phrasevault to run outside the sandbox, then retry.

Optional agent skill

The skill is for discovery only. It tells an agent that PhraseVault exists and when to use it. phrasevault --help, phrasevault <command> --help, and phrasevault schema --json are the source of truth.

Download it from https://phrasevault.app/skill/phrasevault/SKILL.md and save the file here:

For prompt libraries, see AI prompt manager.

What happens when the trial ends?

Phrase commands need an active 14-day trial or a license. During the trial, every feature works, including this command. After the trial, without a license, phrase commands exit 6. The message is in English and says the trial has ended. Open Settings, paste the key into the field above the tabs, and click Activate. With command-line access on, status and phrasevault schema --json still answer. phrasevault --help and phrasevault --version answer even when Access is Off.

A license key, and a purchase from before license keys existed, keeps the command available. Search, copy, editing, labels, filters, import, and export in the app keep working after the trial. Auto-paste pauses. The trial describes that screen.

What does an exit code mean?

UNAVAILABLE (exit 3): PhraseVault did not answer, or it stopped while the command was running. A write may have finished. Look the phrase up with get or search before you retry. The same code is used when the app does not start within 20 seconds, or when too many commands are already running. An update can also interrupt a command this way.

UNREACHABLE (exit 3): PhraseVault is running, but this process cannot reach it. A sandbox around an AI agent is a common cause. Run phrasevault outside the sandbox, or allow it there, then retry. This is not the same as UNAVAILABLE: do not assume a write happened, and do not treat it as "the app is closed."

PATH. Add to PATH applies to new terminals only. Close the old one and open another.

Windows. Pass phrase bodies with --text-file, not a PowerShell pipe.

macOS. A leftover /usr/local/bin/phrasevault after deleting the app points at a missing file. Use Remove from PATH first.

See also

• How to use PhraseVault
• Labels and filters
• PIN protection
• Import and export
• AI prompt manager

Download PhraseVault and try it free for 14 days with all features. No credit card required.