PhraseVault® incluye el comando phrasevault para scripts y para cualquier agente de IA que pueda ejecutar comandos de shell. El comando es un programa pequeño que viene con la app. Reenvía cada orden a PhraseVault en este equipo, y la app hace el trabajo. Esta página explica cómo activar la línea de comandos del expansor de texto, qué permite cada nivel de acceso y cómo evitar que un agente cambie la base de datos equivocada.

El comando está apagado hasta que lo actives. Se incluye con PhraseVault para Windows 10 y 11 (64 bits), para macOS 13 o posterior en Apple Silicon y para Linux. PhraseVault en Linux funciona en Omarchy y Arch Linux con Hyprland (x86_64). PhraseVault no tiene IA propia. El comando no abre un puerto de red: en Windows usa una canalización con nombre local, y en macOS y Linux un socket Unix en un directorio privado. Un agente de IA externo puede enviar a su propio proveedor el texto que reciba.

¿Qué hace el comando?

Busca, lee, expande y exporta frases de la base de datos abierta y, si lo permites, también las añade, edita, importa y elimina. No puede cambiar el color de una etiqueta, cambiar ajustes, leer el portapapeles ni pegar en otra aplicación. list, search, get y expand no registran un uso. Etiquetas y filtros explica qué significa eso para Nunca usada.

Un terminal muestra columnas alineadas. Con --json, o si rediriges la salida, obtienes JSON. En ese modo JSON, los errores van en JSON a la salida de error. En un terminal interactivo sin --json, los errores son texto plano en la salida de error, en líneas Error: y Hint:. Desde scripts y agentes, pasa --json.

¿Cómo lo activo?

Abre Configuración, luego Seguridad y después Línea de comandos y agentes de IA.

Acceso tiene tres opciones. El valor inicial es Apagado.

Apagado. «Los agentes y los scripts no pueden usar PhraseVault.» --help y --version siguen funcionando. Cualquier otro comando termina con el código 7 y PhraseVault no se inicia.
Solo lectura. «Los agentes pueden buscar, leer y expandir frases.»
Lectura y escritura. «Los agentes también pueden añadir, editar, importar y eliminar frases.»

Frases bloqueadas solo aparece cuando Acceso no está en Apagado. El valor inicial es Apagado. Las dos opciones se aplican al pulsar Guardar. Cancelar las descarta. Agregar a PATH y Quitar de PATH actúan al momento y no esperan a Guardar.

Cada vez que guardas con Acceso pasado de Apagado a otra opción, PhraseVault pregunta ¿Activar el acceso por línea de comandos? El aviso dice: «Mientras esté activado, cualquier programa que se ejecute como tú puede usar PhraseVault desde la línea de comandos.» Elige Activar o Cancelar. Deja el acceso en Apagado en una cuenta compartida.

Si el acceso no está en Apagado y PhraseVault no está abierto, el primer comando lo inicia oculto en la bandeja y espera hasta 20 segundos. La ventana sigue oculta. --help y --version no inician la app. --no-launch omite el inicio; con la app cerrada, ese comando termina con el código 3.

¿Qué puede hacer con las frases bloqueadas?

Frases bloqueadas controla las frases protegidas con PIN. Proteger frases con un PIN explica el bloqueo en la app.

Apagado. «Los agentes no pueden leer ni cambiar frases bloqueadas.» get, expand, edit, delete, una importación que sobrescribiría una frase bloqueada y unlock terminan con el código 4. list y search siguen mostrando el nombre y el id corto, con protected en true, y sin el texto.
Desbloqueadas. «Los agentes pueden usar frases bloqueadas mientras las tengas desbloqueadas.» Esos comandos solo funcionan durante esa sesión, excepto unlock, que sigue terminando con el código 4. Solo Con PIN permite unlock.
Con PIN. «Los agentes también pueden desbloquearlas con tu PIN. Solo para agentes que guardan secretos de forma segura.» unlock lee el PIN solo desde la entrada estándar, nunca como argumento. Si la entrada estándar es un terminal, el comando termina con el código 2.

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

Esa canalización es para un shell con printf, como Terminal en Mac. No muestres el PIN, no lo guardes y no lo escribas en un registro. La exportación nunca incluye frases bloqueadas, elijas la opción que elijas. Sobrescribir desde la línea de comandos conserva la protección. Sobrescribir en la app la quita.

¿Cómo añado phrasevault a PATH?

Agregar a PATH es opcional. Así los terminales nuevos encuentran phrasevault sin una ruta completa.

