La línea de comandos

El uso de los comandos sobre un proyecto completo, con su directorio .stxt/ y VS Code, se describe en El entorno de trabajo; el resto de herramientas, en Herramientas.

Instalación

Se publica en npm como @stxt-lang/cli y necesita Node 20 o superior:

npm install -g @stxt-lang/cli
stxt --version

stxt 1.0.2 (@stxt-lang/core 1.0.2, spec 2026-09-07)

--version muestra dos versiones y una fecha: la versión del comando, la del parser que incorpora y la fecha de la especificación de STXT que ese parser implementa (la de STXT-SPEC que fija el kit de conformidad). Las dos primeras indican qué hay instalado; la fecha, a qué especificación es conforme: dos instalaciones con paquetes distintos leen el mismo STXT mientras la fecha de la spec coincida. Sin instalación permanente, cualquier comando funciona con npx:

npx @stxt-lang/cli validate --recursive docs/

Para actualizar, npm update -g @stxt-lang/cli; para desinstalarlo, npm uninstall -g @stxt-lang/cli. Desde la 1.0 del paquete, los comandos, sus opciones, los códigos de salida y --format json son estables dentro de su línea 1.x; la salida pensada para personas, no (ver Estabilidad y versiones). El número de versión y las novedades están en el repositorio.

Sinopsis

stxt [--version | --help]
stxt validate <file|dir|->... [--recursive] [--format text|json] [--warn-schema | --no-schema]
              [--max-nesting N] [--max-line-length N] [--max-input-size N]
stxt format   <file|dir|->... [--recursive] [--tabs | --spaces] [--write | --check] [--clean]
              [--max-nesting N] [--max-line-length N] [--max-input-size N]
stxt describe <file|-> [--max-nesting N] [--max-line-length N] [--max-input-size N]
stxt schemas  [path]
stxt install  <file> [--local | --user | --system | --root <dir>] [--force] [--ignore-non-definitions]

Convenciones de la interfaz, comunes a todos los comandos:

• Cada opción tiene una sola forma larga, con doble guion (--recursive). Solo cuatro tienen alias corto, las convenciones Unix habituales: -v (--version), -h (--help), -r (--recursive) y -w (--write).
• --version y --help se atienden en cualquier posición y tienen precedencia sobre el resto: stxt validate --help imprime la ayuda general (no hay ayuda por comando).
• Una opción desconocida —también las de un solo guion— o un comando inexistente son errores de uso y terminan con código 2 sin realizar ninguna acción.
• Los resultados (hallazgos, JSON, documentos formateados, listados) van por la salida estándar; los errores de uso y de lectura, y los errores de sintaxis de format y describe, por la salida de error (el informe de validate es el resultado, y va por la estándar).
• - designa la entrada estándar en validate, format y describe, según la convención Unix: un documento que llega por un pipe se procesa igual que un fichero y se reporta como <stdin>. Se puede dar una sola vez. Sin argumento, ningún comando lee la entrada estándar: es un error de uso.
• Ningún comando reescribe ficheros sin una opción explícita: format solo escribe con --write, e install solo sobrescribe con --force.

Códigos de salida

El contrato es el mismo para todos los comandos: un trabajo de CI puede distinguir un fallo de los documentos de un uso incorrecto del comando.

stxt validate docs/ && make deploy solo ejecuta el despliegue si los documentos validan; un 2 en CI señala un error del script, no de los documentos.

stxt validate

stxt validate <file|dir|->... [--recursive] [--format text|json] [--warn-schema | --no-schema]
              [--max-nesting N] [--max-line-length N] [--max-input-size N]

Para cada documento: lo parsea, resuelve su cadena de gramáticas —los directorios .stxt/ de su carpeta y de todas sus ancestras, después ~/.stxt y /etc/stxt, o lo que diga STXT_PATH; ver Resolución de gramáticas, más abajo— y lo valida contra la gramática de cada namespace que use. Cuando todo pasa no escribe nada y termina con 0.

Los límites del parser protegen frente a entradas desbocadas, y a veces hay que ampliarlos a sabiendas: un registro de eventos en STXT supera con facilidad el tamaño por defecto. stxt validate registro.stxt --max-input-size -1 lo valida entero. Un límite excedido se reporta como cualquier otro error de parseo y corta el parseo de ese documento, así que es siempre su último hallazgo. validate parsea además en streaming: lee el fichero por trozos y suelta cada nodo raíz al validarlo, así que la memoria que usa es del orden de un nodo raíz, no del documento — validar un registro mayor que la memoria funciona.

