Referencia de CLI

Cada verbo de bxAgents y sus flags.

Referencia de CLI

Usage: boxlang module:bxAgents <verb> [options]

(o la forma más corta bxAgents <verb> [options] - ver Instalación.)

Flags globales

Estos se manejan antes del despacho de verbos y nunca llegan a un verbo - solo son significativos como el primer token, así nunca colisionan con un flag del mismo nombre propio de un verbo.

Todo verbo acepta

--projectRoot=<path> (o una ruta posicional simple como el primer argumento sin flag) para apuntar a un proyecto distinto del directorio actual. Precedencia: flag --projectRoot > primer argumento posicional > directorio de trabajo actual.

Sintaxis de argumentos

Sigue las propias convenciones documentadas de CLI de BoxLang:

Opciones repetidas: gana la última.

Verbos

new

Genera el andamiaje de un nuevo proyecto de agente.

bxAgents new my-agent --model=openai/gpt-5 [--name=...] [--description=...]

• --model es requerido - un slug provider/model (ver Agent.bx).
• --name por defecto toma el propio nombre base del directorio destino.
• Se niega a ejecutarse si el destino ya contiene un Agent.bx.
• Crea Agent.bx, instructions.md, cada carpeta de convención (vacía), una carpeta tests/ lista para ejecutar (tests/box.json + tests/specs/AgentSpec.bx), un .env que declara BOXLANG_HOME=.build/runtime (coincidiendo con el propio home de runtime delimitado que usa serve - ver limitaciones conocidas para exactamente qué cubre y qué no esto), y un .gitignore (.build/, dist/, .env). Nunca sobrescribe un .env/.gitignore existente.
• También ejecuta box install dentro de la nueva carpeta tests/, así que bxAgents test funciona de inmediato sin un paso separado de cd tests && box install. Esto es de mejor esfuerzo: si box no está en PATH o la instalación falla, new igual tiene éxito - el mensaje simplemente te indica ejecutarlo tú mismo. Pasa --skipInstall para omitir este paso por completo.

build

Ejecuta el pipeline de build completo.

bxAgents build [--environment=production] [--verbose]

Escribe .build/app/ y .build/manifest.json. Falla con todos los errores de validación recopilados si el proyecto no es válido.

• --verbose imprime una línea por fase de build en vivo mientras se ejecuta - qué se resolvió/descubrió/validó, conteos por fase (modelos, tools, gateways, advertencias, etc.), qué agentes terminaron registrados en config/WireBox.bx y bajo qué nombres, si se encontró un schedules/Scheduler.bx, y una línea final de tiempo Build completed in Xms. Útil para depurar un build lento o con comportamiento inesperado. Silencioso en cualquier otro caso - --verbose no cuesta nada cuando no se pasa.

test

Ejecuta los propios tests/specs de tu proyecto vía TestBox.

bxAgents test

• Requiere testbox instalado bajo tests/testbox (cd tests && box install).
• Construye tu agente contra el proveedor mock por defecto (el override de entorno test() de Agent.bx) - no se necesita clave de API ni acceso a red.
• Imprime conteos de aprobados/fallidos/con error/omitidos más una línea por fallo, y sale con código distinto de cero si algo falló.

serve

Lanza un proceso real de boxlang-miniserver apuntado a .build/app.

bxAgents serve [--port=8080] [--host=0.0.0.0]

• Requiere un build previo - falla claramente si .build/app no existe.
• Falla claramente si boxlang-miniserver no se encuentra en PATH.
• Escribe .build/miniserver.json (reescrituras habilitadas, rewriteFileName: "index.bxm", health check activado) antes de lanzar.
• Delimita el propio home de runtime de BoxLang del servidor a .build/runtime (vía serverHome) en lugar del ~/.boxlang compartido por defecto, así que la caché de clases compiladas y los overrides de configuración de cada proyecto están aislados - y clean lo elimina gratis, ya que de todos modos borra .build por completo. invoke --server también obtiene esto, ya que reutiliza serve internamente. Esto no se extiende a chat/build/test/invoke por defecto - ver limitaciones conocidas.

chat

REPL interactivo contra el agente construido, usando el propio MiniConsole de BoxLang para la lectura de líneas.

bxAgents chat

