Referência / CLI
Página traduzida automaticamente
Referência da CLI
Todos os subcomandos do verbatra e as flags globais que eles compartilham, além de como a CLI lê seu ambiente e carrega arquivos .env.
O @verbatra/cli fornece o binário verbatra, uma camada fina sobre o @verbatra/sdk.
Comandos
Estes comandos fazem o trabalho:
init
.env.example para este projeto.extract
translate
watch
check
diff
report
report provenance lista quais traduções uma máquina escreveu e quais uma pessoa revisou.doctor
pseudo
types
export
import
tmx
studio
mcp
Instalar e executar
Instale o @verbatra/cli como dependência de desenvolvimento:
npm install --save-dev @verbatra/cliDepois, execute o binário pelo seu gerenciador de pacotes:
npx @verbatra/cli <command>Você precisa do Node.js ^22.22.0 || >=24 (a CLI 0.12.x aceita ^22.18.0 || >=24).
Quer testar um comando antes de instalar? npx @verbatra/cli <command> (npm) ou pnpm dlx @verbatra/cli <command> (pnpm) funcionam sem uma instalação local prévia. Use sempre o nome com escopo: o nome sem escopo verbatra no npm não pertence a este projeto.
Flags globais
Estas flags significam o mesmo em todo comando que as aceita, então as páginas dos comandos listam só as flags próprias. A última coluna nomeia os comandos que não aceitam uma flag.
| Flag | Argumento | Padrão | Efeito | Não aceita por |
|---|---|---|---|---|
--cwd | <path> | diretório atual | começa a busca pela configuração neste diretório e resolve a partir dele os caminhos que você passa; os arquivos de locale são resolvidos a partir do diretório da configuração que a busca encontrou; o init grava seus arquivos nesse diretório | nenhum |
--config | <path> | busca uma | carrega este arquivo de configuração em vez de buscar; veja a ordem de busca em Arquivo de configuração | init |
--json | nenhum | desativado | imprime um envelope (o objeto JSON da resposta) legível por máquina no stdout, uma linha por registro; os erros continuam indo para o stderr | mcp, studio |
-q, --quiet | nenhum | desativado | imprime só resultados, alertas e erros: sem progresso, dicas nem linhas informativas; funciona antes ou depois do nome do comando | nenhum |
--no-color | nenhum | cor em um terminal | nunca colore a saída; veja Saída no terminal | nenhum |
-h, --help | nenhum | desativado | imprime a ajuda do programa ou do comando e termina com código 0 | nenhum |
-V, --version | nenhum | desativado | imprime a versão da CLI e termina com código 0 | nenhum |
Um comando ou uma flag desconhecida termina com código 2, e o verbatra sozinho, sem comando, também: ele imprime a ajuda no stderr e, quando nenhuma configuração é encontrada, sugere verbatra init. O mcp nunca grava no stdout, já que o stdout é seu canal de protocolo, então ele recusa --json com USAGE_. A partir da 0.12.0, um --cwd que não nomeia um diretório existente termina com código 2 e INVALID_ em todo comando, antes de qualquer leitura ou gravação.
Arquivos de ambiente
translate, watch, doctor, studio e mcp carregam .env.local e depois .env do diretório de trabalho antes de executar. Quando a configuração que a busca encontrou fica em um diretório pai, eles carregam também os mesmos dois arquivos desse diretório; com --config, leem só o diretório de trabalho. Quando um cliente MCP muda suas raízes, o servidor MCP carrega os dois arquivos também da nova raiz do projeto. O doctor --literals é a exceção: ele não lê nenhuma chave de API, então não carrega nenhum dos dois arquivos. Uma variável já definida no seu ambiente real sempre prevalece, depois os arquivos do diretório de trabalho, depois os do diretório da configuração, e um valor no .env.local prevalece sobre a mesma variável no .env. As chaves de API são lidas só do ambiente, nunca do arquivo de configuração nem de uma flag: veja Provedores. Os comandos somente leitura (check, diff, report), os comandos de entrega (export, import), extract, init, pseudo, types e tmx nunca chamam um provedor e não carregam nenhum arquivo .env.
Entradas do .gitignore
Uma execução real de translate, watch, import, tmx import ou pseudo também acrescenta, entre .env, .env.local, .verbatra-local/ e verbatra.cache.json, o que estiver faltando em um .gitignore existente na raiz do projeto, e os nomeia no stderr (--json e --quiet suprimem essa linha). Isso acontece assim que a configuração é carregada, então uma execução que falha depois já o fez. Uma simulação não mexe no arquivo, e nenhum desses comandos cria um; o verbatra init cria. Um .gitignore que é um link simbólico saindo do projeto fica inalterado, com um alerta que --json e --quiet mantêm.
Saída no terminal
A cor, o spinner (indicador de progresso), --quiet e as variáveis que os controlam estão descritos em Saída no terminal.
Códigos de saída
O contrato dos códigos de saída e seus casos-limite estão em Códigos de saída e saída JSON. Cada página de comando lista só os códigos que aquele comando retorna.
Editar no GitHub