Un directorio como argumento exige --recursive; sin él es un error de uso (2), lo que evita validar un árbol de directorios por accidente. Se pueden mezclar ficheros, directorios y - en la misma llamada.

Con - el documento se lee de la entrada estándar y en los hallazgos se llama <stdin>. Como no está en ningún directorio, su cadena de gramáticas es la del directorio actual, como si fuera un fichero de ese directorio (la misma cadena que muestra stxt schemas sin argumento); ejecutado desde la raíz del proyecto, valida contra las mismas gramáticas que sus ficheros. El siguiente ejemplo valida la versión confirmada en git del documento de la sección siguiente, con los mismos dos hallazgos:

git show HEAD:docs/book.stxt | stxt validate -

<stdin>:6: [INVALID_VALUE] Published: Invalid date (1 de octubre de 2025) (error)
<stdin>:1: [TOO_FEW_CHILDREN] 0 nodes of 'com.acme.book:isbn' and min is 1 (error)
2 error(s), 0 warning(s)

Los hallazgos

Con el proyecto de El entorno de trabajo —la plantilla com.acme.book en .stxt/ y docs/book.stxt—, un documento con una fecha no válida y sin el ISBN obligatorio produce:

stxt validate docs/book.stxt

/home/ana/libros/docs/book.stxt:6: [INVALID_VALUE] Published: Invalid date (1 de octubre de 2025) (error)
/home/ana/libros/docs/book.stxt:1: [TOO_FEW_CHILDREN] 0 nodes of 'com.acme.book:isbn' and min is 1 (error)
2 error(s), 0 warning(s)

Cada línea es fichero:línea: [CÓDIGO] mensaje (severidad), con la ruta absoluta del fichero, y al final el recuento. El código es estable, va en mayúsculas y es el mismo en todas las herramientas del ecosistema, por lo que sirve para filtrar en un script o para buscar en las especificaciones. Los más habituales:

Un error de cardinalidad se señala en la línea del padre (Book, línea 1), porque es el padre el que carece del ISBN. Los errores de la propia cadena de resolución —una gramática no válida en .stxt/, dos definiciones del mismo namespace en el mismo nivel— se reportan como hallazgos en la línea 0 del fichero causante, no del documento, y hacen fallar la validación: la herramienta no elige una de las dos definiciones.

stxt validate docs/book.stxt

/home/ana/libros/.stxt/otro/copia.stxt:0: [DISCOVERY_DUPLICATE_NAMESPACE] Duplicate definition for namespace 'com.acme.book' at level /home/ana/libros/.stxt: already defined in /home/ana/libros/.stxt/@stxt.template/com.acme.book.stxt (error)
1 error(s), 0 warning(s)

Sin gramática, o con la gramática en aviso

Las gramáticas son opcionales en el lenguaje, pero validate exige poder aplicarlas. Un documento sin namespace no se valida y pasa (STXT-SCHEMA-SPEC §5). Uno con namespace que ninguna gramática de la cadena define produce SCHEMA_NOT_FOUND, también cuando la cadena está vacía: un documento que no se puede validar no cuenta como validado. El resultado depende solo del documento y de su cadena, no de qué otras gramáticas haya instaladas. Para comprobar únicamente la sintaxis está --no-schema. Un documento que es una definición (@stxt.schema o @stxt.template) se comprueba siempre contra su meta-esquema, aunque no haya ninguna otra gramática.

Dos opciones cambian qué cuenta como fallo. --warn-schema rebaja los errores de gramática a avisos, pensado para la introducción de una gramática en un proyecto con documentos anteriores a ella:

stxt validate --warn-schema docs/book.stxt

/home/ana/libros/docs/book.stxt:6: [INVALID_VALUE] Published: Invalid date (1 de octubre de 2025) (warning)
/home/ana/libros/docs/book.stxt:1: [TOO_FEW_CHILDREN] 0 nodes of 'com.acme.book:isbn' and min is 1 (warning)
0 error(s), 2 warning(s)

Termina con 0: hay avisos, pero ningún error. --no-schema comprueba solo la sintaxis, sin resolver ni aplicar gramáticas: el mismo documento pasa sin salida.

Salida JSON

Con --format json la salida es un array con un objeto por hallazgo —file, line, code, message, severity—, y [] cuando todo pasa. No hay resumen ni texto adicional, por lo que se puede encadenar directamente con jq o leer desde otro programa. El código de salida es el mismo que en modo texto.

stxt validate --format json docs/book.stxt