En Windows, el PATH de tu usuario gana el directorio resources\bin de la app. En una instalación normal es %LOCALAPPDATA%\PhraseVault\current\resources\bin. Desinstalar PhraseVault quita esa entrada.
En macOS, PhraseVault crea /usr/local/bin/phrasevault y pide una contraseña de administrador. Crea /usr/local/bin si ese directorio no existe.
En Linux, el paquete de Arch enlaza /usr/bin/phrasevault, así que el comando ya está en PATH. Agregar a PATH no se aplica.

Abre un terminal nuevo después. El que ya tenías conserva el PATH anterior. En Mac, elige Quitar de PATH antes de borrar la app. Si no, /usr/local/bin/phrasevault puede quedar apuntando a un archivo que ya no está.

¿Qué comandos puedo usar?

phrasevault --help termina con un bloque Agents. phrasevault help <command> y phrasevault <command> --help describen un comando. phrasevault schema --json imprime las definiciones legibles por máquina.

Con Acceso en Apagado: phrasevault --help y phrasevault --version.

Solo lectura (y Lectura y escritura):

Comando	Qué hace
`status`	Versión de la app, nombre del archivo de la base de datos, número de frases, acceso, estado de la licencia y si las frases bloqueadas están desbloqueadas. No cambia nada.
`list`	Nombres e ids, primero las más usadas. Repite `--label` para exigir cada etiqueta.
`search <query>`	Ordena los resultados como la app.
`get <ref>`	Una frase, con su texto.
`expand <ref>`	Rellena marcadores. `--set Key=value` completa un campo. `--clipboard-text` aporta el texto de un marcador de portapapeles, porque el comando nunca lee el portapapeles.
`labels`	Nombre, color y cantidad de cada etiqueta.
`export`	JSON de PhraseVault. `--label` lo reduce. `--output` escribe un archivo. Las frases bloqueadas quedan fuera.
`vault list` y `vault current`	Archivos de bases de datos recientes y el que está abierto.
`lock` y `unlock`	`lock` termina la sesión del PIN. `unlock` la inicia con un PIN en la entrada estándar, y solo con Con PIN; con Desbloqueadas termina con el código 4.
`import <file> --dry-run`	Previsualiza una importación y no escribe nada. El comando necesita un archivo o la entrada estándar.

Lectura y escritura permite además:

Comando	Qué hace
`add` y `edit`	Crea o cambia una frase. `add` acepta `--label`; sin él, la frase nueva no tiene etiquetas. `edit` acepta `--label` para sustituir las etiquetas y `--no-labels` para quitarlas. Una etiqueta nombrada aquí se crea si no existe. No hay un comando para cambiar el color.
`delete <ref> --yes`	Elimina una frase.
`import <file>`	Lee JSON de PhraseVault, CSV de TextExpander® o YAML de Espanso. Por defecto se omiten las frases que ya existen.
`vault open <path>` y `vault new <path>`	Abre un archivo de base de datos o crea uno vacío. El nombre nuevo debe terminar en `.sqlite`.
`label rename` y `label delete <name> --yes`	Cambia el nombre de una etiqueta o la quita de todas las frases. Las frases se quedan.

Una referencia es id: más el id corto de list o search (7 letras y dígitos), name: más el nombre exacto, o un nombre solo cuando coincide una única frase. Para edit y delete, usa 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

En Windows, pasa el texto de la frase con --text-file. No lo canalices por PowerShell. El JSON del comando es ASCII, con el resto de caracteres escapados, para que Windows PowerShell 5.1 pueda leerlo.

Copia frases entre bases de datos con una exportación, luego una prueba y luego la importación. Eso no mantiene los dos archivos enlazados. Los formatos están en importar y exportar frases. Las filas CSV y YAML no tienen un id estable. Sin --assign-ids el comando las rechaza. Con --assign-ids, cada ejecución las inserta como frases nuevas. Parte de un JSON exportado por PhraseVault cuando quieras que las mismas frases coincidan en la siguiente importación.

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

¿Cómo confirmo un cambio?

--yes es una confirmación explícita, no un nivel de permiso. Hace falta en delete, label delete, una importación que sobrescribe y en vault open o vault new cuando cambiarían a otra base de datos. Editar una frase no lo necesita. Abrir la base de datos que ya está abierta no lo necesita. Sin --yes el comando termina con el código 5 y no cambia nada. Nunca pregunta. Añade --yes solo después de haber aceptado esa acción concreta. Que un agente pueda ejecutar el comando no es esa aceptación.

--expect-vault seguido de una ruta vale en add, edit, delete, label rename, label delete e import. La escritura solo ocurre si ese archivo es la base de datos abierta en PhraseVault. Si no, el comando termina con el código 9 y no se escribe nada.

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

El acceso y la licencia se comprueban de nuevo justo antes de cada escritura. Un registro en el directorio de registros de la app guarda el nombre del comando, las referencias, el código de salida y la duración. No guarda el texto de las frases ni un PIN.

