---
title: "Referencia de la CLI"
description: "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."
type: "reference"
---
# 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`](https://verbatra.kreitz-webdev.de/es/docs/sdk.md).

## Comandos [#comandos]

Estos comandos hacen el trabajo:

<Cards>
  <Card title="init" href="https://verbatra.kreitz-webdev.de/es/docs/cli/init.md">Crea una configuración de verbatra y un `.env.example` para este proyecto.</Card>
  <Card title="extract" href="https://verbatra.kreitz-webdev.de/es/docs/cli/extract.md">Analiza el código de tu aplicación en busca de llamadas de traducción y añade las claves nuevas al archivo del locale de origen.</Card>
  <Card title="translate" href="https://verbatra.kreitz-webdev.de/es/docs/cli/translate.md">Traduce cada locale de destino una vez y luego sale.</Card>
  <Card title="watch" href="https://verbatra.kreitz-webdev.de/es/docs/cli/watch.md">Retraduce en cada cambio del origen hasta que lo interrumpas.</Card>
  <Card title="check" href="https://verbatra.kreitz-webdev.de/es/docs/cli/check.md">Informa de qué claves faltan o están obsoletas por locale, solo lectura.</Card>
  <Card title="diff" href="https://verbatra.kreitz-webdev.de/es/docs/cli/diff.md">Lista las claves exactas que se añadirían, se retraducirían o están huérfanas por locale, solo lectura.</Card>
  <Card title="report" href="https://verbatra.kreitz-webdev.de/es/docs/cli/report.md">Imprime un informe de solo lectura: `report provenance` lista qué traducciones escribió una máquina y cuáles revisó una persona.</Card>
  <Card title="doctor" href="https://verbatra.kreitz-webdev.de/es/docs/cli/doctor.md">Valida la configuración del proyecto e informa de todos los problemas a la vez, sin llamar a un proveedor.</Card>
  <Card title="pseudo" href="https://verbatra.kreitz-webdev.de/es/docs/cli/pseudo.md">Genera un pseudolocale a partir de las cadenas de origen, sin llamar a un proveedor.</Card>
  <Card title="types" href="https://verbatra.kreitz-webdev.de/es/docs/cli/types.md">Genera declaraciones de TypeScript para las claves de tu catálogo y los argumentos de sus mensajes, sin llamar a un proveedor.</Card>
  <Card title="export" href="https://verbatra.kreitz-webdev.de/es/docs/cli/export.md">Exporta las cadenas sin traducir para un traductor humano, como libro de Excel, como un archivo CSV o TSV por locale o como un archivo XLIFF por locale para una herramienta TAO.</Card>
  <Card title="import" href="https://verbatra.kreitz-webdev.de/es/docs/cli/import.md">Importa un libro rellenado o un archivo delimitado de vuelta a los archivos de locale.</Card>
  <Card title="tmx" href="https://verbatra.kreitz-webdev.de/es/docs/cli/tmx.md">Importa una memoria de traducción TMX de otra herramienta a la memoria de este proyecto, o exporta la memoria de este proyecto como archivo TMX.</Card>
  <Card title="studio" href="https://verbatra.kreitz-webdev.de/es/docs/cli/studio.md">Arranca Verbatra Studio, el panel local de traducción.</Card>
  <Card title="mcp" href="https://verbatra.kreitz-webdev.de/es/docs/cli/mcp.md">Arranca un servidor MCP por stdio que expone las herramientas de verbatra a un cliente MCP.</Card>
</Cards>

## Instala e invoca [#instala-e-invoca]

Instala `@verbatra/cli` como dependencia de desarrollo:

```bash
npm install --save-dev @verbatra/cli
```

Luego ejecuta el binario a través de tu gestor de paquetes:

```bash
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 [#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](https://verbatra.kreitz-webdev.de/es/docs/config-file.md) | `init` |
| `--json` | ninguno | desactivado | imprime un [envoltorio](https://verbatra.kreitz-webdev.de/es/docs/cli/output.md#salida-json) 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](https://verbatra.kreitz-webdev.de/es/docs/cli/output.md#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_ERROR`. Desde 0.12.0, un `--cwd` que no nombra un directorio existente sale con `2` e [`INVALID_OPTION`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#invalid_option) en todos los comandos, antes de leer o escribir nada.

## Archivos de entorno [#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](https://verbatra.kreitz-webdev.de/es/docs/providers.md). 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 [#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`](https://verbatra.kreitz-webdev.de/es/docs/cli/init.md). 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 [#salida-en-el-terminal]

El color, el spinner, `--quiet` y las variables que los controlan se describen en [Salida en el terminal](https://verbatra.kreitz-webdev.de/es/docs/cli/output.md#salida-en-el-terminal).

## Códigos de salida [#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](https://verbatra.kreitz-webdev.de/es/docs/cli/output.md#códigos-de-salida). Cada página de comando lista solo los códigos que devuelve ese comando.