[{"file":"/home/ana/libros/docs/book.stxt","line":6,"code":"INVALID_VALUE","message":"Published: Invalid date (1 de octubre de 2025)","severity":"error"},{"file":"/home/ana/libros/docs/book.stxt","line":1,"code":"TOO_FEW_CHILDREN","message":"0 nodes of 'com.acme.book:isbn' and min is 1","severity":"error"}]

# Cuántos hallazgos de cada código hay en todo el proyecto
stxt validate --format json --recursive docs/ | jq -r '.[].code' | sort | uniq -c

stxt format

stxt format <file|dir|->... [--recursive] [--tabs | --spaces] [--write | --check] [--clean]
            [--max-nesting N] [--max-line-length N] [--max-input-size N]

Reescribe documentos en su forma canónica: la indentación normalizada a tabuladores (o a cuatro espacios con --spaces), un solo espacio tras los dos puntos, sin espacios al final de línea. Trabaja línea a línea: re-renderiza las líneas que abren un nodo y conserva todo lo que el árbol no describe —comentarios, líneas en blanco y el contenido de los bloques >>, que solo se reindenta, incluidas sus líneas en blanco interiores (las finales de un bloque no son contenido y quedan como líneas en blanco sin indentar)—, además del final de línea original (CRLF incluido) y la ausencia de salto final. De los comentarios convierte solo las unidades enteras de indentación (tabuladores o grupos de cuatro espacios) al estilo elegido, una por una, y deja intacto lo que venga detrás. El namespace se escribe únicamente donde el fuente lo escribió.

Tres modos, mutuamente excluyentes:

Otras opciones:

--check equivale a gofmt -l o prettier --check, y es el modo adecuado para CI. --clean obtiene el documento canónico puro; como pierde información, no es el comportamiento por defecto. Un documento con errores de sintaxis se reporta y no se reformatea, en ningún modo. format no tiene modo de gramática: reformatear un documento es independiente de que valide.

Un documento escrito con espacios, un comentario, una línea en blanco y espacios de más:

# Ficha del libro
Book (com.acme.book):
    Title:   Arquitectura de software moderna

    Authors:
        Author: María Pérez
    ISBN: 978-84-123456-7-8

stxt format docs/book.stxt

# Ficha del libro
Book (com.acme.book):
	Title: Arquitectura de software moderna

	Authors:
		Author: María Pérez
	ISBN: 978-84-123456-7-8

El comentario y la línea en blanco se conservan; la indentación es ahora de tabuladores y los espacios sobrantes se han eliminado. Los otros dos modos sobre el mismo fichero:

stxt format --check docs/book.stxt
/home/ana/libros/docs/book.stxt: would be reformatted
# código de salida 1

stxt format --write docs/book.stxt
Formatted /home/ana/libros/docs/book.stxt

stxt format --check docs/book.stxt
# ya no escribe nada: código de salida 0

Combinar --write con --check, o --tabs con --spaces, es un error de uso (2): stxt format: --write and --check cannot be combined.

Con - el documento se lee de la entrada estándar y el resultado va por la salida estándar, lo que convierte a format en un filtro que cualquier editor puede aplicar a la selección; --check - responde <stdin>: would be reformatted y 1 si cambiaría. --write con - es un error de uso: no hay fichero al que volver a escribir.

stxt format --spaces - < docs/book.stxt

stxt format --write -
stxt format: --write cannot be used with - (the standard input); the result is printed to stdout

stxt describe

stxt describe <file|-> [--max-nesting N] [--max-line-length N] [--max-input-size N]

Parsea un único documento y escribe por la salida estándar su árbol lógico en el JSON canónico de STXT-TREE-SPEC: un array con los nodos raíz, y para cada nodo name, canonicalName, el namespace efectivo, la forma ("inline" con value y children, o "block" con lines). No incluye posiciones, comentarios ni campos derivados. Permite procesar un documento STXT desde cualquier programa que lea JSON, sin parser propio.

describe no resuelve gramáticas ni valida: esos resultados no forman parte del árbol lógico. Si el documento tiene errores de sintaxis no emite un árbol parcial: informa los errores por la salida de error y termina con 1. Con - lee el documento de la entrada estándar (stxt describe - < config.stxt), y en los errores lo llama <stdin>. Acepta los mismos límites del parser que validate (--max-nesting, --max-line-length, --max-input-size; -1 desactiva): stxt describe registro.stxt --max-input-size -1 emite el árbol de un documento mayor que el tamaño por defecto.

Book (com.acme.book):
	Title: Arquitectura de software moderna
	Authors:
		Author: María Pérez
	ISBN: 978-84-123456-7-8
	Chapter: Introducción
		Content >>
			Conceptos básicos y objetivos del libro.