¿Cómo lo usan los agentes de IA?

Indica al agente phrasevault --help y phrasevault schema --json, y después phrasevault status --json. Prefiere Solo lectura salvo que quieras que el agente cambie frases. Los nombres y el texto son datos que el agente trata, no instrucciones que deba seguir.

Usa expand con --set para campos como un nombre. Pasa --clipboard-text cuando la frase necesita texto del portapapeles. Si falta un valor, el comando termina con el código 2 y lista qué hay que preguntar. No inventa un valor.

Si el agente corre dentro de un entorno aislado, el código de salida 3 con el código UNREACHABLE significa que PhraseVault está en marcha, pero el aislamiento no llega a la canalización o al socket local. Permite que phrasevault se ejecute fuera de ese entorno y vuelve a intentarlo.

Skill opcional para el agente

El skill solo sirve para el descubrimiento. Le dice al agente que PhraseVault existe y cuándo usarlo. La referencia sigue siendo phrasevault --help, phrasevault <command> --help y phrasevault schema --json.

Descárgalo desde https://phrasevault.app/skill/phrasevault/SKILL.md y guárdalo aquí:

Ruta	Quién lo lee
`~/.claude/skills/phrasevault/SKILL.md`	Claude Code
`~/.agents/skills/phrasevault/SKILL.md`	Codex, Cursor, Gemini CLI, Grok Build, VS Code Copilot

Para bibliotecas de prompts, consulta el gestor de prompts.

¿Qué pasa al terminar la prueba?

Los comandos de frases necesitan una prueba de 14 días en curso o una licencia. Durante la prueba funcionan todas las funciones, incluido este comando. Después, sin licencia, esos comandos terminan con el código 6. El mensaje está en inglés y dice que la prueba ha terminado. Abre Configuración, pega la clave en el campo que hay sobre las pestañas y haz clic en Activar. Con el acceso de la línea de comandos activado, status y phrasevault schema --json siguen respondiendo. phrasevault --help y phrasevault --version responden incluso con Acceso en Apagado.

Una clave de licencia, y una compra anterior a las claves de licencia, mantienen el comando disponible. La búsqueda, copiar, editar, las etiquetas, los filtros, la importación y la exportación en la app siguen funcionando después de la prueba. El pegado automático se pausa. La prueba describe esa pantalla.

¿Qué significa un código de salida?

Código	Nombre	Significado
0	OK	Correcto. Lee la salida estándar.
1	ERROR	La operación falló. Lee el mensaje. No repitas una escritura hasta haber comprobado la frase.
2	USAGE	Comando, opción o valor incorrectos, o a una plantilla le falta un valor.
3	UNAVAILABLE o UNREACHABLE	Los dos casos de abajo.
4	PROTECTED	No se puede usar una frase bloqueada, o el PIN era incorrecto o está en espera.
5	CONFIRMATION_REQUIRED	Faltaba `--yes`. No cambió nada.
6	NOT_LICENSED	La prueba ha terminado.
7	ACCESS_DENIED	El acceso está en Apagado, o está en Solo lectura y este comando escribe.
8	NOT_FOUND	No coincide ninguna frase, etiqueta ni archivo de base de datos.
9	CONFLICT	Coinciden varias frases, el nombre ya existe, el archivo nuevo de base de datos ya existe, la base abierta no es la ruta de `--expect-vault`, o un cambio de base de datos sigue en curso.

UNAVAILABLE (código 3): PhraseVault no respondió, o dejó de responder mientras el comando se ejecutaba. Una escritura puede haber terminado. Busca la frase con get o search antes de reintentar. El mismo código aparece si la app no arranca en 20 segundos o si ya hay demasiados comandos en marcha. Una actualización también puede interrumpir un comando así.

UNREACHABLE (código 3): PhraseVault está en marcha, pero este proceso no puede llegar hasta él. Un entorno aislado alrededor de un agente de IA es una causa habitual. Ejecuta phrasevault fuera de ese entorno, o permítelo ahí, y vuelve a intentarlo. No es lo mismo que UNAVAILABLE: no des por hecho que se escribió algo y no lo trates como «la app está cerrada».

PATH. Agregar a PATH solo afecta a los terminales nuevos. Cierra el anterior y abre otro.

Windows. Pasa el texto con --text-file, no por una canalización de PowerShell.

macOS. Un /usr/local/bin/phrasevault que queda tras borrar la app apunta a un archivo ausente. Usa antes Quitar de PATH.

Ver también

Descarga PhraseVault y pruébalo 14 días gratis con todas las funciones. Sin tarjeta.

Línea de comandos de PhraseVault® para scripts y agentes de IA