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

Crea un nuevo proyecto de agente de una de tres formas mutuamente excluyentes: generar el andamiaje desde una plantilla incorporada, clonar un repositorio de GitHub, o instalar un paquete de ForgeBox.

# Generar el andamiaje desde una plantilla incorporada (por defecto: minimal)
bxAgents new my-agent --model=openai/gpt-5 [--template=minimal|webui-chat|slack-bot|telegram-bot|github-bot|mcp-server|scheduled|multi-agent] [--name=...] [--description=...]

# Clonar un repositorio de GitHub existente
bxAgents new my-agent --repo=owner/repo-name

# Instalar un paquete de ForgeBox
bxAgents new my-agent --forgebox=some-package-slug

• --template, --repo y --forgebox nombran tres FUENTES de proyecto distintas - se aplica exactamente una. Combinar dos de ellas es un error.
• Modo --template (el predeterminado cuando no se pasa ninguna opción de fuente - minimal):
  • --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.
  • --template elige una de 8 plantillas incorporadas, cada una añadiendo un poco de contenido preconfigurado sobre el esqueleto base anterior:
    • minimal - el esqueleto desnudo, nada más.
    • webui-chat - añade un gateways/webui.bx que expone la UI de chat web en /chat.
    • slack-bot - añade un adaptador de canal gateways/slack.bx, más las líneas de marcador de posición SLACK_BOT_TOKEN/SLACK_APP_TOKEN correspondientes en .env.
    • telegram-bot - añade un adaptador de canal gateways/telegram.bx, más una línea de marcador de posición TELEGRAM_BOT_TOKEN correspondiente en .env.
    • github-bot - añade un adaptador de canal gateways/github.bx, más las líneas de marcador de posición GITHUB_TOKEN/GITHUB_WEBHOOK_SECRET/GITHUB_BOT_NAME correspondientes en .env.
    • mcp-server - añade un servidor de herramientas de ejemplo mcp/exampleServer.bx y una entrada gateways/mcpExpose.bx que lo expone como servidor MCP en /mcp.
    • scheduled - añade un schedules/Scheduler.bx real que llama al agente con un temporizador diario.
    • multi-agent - añade un configure() al Agent.bx raíz que declara dos subagentes (researcher, writer), cada uno generado como su propio subagents/<name>/Agent.bx + instructions.md reales.
  • 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.
• Modo --repo (--repo=owner/repo-name o una URL completa): clona el repositorio mediante una dependencia JGit incluida - no es necesario tener instalado el binario git. Siempre clona de forma superficial (profundidad 1) y siempre elimina la carpeta .git resultante después, de modo que el nuevo proyecto empieza con un historial limpio en lugar de quedar atado al propio remoto del repositorio plantilla. Se niega a ejecutarse en un directorio que ya existe y no está vacío, y falla claramente si no se encuentra ningún Agent.bx en el repositorio clonado.
• Modo --forgebox (--forgebox=<slug>): instala un paquete de ForgeBox hablando directamente con la propia API REST de ForgeBox (no requiere el CLI box). Falla claramente si el slug no existe, la descarga falla, o el paquete instalado no tiene un Agent.bx en su raíz (desenvolviendo primero un nivel de anidamiento, ya que muchos archivos de ForgeBox envuelven su contenido en una única carpeta de nivel superior).
• --model, --repo y --forgebox se excluyen mutuamente en el sentido de que solo el modo --template necesita --model - --repo/--forgebox nunca lo requieren, ya que el proyecto fuente ya define el suyo propio.
• --name/--description se ignoran (con una advertencia en la salida) cuando se usa --repo/--forgebox - el proyecto clonado/instalado define el suyo propio.
• El paso de conveniencia box install para tests/ (y --skipInstall) solo aplican al modo --template - la propia carpeta tests/ de un proyecto clonado/instalado (si es que tiene una) se deja intacta.

build

Ejecuta el pipeline de build completo.

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

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.
• --generatorVersion sobrescribe la cadena grabada en generator.version de manifest.json (ver El manifest) - por defecto "dev" cuando se omite. Existe para herramientas que construyen contra una versión publicada específica de este módulo y quieren que eso quede registrado en el manifest, en lugar del valor por defecto de desarrollo local.

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=127.0.0.1]

• Requiere un build previo - falla claramente si .build/app no existe.
• Falla claramente si boxlang-miniserver no se encuentra en PATH.
• Sirve siempre el agente en /__bxagents (POST /invoke, POST /stream, POST /batch, GET /info), declare lo que declare el proyecto en gateways/ - consulta La ruta de agente siempre activa para exigir un token en ella, o desactivarla.
• 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                                  # rápido, en el mismo proceso
bxAgents chat --server [--port=<puerto>]       # aplicación completa, servidor propio desechable
bxAgents chat --connect=http://127.0.0.1:8080  # aplicación completa, servidor que ya tienes en marcha

Tres modos, un solo REPL:

• Requiere un build previo - salvo con --connect, que habla con un servidor que mantiene otra persona y por tanto no necesita nada construido localmente.
• Por defecto: 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 el agente en sí nunca diverge. Lo que sí cambia es todo lo que aporta ColdBox: sin models/, sin scheduler, sin interceptores, sin registro de gateways. Cuando eso importa, usa --server.
• --server: arranca un miniserver real en un puerto efímero de loopback y conduce el REPL sobre HTTP contra la ruta de agente /__bxagents siempre activa del proyecto, y lo apaga al salir. --port fija el puerto en lugar de tomar uno libre.
• --connect: conduce el mismo REPL contra un servidor en marcha, sin arrancar ni detener nada. La URL es la raíz del servidor (http://host:puerto), no la ruta del agente - chat la añade por su cuenta.
• --server y --connect son mutuamente excluyentes: uno dice "arráncame un servidor", el otro "no lo hagas". Pasar ambos falla de inmediato en lugar de honrar uno en silencio.
• Ambos modos HTTP hacen streaming de la respuesta: la contestación aparece token a token a medida que el agente la produce, por la subruta /stream (SSE) de la ruta, en vez de llegar de golpe al terminar el turno. Si el stream no se puede abrir - un servidor antiguo sin subruta /stream, o un proxy que no deja pasar text/event-stream - recurre a /invoke y obtienes la respuesta completa al final en lugar de un error.
• Ambos modos HTTP arrastran el threadId del servidor entre turnos, así que una sesión es una sola conversación y no una serie de primeros mensajes inconexos.
• Un turno que se detiene a esperar una decisión humana en el bucle lo indica en lugar de aparentar que responde con silencio, y señala el endpoint /gateways/interactions/ donde se envía la decisión.
• Si la ruta está protegida tras agentApi.tokenEnvVar, estos modos reciben un 401 claro en lugar de un timeout confuso - no envían ningún token.
• Escribe exit o quit para salir.
• Necesita una TTY interactiva real (MiniConsole invoca stty para el modo raw) - no funcionará canalizado/no interactivo. Usa invoke para scripting.

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 BxAgents (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="<tu-contraseña>"

• --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.

doctor

Comprueba el entorno y el proyecto en busca de los problemas que más habitualmente rompen un build.

bxAgents doctor [--json]

• No requiere un build previo - está pensado precisamente para ejecutarse cuando algo no funciona.
• Informa de la versión de BoxLang, de si el módulo bx-ai está cargado, de si se encuentra Agent.bx, de si la estructura del proyecto valida, y de los módulos de apoyo que falten.
• Distingue entre problemas (que impedirán un build) y avisos (que no), y termina con un recuento de ambos.
• --json imprime el mismo informe como JSON, para scripting y CI.