CLI de Lingua

Referencia de comandos y opciones

Consulta todos los comandos, opciones, límites, modos de salida y códigos estables del CLI de Lingua.

Explorar guías del CLI

Instala el CLI con Homebrew en macOS, usa @linguacode/cli mediante npm o npx, o compílalo desde el código fuente. Fija una versión para automatización.

Esta referencia sigue el mismo catálogo estructurado que genera lingua --help. El build del website falla si su snapshot del catálogo se separa del código fuente del CLI.

Comandos

Comando Propósito
lingua utility <utility-id> Ejecuta un adaptador de utilidad compartido.
lingua capsule validate <file> Valida una RunCapsuleV1 sin ejecutarla.
lingua capsule replay <file> Verifica y repite una Capsule confiable de una sola fuente.
lingua capsule verify <file> Comparación estricta del source capturado; comando de build desde source, aún no publicado.
lingua repro pack <capsule> --entry <path> Empaqueta una Capsule de JavaScript y los archivos que elijas en un sobre de reproducción; experimental.
lingua repro review <envelope> Muestra lo que pide una reproducción y su token de aprobación; no ejecuta nada.
lingua repro run <envelope> --approve <token> Ejecuta una reproducción aprobada dentro de un backend de contención, o la rechaza; experimental.
lingua run <file-or-directory> Ejecuta un archivo o proyecto convencional.
lingua list utilities Imprime el registro actual de utilidades.
lingua completion [bash|zsh|fish|install] Detecta e instala autocompletado o genera el script de un shell.
lingua --version Imprime la versión del CLI integrada en el build.
lingua --help Imprime la ayuda de terminal.

Opciones

Opción La usa Significado
--input <file> utility Lee la entrada de la utilidad desde un archivo.
--option key=value utility Repítela para pasar opciones del adaptador.
--stdin <file> run Envía el contenido del archivo como stdin.
--timeout <ms> run, capsule replay, capsule verify Detiene después de 100–300000 ms.
--env NAME=value run, capsule replay, capsule verify Repítela para agregar una variable explícita.
--entry <path> repro pack Ruta relativa .mjs o .cjs donde queda el código de la Capsule.
--file <path> repro pack Repítela para agregar un archivo, relativo a --root.
--node <major> repro pack Versión mayor de Node.js que pide la reproducción.
--approve <token> repro run Token de aprobación que imprime repro review.
--json comandos con datos Emite un documento JSON estructurado.
--quiet comandos con datos Oculta diagnósticos de Lingua, no la salida del comando.
--yes completion Aprueba los cambios detectados sin pedir confirmación.
--dry-run completion Muestra shells y archivos de destino sin escribir.
--color <auto|always|never> todos Controla los estilos de diagnósticos humanos.
-- run Envía cada token restante al programa.
--help, -h todos Muestra ayuda.
--version, -v nivel principal Imprime la versión del CLI.

Códigos de salida

Código Nombre Significado
0 ok El comando terminó correctamente.
1 userInputError Los argumentos, la entrada, el archivo o la forma son inválidos.
2 runtimeError La ejecución falló, agotó el tiempo, se detuvo o devolvió un código no cero.
3 unsupportedCapability El runtime, modo, toolchain o salida no es compatible.
4 internal Una excepción inesperada llegó al límite del CLI.
5 verificationFailed La verificación estricta detectó diferencias.
6 verificationInconclusive La evidencia no permite establecer un pass estricto.

Contrato de salida

Los errores humanos usan una forma fácil de buscar:

lingua run: error[missing-runtime]: Required runtime "lua" is not available on PATH.

Con --json, el mismo motivo estable aparece en stdout:

{
  "ok": false,
  "reason": "missing-runtime",
  "detail": "Required runtime \"lua\" is not available on PATH."
}

Las guías prácticas documentan los envelopes correctos específicos. Los códigos existentes nunca cambian de número.

Verificación estricta del source capturado (sin publicar)

lingua capsule verify <file> --timeout <ms> --env NAME=value --json está disponible desde el CLI 1.6.0; en instalaciones anteriores revisa primero lingua capsule verify --help. Compara exactamente status, stdout y stderr; no verifica un archivo modificado, seguridad, ejecución hermética ni equivalencia entre motores. Solo acepta baselines exitosos de texto con evidencia completa, y las grabaciones de Python, Go y Ruby web son inconclusas porque el motor de la app es distinto del runtime del CLI. ok es verdadero únicamente para verdict pass; las diferencias terminan con código 5 y la evidencia inconclusa con 6. Los errores de entrada, capacidades, runtime e internos conservan los códigos 1–4. Replay conserva su contrato de salida basado únicamente en ejecución.

Casos de regresión (sin publicar, compilaciones desde código)

lingua capsule verify <file> --target <file> --json

lingua capsule verify-suite <suite> --root <directory> --json

--target <file> ejecuta el archivo relativo guardado actual igual que el código capturado (mismo modo de runtime y directorio de trabajo del baseline); --root <directory> limita los destinos de la suite y usa el directorio actual por defecto. La suite v1 contiene baselines completos sin cambios, ejecuta hasta 20 casos/4 MiB en serie con un presupuesto total de cinco minutos y devuelve verdict estricto por caso. Importar o mostrar una vista previa nunca ejecuta código. Disponible desde el CLI 1.6.0.

Reproducciones con permisos (experimental, compilaciones desde código)

lingua repro pack <capsule> --entry main.mjs --file lib/sum.mjs --root <directory> > repro.json empaqueta una Capsule de JavaScript y los archivos que elijas en un sobre que niega la red y solo permite escrituras desechables. Se rechaza un archivo que un enlace simbólico saca de la raíz o que no es UTF-8. lingua repro review repro.json revisa cada hash, lista los controles obligatorios e imprime un token de aprobación sin ejecutar nada. lingua repro run repro.json --approve <token> --json ejecuta los bytes revisados dentro de Seatbelt en macOS, sin red, sin procesos hijos y escribiendo solo en scratch y output, y compara la salida exactamente con la Capsule: código 0 si coincide, 5 si difiere o hubo un acceso denegado, 6 si falta evidencia. Se niega antes de lanzar si la aprobación ya no corresponde (código 1), si la versión mayor de Node.js es otra, si no hay backend o si falta un control (código 3). En macOS no se pueden observar los accesos denegados, así que el cumplimiento queda como not-observed, nunca clean.