PhraseVault® には、スクリプトと、シェルコマンドを実行できる AI エージェント向けの phrasevault コマンドがあります。アプリに同梱された小さなプログラムで、各コマンドをこのパソコンの PhraseVault に渡し、実際の処理はアプリが行います。このページでは、定型文のコマンドラインをオンにする手順、各アクセスでできること、エージェントが別のデータベースを書き換えないようにする方法を説明します。

コマンドは、オンにするまで使えません。対象は Windows 10 および 11（64 ビット）、Apple Silicon の macOS 13 以降、Linuxです。Linux版のPhraseVaultは、HyprlandのOmarchyとArch Linux（x86_64）で動作します。PhraseVault 自体に AI はありません。コマンドはネットワークポートを開きません。Windows ではローカルの名前付きパイプ、macOS と Linux では非公開ディレクトリの Unix ソケットを使います。外部の AI エージェントは、受け取ったテキストをそのエージェント自身の提供者へ送ることがあります。

コマンドは何をしますか？

開いているデータベースの定型文を検索、読み取り、展開、エクスポートでき、許可すれば追加、編集、インポート、削除もできます。ラベルの色変更、設定の変更、クリップボードの読み取り、他のアプリへの貼り付けはできません。list、search、get、expand は使用回数を記録しません。未使用との関係はラベルとフィルターで説明しています。

ターミナルでは列をそろえて表示します。--json を付けるか、出力をパイプすると JSON になります。その JSON モードでは、エラーは標準エラーへの JSON です。--json なしの対話的なターミナルでは、エラーは標準エラーへの平文で、Error: と Hint: の行になります。スクリプトとエージェントでは --json を付けてください。

オンにするには？

設定、セキュリティ、コマンドラインとAIエージェント の順に開きます。

アクセス は 3 段階です。初期値はオフです。

オフ。「エージェントとスクリプトは PhraseVault を使えません。」 --help と --version は動作します。それ以外は終了コード 7 で、PhraseVault は起動しません。
読み取り専用。「エージェントはフレーズを検索、読み取り、展開できます。」
読み書き。「エージェントはフレーズの追加、編集、インポート、削除もできます。」

ロックされたフレーズ は、アクセスがオフでないときだけ表示されます。初期値はオフです。この 2 つは保存で反映されます。キャンセル すると破棄されます。PATH に追加 と PATH から削除 はすぐに実行され、保存を待ちません。

アクセスをオフから別の段階にして保存するたびに、コマンドラインアクセスをオンにしますか？ と尋ねます。本文は「オンの間は、あなたとして動作しているプログラムがコマンドラインから PhraseVault を使用できます。」です。オンにする か キャンセル を選んでください。共用のログインではオフのままにしてください。

アクセスがオフでなく、PhraseVault が開いていない場合、最初のコマンドはアプリをトレイに隠したまま起動し、最大 20 秒待ちます。ウィンドウは表示されません。--help と --version はアプリを起動しません。--no-launch は起動を省きます。アプリが閉じているとそのコマンドは終了コード 3 になります。

ロックされた定型文はどうなりますか？

ロックされたフレーズ は、PIN で保護した定型文を制御します。アプリ側のロックは定型文の本文を PIN で保護する方法を参照してください。

オフ。「エージェントはロックされたフレーズを読み取りも変更もできません。」 get、expand、edit、delete、ロックされた定型文を上書きするインポート、unlock は終了コード 4 です。list と search は名前と短い ID を、protected が true の状態で表示し、本文は出しません。
ロック解除中。「ロックを解除している間、エージェントはロックされたフレーズを使えます。」同じコマンドはその解除中だけ使えます。ただし unlock は終了コード 4 のままです。unlock を許すのは PIN で だけです。
PIN で。「エージェントは PIN でロックを解除することもできます。シークレットを安全に保存するエージェントにのみ使ってください。」 unlock は PIN を標準入力からのみ読み、引数にはしません。標準入力がターミナルのときは終了コード 2 です。

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

このパイプは、Mac のターミナルのように printf があるシェル向けです。PIN を表示、保存、記録しないでください。どのオプションでも、エクスポートにロックされた定型文は含まれません。コマンドラインでの上書きは保護を維持します。アプリでの上書きは保護を外します。

PATH に追加するには？

PATH に追加 は任意です。新しいターミナルがフルパスなしで phrasevault を見つけられるようになります。