• Requiere un build previo.
• Carga GeneratedAgentFactory.bx directamente (sin ningún contenedor ColdBox/WireBox involucrado) y llama a buildAgent() una vez por sesión - exactamente la misma factory que usan las rutas HTTP de serve, así que chat y HTTP nunca divergen.
• Escribe exit o quit para salir.
• Necesita una TTY interactiva real (MiniConsole invoca stty para el modo raw) - no funcionará canalizado/no interactivo.

invoke

Un solo turno no interactivo contra el agente construido: envía un mensaje, imprime la respuesta, sale. Existe para scripting/CI, donde el requisito de TTY de chat es un bloqueo absoluto.

bxAgents invoke --message="What's the weather in Boston?" [--json]
bxAgents invoke --message="..." --server [--port=<port>]

• Requiere un build previo.
• Por defecto (sin --server): carga GeneratedAgentFactory.bx directamente (sin contenedor ColdBox, sin HTTP) y llama al agente una vez - el mismo camino en proceso que usa chat internamente, solo sin el bucle del REPL. No hay ningún prerequisito de serve/gateway en absoluto.
• --server: lanza un proceso real y desechable de boxlang-miniserver (igual que serve), envía el mensaje como un request HTTP real a través de la ruta expuesta con toAi() del proyecto, luego apaga el servidor de nuevo. Ejerce el camino realmente servido (enrutamiento ColdBox, interceptores, gateways) en lugar del atajo en proceso. Requiere una entrada gateways/*.bx con { exposes: "agent", path: "..." } (ver gateways) - falla claramente si ninguna existe. --port por defecto usa un puerto efímero libre para que nunca colisione con un serve ya en ejecución.
• --json imprime {"response": "..."} en lugar de la respuesta en texto plano.

package

Empaqueta un proyecto construido en un .bxa.

bxAgents package [--version=1.0.0]

• Requiere un build previo - lee .build/manifest.json; falla claramente si falta.
• --version por defecto es 1.0.0.
• Escribe dist/{agentName}-{version}.bxa, un .sha256 hermano, y una copia redactada de manifest.json. Ver Despliegue y secretos.

deploy

Envía un proyecto construido/empaquetado a un destino de despliegue real vía la convención pluggable deploy/.

bxAgents deploy --name=production
# o, la forma abreviada solo con flags (solo local):
bxAgents deploy --destination=/path/to/somewhere [--target=local]

• --name=<entry> despacha a cualquier destino que declare la entrada deploy/<entry>.bx/.json nombrada (local, ssh, ftp, sftp, docker, o digitalocean).
• La forma solo con flags (--target=local --destination=..., o sin --target en absoluto) funciona sin ninguna carpeta deploy/ presente - solo local la soporta; cada otro destino requiere una entrada nombrada, ya que necesita más configuración de la que un par de flags puede transportar.
• local/ssh/ftp/sftp requieren un package previo; docker/digitalocean requieren un build previo (construyen directamente desde .build/app).
• ftp/sftp necesitan el módulo bx-ftp instalado junto a BX Agents (ver Instalación).

hash-password

Convierte una contraseña en texto plano en el valor passwordHash que acepta el bloque users de una entrada webui.

bxAgents hash-password --password="correct horse battery staple"

• --password es requerido.
• Imprime el hash a stdout - pbkdf2$<iterations>$<salt>$<derivedKey>, PBKDF2-HMAC-SHA256, con salt por llamada. Seguro de commitear: es unidireccional, y hacer el hash de la misma contraseña dos veces produce dos hashes distintos (ambos válidos).
• Se mantiene deliberadamente idéntico al hasher que la propia interfaz web generada usa para verificar un inicio de sesión - un hash producido aquí siempre se verifica allí.

inspect

Imprime de forma legible un .build/manifest.json existente sin reconstruir.

bxAgents inspect [--json]

• Requiere un build previo.
• Imprime nombre del agente, modelo, entorno, versión del manifest, nombre/versión del generador, y conteo de archivos.
• --json imprime el manifest crudo como JSON en lugar del resumen legible para humanos - útil para scripting.

clean

Elimina la salida .build/ y dist/ de un proyecto.

bxAgents clean

• Solo elimina .build y dist - las convenciones fuente (Agent.bx, tools/, etc.) nunca se tocan.
• Reporta "Nothing to clean" si ninguno de los directorios existe.