stxt describe docs/book.stxt

[
  {
    "name": "Book",
    "canonicalName": "book",
    "namespace": "com.acme.book",
    "form": "inline",
    "value": "",
    "children": [
      {
        "name": "Title",
        "canonicalName": "title",
        "namespace": "com.acme.book",
        "form": "inline",
        "value": "Arquitectura de software moderna",
        "children": []
      },
      {
        "name": "Authors",
        "canonicalName": "authors",
        "namespace": "com.acme.book",
        "form": "inline",
        "value": "",
        "children": [
          {
            "name": "Author",
            "canonicalName": "author",
            "namespace": "com.acme.book",
            "form": "inline",
            "value": "María Pérez",
            "children": []
          }
        ]
      },
      {
        "name": "ISBN",
        "canonicalName": "isbn",
        "namespace": "com.acme.book",
        "form": "inline",
        "value": "978-84-123456-7-8",
        "children": []
      },
      {
        "name": "Chapter",
        "canonicalName": "chapter",
        "namespace": "com.acme.book",
        "form": "inline",
        "value": "Introducción",
        "children": [
          {
            "name": "Content",
            "canonicalName": "content",
            "namespace": "com.acme.book",
            "form": "block",
            "lines": [
              "Conceptos básicos y objetivos del libro."
            ]
          }
        ]
      }
    ]
  }
]

# El título del libro, con jq
stxt describe docs/book.stxt | jq -r '.[0].children[] | select(.canonicalName == "title") | .value'

stxt schemas

stxt schemas [path]

Muestra la cadena de resolución de un documento o de un directorio —por defecto, el directorio actual— y, para cada namespace, qué definición queda activa y de qué fichero procede. Responde a qué gramática se aplica a un documento, y es el primer diagnóstico ante un SCHEMA_NOT_FOUND.

stxt schemas docs

Resolution chain for /home/ana/libros/docs:
    /home/ana/libros/.stxt

Namespaces:
    com.acme.book <- /home/ana/libros/.stxt/@stxt.template/com.acme.book.stxt

La cadena lista los niveles en orden de precedencia: los .stxt/ del documento y de sus ancestros, y después el de usuario y el del sistema si existen. Si el proyecto está dentro de otro con su propio .stxt/ (un monorepo), aparecen los dos, y para cada namespace gana el más cercano. Cuando no hay ningún nivel:

stxt schemas

Resolution chain for /home/ana/notas:
    (empty — no .stxt directory found)

No namespaces resolved.

Los errores de la cadena se muestran en un bloque Errors: al final, con su código. El caso habitual es una copia de la misma gramática en dos rutas del mismo nivel: el namespace se queda sin definición activa hasta que se elimine una, y validate falla con el mismo error.

stxt schemas docs

Resolution chain for /home/ana/libros/docs:
    /home/ana/libros/.stxt

No namespaces resolved.

Errors:
    DISCOVERY_DUPLICATE_NAMESPACE /home/ana/libros/.stxt/otro/copia.stxt: Duplicate definition for namespace 'com.acme.book' at level /home/ana/libros/.stxt: already defined in /home/ana/libros/.stxt/@stxt.template/com.acme.book.stxt

schemas termina siempre con 0, también con errores en la cadena: es un comando informativo; el que falla es validate.

stxt install

stxt install <file> [--local | --user | --system | --root <dir>] [--force] [--ignore-non-definitions]

Instala las definiciones —esquemas y plantillas— de un fichero en un nivel de la cadena de resolución. No es una copia del fichero: primero comprueba que tenga extensión .stxt, que parsee y que cada uno de sus nodos raíz sea una definición que valide contra su meta-esquema (la misma comprobación que hace el resolutor al cargar un nivel), y solo entonces escribe, todo o nada. Cada definición se escribe por separado, en forma canónica, como <nivel>/@stxt.schema/<namespace>.stxt o <nivel>/@stxt.template/<namespace>.stxt, con el namespace que define, no el nombre del fichero de origen; un fichero con varias definiciones se divide en varios.

Esa nomenclatura es una convención de la CLI, no del lenguaje: STXT-DISCOVERY-SPEC §3 no da significado ni a los nombres de fichero ni a los subdirectorios de un nivel, por lo que una gramática colocada a mano puede estar en cualquier ruta del nivel. La convención hace visible, con un ls, qué namespaces define cada nivel.

stxt install book-template.stxt