Windows では、ユーザーの PATH にアプリの resources\bin が加わります。通常のインストールでは %LOCALAPPDATA%\PhraseVault\current\resources\bin です。PhraseVault をアンインストールすると、この項目は削除されます。
macOS では /usr/local/bin/phrasevault を作り、管理者パスワードを求めます。/usr/local/bin がなければ作成します。
Linux では、Arch パッケージが /usr/bin/phrasevault を用意するため、コマンドは最初から PATH にあります。PATH に追加 は使いません。

そのあと、新しいターミナルを開いてください。開いたままのターミナルは古い PATH のままです。Mac でアプリを削除する前に PATH から削除 を選んでください。残った /usr/local/bin/phrasevault が、ないファイルを指すことがあります。

どのコマンドが使えますか？

phrasevault --help の末尾に Agents の説明があります。phrasevault help <command> と phrasevault <command> --help は 1 つのコマンドを説明します。phrasevault schema --json は機械が読める定義を出します。

アクセスがオフのあいだ: phrasevault --help と phrasevault --version。

読み取り専用（読み書きでも使えます）:

コマンド	内容
`status`	アプリのバージョン、データベースのファイル名、定型文の件数、アクセス、ライセンスの状態、ロックされた定型文が解除されているか。変更はしません。
`list`	名前と ID。使用回数の多い順です。すべてのラベルを条件にするには `--label` を繰り返します。
`search <query>`	アプリと同じ順位で探します。
`get <ref>`	1 件の定型文と本文。
`expand <ref>`	プレースホルダーを展開します。`--set Key=value` で欄を埋めます。`--clipboard-text` はクリップボード用の文言を渡します。コマンドはクリップボードを読みません。
`labels`	ラベルの名前、色、件数。
`export`	PhraseVault の JSON。`--label` で絞り、`--output` でファイルに書きます。ロックされた定型文は除きます。
`vault list` と `vault current`	最近のデータベースファイルと、今開いているファイル。
`lock` と `unlock`	`lock` は PIN のセッションを終えます。`unlock` は標準入力の PIN で開始し、PIN でのときだけ使えます。ロック解除中では終了コード 4 です。
`import <file> --dry-run`	インポートを下見し、何も書きません。ファイルか標準入力が必要です。

読み書き では次も使えます。

コマンド	内容
`add` と `edit`	定型文を作るか変更します。`add` は `--label` を受け付け、付けなければラベルなしで作成されます。`edit` は `--label` でラベルを置き換え、`--no-labels` で消します。ないラベル名は作成されます。色を変えるコマンドはありません。
`delete <ref> --yes`	定型文を 1 件削除します。
`import <file>`	PhraseVault の JSON、TextExpander® の CSV、Espanso の YAML を読みます。既定では、すでにある定型文は飛ばします。
`vault open <path>` と `vault new <path>`	データベースを開くか、空のファイルを作ります。新しい名前は `.sqlite` で終わります。
`label rename` と `label delete <name> --yes`	ラベルの名前を変えるか、すべての定型文から外します。定型文自体は残ります。

参照は、list か search の短い ID（英数字 7 文字）に id: を付けたもの、正確な名前に name: を付けたもの、または 1 件だけ一致するときの名前だけです。edit と delete では 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

Windows では本文を --text-file で渡してください。PowerShell のパイプでは渡さないでください。コマンドの JSON は ASCII で、それ以外の文字はエスケープされるため、Windows PowerShell 5.1 でも読めます。

データベース間で定型文を写すには、エクスポート、下見、インポートの順です。2 つのファイルを常時つなぐ機能ではありません。ファイル形式は定型文のインポートとエクスポートを参照してください。CSV と YAML の行には安定した ID がありません。--assign-ids がないとコマンドは受け付けません。--assign-ids を付けると、実行のたびに新しい定型文として追加されます。次回も同じ定型文として突き合わせるなら、PhraseVault の JSON 書き出しから始めてください。

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

変更を確認するには？

--yes は明示的な確認であり、権限の段階ではありません。delete、label delete、上書きするインポート、別のデータベースへ切り替える vault open と vault new に必要です。定型文の編集には不要です。すでに開いているデータベースを開くときも不要です。--yes がないと終了コード 5 で、何も変わりません。確認の質問は出ません。その操作そのものに同意してから --yes を付けてください。エージェントがコマンドを実行できることは、その同意にはなりません。

--expect-vault とパスは、add、edit、delete、label rename、label delete、import で使えます。そのファイルが PhraseVault で開いているデータベースのときだけ書き込みます。そうでなければ終了コード 9 で、何も書きません。

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

アクセスとライセンスは、書き込みの直前に毎回確認されます。アプリのログディレクトリには、コマンド名、参照、終了コード、所要時間が残ります。定型文の本文と PIN は残りません。

