Referencia / CLI
Página traducida automáticamente
Referencia de la CLI
Todos los subcomandos de verbatra y los flags globales que comparten, además de cómo la CLI lee tu entorno y carga los archivos .env.
@verbatra/cli incluye el binario verbatra, una capa fina sobre @verbatra/sdk.
Comandos
Estos comandos hacen el trabajo:
init
.env.example para este proyecto.extract
translate
watch
check
diff
report
report provenance lista qué traducciones escribió una máquina y cuáles revisó una persona.doctor
pseudo
types
export
import
tmx
studio
mcp
Instala e invoca
Instala @verbatra/cli como dependencia de desarrollo:
npm install --save-dev @verbatra/cliLuego ejecuta el binario a través de tu gestor de paquetes:
npx @verbatra/cli <command>Necesitas Node.js ^22.22.0 || >=24 (la CLI 0.12.x acepta ^22.18.0 || >=24).
¿Quieres probar un comando antes de instalar? npx @verbatra/cli <command> (npm) o pnpm dlx @verbatra/cli <command> (pnpm) funcionan sin una instalación local previa. Usa siempre el nombre con scope: el nombre verbatra sin scope en npm no pertenece a este proyecto.
Flags globales
Estos flags significan lo mismo en cada comando que los acepta, así que las páginas de comandos solo listan sus propios flags. La última columna nombra los comandos que no aceptan un flag.
| Flag | Argumento | Por defecto | Efecto | No lo aceptan |
|---|---|---|---|---|
--cwd | <path> | directorio actual | empieza aquí la búsqueda de la config y resuelve contra él las rutas que pasas; los archivos de locale se resuelven contra el directorio de la config encontrada; init escribe ahí sus archivos | ninguno |
--config | <path> | buscar uno | carga este archivo de config en lugar de buscar uno; consulta el orden de búsqueda | init |
--json | ninguno | desactivado | imprime un envoltorio legible por máquina en stdout, una línea por registro; los errores siguen yendo a stderr | mcp, studio |
-q, --quiet | ninguno | desactivado | imprime solo resultados, avisos y errores: sin progreso, sugerencias ni líneas informativas; funciona antes o después del nombre del comando | ninguno |
--no-color | ninguno | color en un terminal | nunca colorea la salida; consulta Salida en el terminal | ninguno |
-h, --help | ninguno | desactivado | imprime la ayuda del programa o del comando y sale con 0 | ninguno |
-V, --version | ninguno | desactivado | imprime la versión de la CLI y sale con 0 | ninguno |
Un comando o flag desconocido sale con 2, igual que un verbatra sin comando: imprime la ayuda en stderr y, si no encuentra configuración, sugiere verbatra init. mcp nunca escribe en stdout, porque stdout es su canal de protocolo, así que rechaza --json con USAGE_. Desde 0.12.0, un --cwd que no nombra un directorio existente sale con 2 e INVALID_ en todos los comandos, antes de leer o escribir nada.
Archivos de entorno
translate, watch, doctor, studio y mcp cargan .env.local y luego .env desde el directorio de trabajo antes de ejecutarse. Cuando la configuración que encontró la búsqueda está en un directorio superior, cargan después los mismos dos archivos también desde ese directorio; con --config solo leen el directorio de trabajo. Cuando un cliente MCP cambia sus raíces, el servidor MCP carga también ambos archivos desde la nueva raíz del proyecto. doctor --literals es la excepción: no lee ninguna clave de API, así que no carga ninguno de los dos archivos. Una variable ya definida en tu entorno real siempre gana, después los archivos del directorio de trabajo, luego los del directorio de la configuración, y un valor en .env.local gana a la misma variable en .env. Las claves de API se leen solo del entorno, nunca del archivo de configuración ni de un flag: consulta Proveedores. Los comandos de solo lectura (check, diff, report), los comandos de entrega (export, import), extract, init, pseudo, types y tmx nunca llaman a un proveedor y no cargan archivos .env.
Entradas de .gitignore
Una ejecución real de translate, watch, import, tmx import o pseudo también añade a un .gitignore existente en la raíz del proyecto las entradas que le falten de .env, .env.local, .verbatra-local/ y verbatra.cache.json, y las nombra en stderr (--json y --quiet omiten esa línea). Ocurre en cuanto se carga la configuración, así que una ejecución que falla después ya lo ha hecho. Un dry run no toca el archivo, y ninguno de estos comandos crea uno; eso lo hace verbatra init. Un .gitignore que es un enlace simbólico que sale del proyecto se deja sin cambios, con un aviso que --json y --quiet conservan.
Salida en el terminal
El color, el spinner, --quiet y las variables que los controlan se describen en Salida en el terminal.
Códigos de salida
El contrato de códigos de salida y sus casos límite están en Códigos de salida y salida JSON. Cada página de comando lista solo los códigos que devuelve ese comando.
Editar en GitHub