Installed com.acme.book (@stxt.template) to /home/ana/libros/.stxt/@stxt.template/com.acme.book.stxt

Los casos que hacen fallar la instalación (código 1) y sus mensajes:

stxt install book-template.stxt
stxt install: /home/ana/libros/.stxt/@stxt.template/com.acme.book.stxt already exists (use --force to overwrite)

stxt install docs/book.stxt
stxt install: docs/book.stxt:1: root node 'Book' belongs to 'com.acme.book', not to @stxt.schema or @stxt.template (use --ignore-non-definitions to install only the definitions)

stxt install broken.stxt
stxt install: broken.stxt: invalid @stxt.template definition: Type not valid: NOTATYPE

stxt install notes.txt
stxt install: not an STXT document (.stxt expected): notes.txt

Un fichero que mezcla una plantilla con documentos de ejemplo se instala con --ignore-non-definitions: se instala la plantilla y se omiten los ejemplos. Para compartir una gramática entre todos los proyectos de una máquina, stxt install --user gramatica.stxt.

Resolución de gramáticas y STXT_PATH

Los tres comandos que aplican gramáticas —validate, schemas e install— usan la misma cadena de resolución que la extensión de VS Code y las bibliotecas, la de STXT-DISCOVERY-SPEC §4: para un documento, todos los directorios .stxt/ desde su carpeta hacia arriba, después ~/.stxt y por último /etc/stxt. Dentro de cada nivel se cargan todos los ficheros .stxt, recursivamente, y cada uno debe ser una definición. La precedencia es por namespace: para cada uno prevalece el nivel más cercano que lo defina, y los demás niveles siguen aportando los que aquel no define. Dos definiciones del mismo namespace en el mismo nivel son un error, y ese namespace se queda sin definición.

La variable de entorno STXT_PATH sustituye la cadena entera por una lista de directorios separados por : (; en Windows), en orden de precedencia; las entradas no tienen por qué llamarse .stxt, y una que no exista no aporta nada. Permite que un trabajo de CI no dependa de lo que haya en el ~/.stxt o el /etc/stxt de la máquina que lo ejecuta:

STXT_PATH=./.stxt stxt validate --recursive docs/

Una STXT_PATH definida pero vacía deja la cadena vacía: ningún documento con namespace encuentra gramática, así que validate falla con SCHEMA_NOT_FOUND — un documento que no puede validarse no cuenta como validado. Comprobar solo la sintaxis en ese caso se pide explícitamente con --no-schema (o se rebaja el error a aviso con --warn-schema), y schemas enseña la cadena como (empty — STXT_PATH provides no directories). La CLI no añade ninguna regla propia a esta cadena; toda la política vive en la biblioteca, y por eso es idéntica en todas las herramientas.

Tareas frecuentes

Integración continua. Dos pasos: los documentos validan y están bien formateados. Falla con 1 si algo no pasa, y con 2 si la invocación es incorrecta.

npx @stxt-lang/cli validate --recursive docs/
npx @stxt-lang/cli format --check --recursive docs/

Un Makefile.

check:
	stxt validate --recursive docs/
	stxt format --check --recursive docs/

fmt:
	stxt format --write --recursive docs/

Formatear un proyecto entero por primera vez, pasándolo a espacios:

stxt format --write --spaces --recursive .

Los .stxt/ se saltan; las gramáticas se formatean en una llamada aparte. Los hallazgos como datos —por ejemplo, solo los errores de un código concreto—:

stxt validate --format json --recursive docs/ | jq '.[] | select(.code == "SCHEMA_NOT_FOUND")'

Un documento como JSON para otro programa:

stxt describe config.stxt > config.json

Un documento que no está en disco —lo genera otro programa, o viene de una petición HTTP—, con -:

curl -s https://example.com/api/book.stxt | stxt validate -
curl -s https://example.com/api/book.stxt | stxt describe - | jq '.[0].name'

Límites

Lo que la línea de comandos no hace:

• No lee de la entrada estándar por defecto: se indica con -, y solo validate, format y describe lo aceptan; schemas e install trabajan sobre rutas.
• No convierte a otros formatos: la única salida estructurada es el JSON de describe (el árbol de STXT-TREE-SPEC) y el de validate --format json.
• No hay ayuda por comando: stxt --help es toda la ayuda, y esta página, la referencia.
• No hay parser dentro. Un error de parseo o de validación es de la biblioteca @stxt-lang/core —y, por tanto, común a todas las herramientas—; el sitio para reportarlo es stxt-js. Los de opciones, mensajes o comportamiento del comando, en stxt-cli.