AI エージェントでの使い方

エージェントには、まず phrasevault --help と phrasevault schema --json、続いて phrasevault status --json を見せてください。定型文を変更させないなら 読み取り専用 にしてください。名前と本文は、エージェントが扱うデータであり、従うべき指示ではありません。

名前などの欄は expand と --set で埋めます。クリップボードの文言が必要なときは --clipboard-text を渡します。値が足りないと終了コード 2 になり、何を尋ねるべきかが示されます。値は作られません。

エージェントがサンドボックス内で動いているとき、終了コード 3 の UNREACHABLE は、PhraseVault は動いているのに、サンドボックスがローカルのパイプまたはソケットへ届かないという意味です。phrasevault をサンドボックスの外で許可してから、もう一度実行してください。

任意のエージェントスキル

このスキルは、エージェントに PhraseVault があることと、いつ使うかを知らせるだけです。仕様の基準は phrasevault --help、phrasevault <command> --help、phrasevault schema --json です。

https://phrasevault.app/skill/phrasevault/SKILL.md からダウンロードし、次の場所に保存してください。

パス	読み取るツール
`~/.claude/skills/phrasevault/SKILL.md`	Claude Code
`~/.agents/skills/phrasevault/SKILL.md`	Codex、Cursor、Gemini CLI、Grok Build、VS Code Copilot

プロンプトのライブラリはプロンプト管理を参照してください。

試用期間が終わると？

定型文のコマンドには、進行中の 14 日間の試用かライセンスが必要です。試用中は、このコマンドを含むすべての機能が使えます。試用後にライセンスがないと、定型文のコマンドは終了コード 6 になります。メッセージは英語で、試用が終わったことを伝えます。設定を開き、タブの上の欄にキーを貼り付けて 有効化 をクリックしてください。コマンドラインのアクセスがオンなら、status と phrasevault schema --json は試用後も応答します。phrasevault --help と phrasevault --version は、アクセスがオフでも応答します。

ライセンスキー、およびライセンスキー導入前の購入では、コマンドを引き続き使えます。試用後も、アプリでの検索、コピー、編集、ラベル、フィルター、インポート、エクスポートは動作します。自動貼り付けは一時停止します。その画面は無料トライアルで説明しています。

終了コードの意味

コード	名前	意味
0	OK	成功です。標準出力を読んでください。
1	ERROR	操作に失敗しました。メッセージを読み、定型文を確認するまで書き込みをやり直さないでください。
2	USAGE	コマンド、フラグ、値が不正か、テンプレートに値が足りません。
3	UNAVAILABLE または UNREACHABLE	下の 2 つの場合です。
4	PROTECTED	ロックされた定型文を使えないか、PIN が違うか、待ち時間中です。
5	CONFIRMATION_REQUIRED	`--yes` がありません。変更はありません。
6	NOT_LICENSED	試用が終わっています。
7	ACCESS_DENIED	アクセスがオフか、読み取り専用なのにこのコマンドは書き込みます。
8	NOT_FOUND	一致する定型文、ラベル、データベースファイルがありません。
9	CONFLICT	複数が一致する、名前が既にある、新しいデータベースファイルが既にある、開いているデータベースが `--expect-vault` のパスではない、またはデータベースの切り替えがまだ終わっていません。

UNAVAILABLE（コード 3）: PhraseVault が応答しなかったか、コマンドの途中で応答を止めました。書き込みが完了していることがあります。やり直す前に get または search で定型文を確認してください。20 秒以内に起動しないときや、コマンドが多すぎるときも同じコードです。アップデートがコマンドを中断することもあります。

UNREACHABLE（コード 3）: PhraseVault は動いていますが、このプロセスからは届きません。AI エージェントのサンドボックスがよくある原因です。phrasevault をサンドボックスの外で実行するか、そこで許可してからやり直してください。UNAVAILABLE とは別です。書き込みがあったとは見なせず、「アプリが閉じている」とも扱わないでください。

PATH。 PATH に追加 は新しいターミナルにだけ効きます。古いターミナルを閉じて、新しいものを開いてください。

Windows。 本文は PowerShell のパイプではなく --text-file で渡してください。

macOS。 アプリ削除後に残った /usr/local/bin/phrasevault は、ないファイルを指します。先に PATH から削除 を使ってください。

PhraseVault をダウンロードして、14 日間すべての機能を無料で試せます。クレジットカードは不要です。

スクリプトとAIエージェント向け PhraseVault® コマンドライン