Docs / Referencia · CLI

Referencia

Referencia del CLI · forjabot

forjabot es el instalador de Forja. Trae un bot del catálogo, lo deja en tu propia nube y lo mantiene al día. No lo instalas: lo corres con npx, y termina imprimiendo pasos claros que tu agente ejecuta — desplegar, conectar canales, configurar. Tiene exactamente cinco comandos.

No necesitas instalar nada global

npx descarga y corre forjabot al vuelo. Escribes npx forjabot <comando> y listo — la versión más reciente cada vez, sin npm install -g. Tu agente (Claude Code o Codex) puede correr estos comandos por ti; tú solo respondes las preguntas de negocio.

Cómo se usa

La forma es siempre la misma: npx forjabot <comando> [argumentos] [--key HZN-…]. Si escribes npx forjabot sin comando, arranca init (el asistente). Cualquier palabra que no sea un comando válido imprime la lista de comandos y sale.

Comando	Qué hace
init	Asistente interactivo: idioma, licencia (o una gratis), elige giro, descarga y onboarding del negocio.
list	Muestra el catálogo de bots disponibles. No requiere licencia.
install <slug>	Instala un giro directo, sin pasar por el asistente.
update	Trae la versión nueva del bot conservando tu config y tu base de conocimiento.
doctor	Diagnóstico del bot instalado: archivos, config, versión, licencia y si el bot responde en línea.

Flags y argumentos reales

El CLI tiene pocas flags. --key es la principal; --email y --name sirven para el arranque gratis sin teclear. Todo lo demás son argumentos posicionales.

Elemento	Dónde	Qué es
--key HZN-…	init · install · update · doctor	Tu licencia. Se normaliza a mayúsculas. Si no la pasas, se usa la guardada.
--yes	init · install	No-interactivo: acepta los defaults sin preguntar. Para agentes y CI (también `FORJA_YES=1`).
--giro <slug>	init	Elige el giro sin pasar por el menú (mismo efecto que `install <slug>` pero dentro del asistente).
--email · --name	init	Para «empezar gratis» sin teclear (útil si tu teclado no mete la `@` en la terminal).
--cerebro · --tono · …	init	Rellenan el onboarding sin menús: `--cerebro claude\|chatgpt\|grok`, `--tono cercano\|formal\|divertido`, `--negocio`, `--que`, `--ofrece` (con precios), `--horario`, `--ubicacion`, `--telefono`, `--web`, `--pagos`, `--faq`, `--reglas`, `--lang es\|en`.
<slug>	install	El bot/giro a instalar. Posicional y obligatorio. Ver Giros disponibles.
[dir]	update · doctor	Carpeta del bot. Opcional: si lo omites, se autodetecta desde donde estés.
HORIZONTES_KEY	variable de entorno	Licencia por env. Segundo en el orden de resolución.
FORJA_SERVER · HORIZONTES_SERVER	variable de entorno	Sobre-escribe el servidor de licencias. Avanzado — casi nunca lo tocas.

De dónde sale la licencia, en este orden: la flag --key → la variable HORIZONTES_KEY → la que quedó guardada en ~/.forja/config.json. La primera que exista, gana.

Para agentes: modo no-interactivo

Cuando el CLI lo corre tu agente (Claude Code / Codex) o un CI, no hay menús de flechas. Pásale todo por flags para que no se quede esperando: npx forjabot init --yes --giro barberia --email tu@correo.com. Si falta un dato obligatorio, el CLI falla con un código ([E-INPUT-REQUIRED], [E-GIRO-NOT-FOUND]) diciéndole qué flag pasar — nunca se cuelga.

El idioma se recuerda

La primera vez, init te pregunta español o inglés y lo guarda. De ahí en adelante todos los comandos hablan en ese idioma. update respeta además el idioma con el que instalaste ese bot en particular.

init

forjabot init Gratis

El punto de partida. Un asistente que te lleva de cero a un bot listo para desplegar, preguntándote una cosa a la vez.

Uso: npx forjabot init — o simplemente npx forjabot (sin comando arranca el asistente).
Qué hace: 1) Elige idioma (español/inglés) y lo guarda. 2) Licencia — tres opciones que navegas con flechas ↑↓: pegar tu HZN-XXXX-XXXX-XXXX, «empezar gratis» (te crea una licencia del bot Starter), o «Conseguir Forja+» (te explica que la licencia viene con la comunidad de Horizontes IA). 3) Valida la licencia e imprime tu plan. 4) Muestra el catálogo filtrado por tu plan — los premium salen bloqueados como 🔒 requiere <plan>. 5) Descarga el bot y crea la carpeta ./<slug>. 6) Estampa tier, idioma y giro en wrangler.toml. 7) Si es el bot genérico (Starter), elige el cerebro (Claude / OpenAI / Grok) y te hace ~6 preguntas del negocio, escribiendo tu member/config.local.ts.
Flags: Interactivo con menús de flechas ↑↓. Acepta --key HZN-… (salta pegar la licencia) y --email / --name (para el arranque gratis sin teclear). Tu API key nunca se teclea aquí: al desplegar, va como secreto de Cloudflare.

Terminal

# asistente — no requiere instalación global
$ npx forjabot init

  ◇ Forja
  Idioma / Language
   1. Español     2. English
  › 1

  ¿Ya tienes una licencia?
   1. Sí, pegar mi licencia
   2. No — empezar gratis (bot Starter)
  › 2

  Validando licencia… ✓  plan free

  Bots disponibles:
   1. Bot Starter · genérico
  Bajando Bot Starter… ✓ 84 KB · v1.0.0

  ✓ Config lista · tu bot ya sabe de tu negocio
  ✓ Bot instalado  →  ./starter

list

forjabot list Sin licencia

El catálogo, tal cual. Útil para ver qué giros existen y cuáles están disponibles antes de instalar.

Uso: npx forjabot list
Qué hace: Consulta el catálogo en vivo e imprime, por cada bot, su nombre, su giro, su estado —disponible o próximamente— y una descripción corta.
Flags: Ninguna. No pide licencia — cualquiera puede ver el catálogo.

Terminal

$ npx forjabot list

  ◇ Forja  ·  bots de IA para tu negocio · por Horizontes IA

  Restaurante        restaurante          disponible
  Toma pedidos y reservas por WhatsApp, 24/7.

  Inmobiliaria       inmobiliaria         disponible
  Califica compradores y agenda visitas.

  Hotelería          hoteleria            próximamente
  Reservas de hospedaje y cotización de eventos.

install

forjabot install <slug> [--key HZN-…]

La ruta directa: instala un giro por su slug sin pasar por el asistente. Ideal cuando ya sabes qué quieres y ya tienes licencia guardada — o cuando montas bots en serie.

Uso: npx forjabot install <slug> · con licencia explícita: npx forjabot install barberia --key HZN-XXXX-XXXX-XXXX
Qué hace: Valida la licencia, descarga el bot, crea la carpeta ./<slug> y estampa tier, idioma y giro en wrangler.toml. Termina con los pasos que sigue tu agente. No corre onboarding (a diferencia de init): la config del negocio la aterriza tu agente con la plantilla del giro.
Flags: <slug> es obligatorio — si falta: «Falta el bot. Usa install <slug> o list». --key HZN-… es opcional si ya tienes licencia guardada; si falta por completo: «Falta la licencia. Usa --key o corre init». Si el bot es premium y tu plan no alcanza, verás el motivo + cómo desbloquearlo.

Terminal

$ npx forjabot install barberia --key HZN-7Q2K-9F3D-VX8M

  ◇ Forja  ·  bots de IA para tu negocio
  Bajando barberia… ✓ 84 KB · v1.0.0

  ✓ Bot instalado  →  ./barberia

  Lo que sigue (tu agente de Claude Code lo hace por ti):
    1.  cd barberia
    2.  pídele a tu agente:  "configura mi chatbot"  (skill /configurar-mi-chatbot)
    3.  conecta tu Cloudflare y tus canales — el agente te guía.

update

forjabot update [dir] [--key HZN-…]

Jala la versión nueva del bot sin tocar tu trabajo. Corre esto cuando saquemos mejoras.

Uso: npx forjabot update — dentro de la carpeta del bot, o desde su carpeta madre (se autodetecta). También npx forjabot update <carpeta>.
Qué hace: Revalida la licencia, compara tu versión instalada contra el catálogo y, si hay una nueva, la descarga y la extrae preservando lo tuyo: member/*.local.ts, member/kb/, tus .env/.dev.vars y el estado de instalación. Si ya estás al día, te lo dice y no hace nada.
Flags: [dir] opcional (la carpeta del bot). --key HZN-… para la revalidación; sin licencia no puede actualizar, pero tu bot sigue corriendo en la versión actual.

Terminal

$ npx forjabot update

  ◇ Forja  ·  bots de IA para tu negocio
  Revalidando licencia… ✓
  Instalado: v1.0.0  ·  Última: v1.1.0
  Bajando v1.1.0… ✓ 86 KB

  ✓ Actualizado a v1.1.0  (tu config y tu KB se conservaron)
  Para publicar los cambios, pídele a tu agente:
    "reinstala dependencias y despliega mi bot"  (pnpm install && pnpm deploy)

Actualizar no publica

update solo trae los archivos nuevos a tu carpeta. Los cambios no están en vivo hasta que tu agente reinstale dependencias y despliegue (pnpm install && pnpm deploy). El CLI nunca despliega por su cuenta.

doctor

forjabot doctor [dir] [--key HZN-…]

El chequeo de salud. Cuando algo se sienta raro, corre doctor: revisa lo esencial y te dice ✓ lo que está bien, ⚠ lo que conviene revisar y ✗ lo que está roto, con una pista de cómo arreglarlo.

Uso: npx forjabot doctor — dentro de la carpeta del bot (o pásala: npx forjabot doctor <carpeta>).
Qué hace: Seis chequeos: 1) encuentra la carpeta del bot y su marcador de instalación; 2) archivos clave — wrangler.toml, package.json, node_modules, member/config.local.ts; 3) lee del wrangler.toml el BOT_NAME, el BOT_NICHE y la URL del panel; 4) tu versión vs. el catálogo; 5) valida la licencia; 6) hace ping a <panel>/admin/overview — un 200 o un 401 significa que el bot responde en línea.
Flags: [dir] opcional. --key HZN-… para el chequeo de licencia (si no, avisa que falta pero corre el resto). Cierra con un conteo de «cosas que revisar».

Terminal

$ npx forjabot doctor

  ◇ Forja  ·  bots de IA para tu negocio
  ✓ Bot encontrado en ./barberia
  ✓ Instalado: barberia v1.1.0
  ✓ wrangler.toml presente
  ✓ package.json presente
  ✓ Dependencias instaladas
  ✓ Negocio configurado (member/config.local.ts)
  ✓ Nombre del negocio: Barbería El Filo
  ✓ Giro (nicho): barberia
  ✓ Estás en la última versión
  ✓ Licencia activa (pro)
  ✓ El bot responde en línea (https://mi-bot.workers.dev)

  Todo en orden. Tu bot está sano.

forjabot login [--no-browser] [--force]

Conecta tu terminal con tu cuenta de forjabots.com — igual que wrangler login o gh auth login. Se abre el navegador solo (entra con Google o GitHub) y la terminal detecta el regreso. Funciona igual en Windows, Mac y Linux; si el navegador no se abre, el CLI imprime la URL para abrirla a mano.

Uso: npx forjabot login — una sola vez por máquina. Las credenciales quedan en ~/.forja/credentials.json (solo tuyas, permisos restringidos).
Qué desbloquea: Tu panel en app.forjabots.com: tus bots con métricas en vivo, y el pair automático al desplegar.
Flags: --no-browser no intenta abrir el navegador (solo imprime la URL). --force vuelve a iniciar sesión aunque ya haya una activa.

$ npx forjabot login

  Abre el navegador para entrar (Google o GitHub)…
  Si no se abre: https://app.forjabots.com/api/cli/auth?...

  ✓ conectado como tu@correo.com
  Siguiente: despliega tu bot y corre  forjabot pair

pair

forjabot pair [dir] [--url https://…] [--name "…"]

Vincula un bot ya desplegado con tu panel de app.forjabots.com. Registra el bot bajo tu cuenta y configura solo los secrets del Worker (vía wrangler) — tú no copias tokens a mano. Es idempotente: correrlo de nuevo no duplica ni rompe nada.

Uso: npx forjabot pair — dentro de la carpeta del bot, después del deploy. Requiere sesión (login primero).
Qué hace: 1) verifica que el bot responda; 2) lo registra en tu cuenta; 3) setea CONTROL_PLANE_TOKEN y CONTROL_PLANE_URL en el Worker; 4) confirma la conexión. Al terminar, tu bot aparece en tu panel con sus métricas.
Flags: --url la URL del Worker si el wrangler.toml aún no la trae. --name para renombrarlo en el panel. Si tu bot es de antes, primero forjabot update (necesita la versión con API de panel).

$ npx forjabot pair

  Verificando el bot… ✓
  Registrando en tu cuenta… ✓
  Configurando secrets… ✓

  ✓ bot conectado — míralo en https://app.forjabots.com/dashboard

whoami · logout

forjabot whoami · forjabot logout

whoami te dice con qué cuenta está conectada la terminal (o si no hay sesión). logout borra las credenciales locales de esta máquina.

Giros disponibles

El <slug> que le pasas a install decide el giro del bot: al instalar, el CLI estampa el BOT_NICHE correspondiente en tu wrangler.toml, lo que re-etiqueta el panel y enciende el playbook de ese giro. Estos son los slugs que el CLI reconoce; los que no coincidan con ninguno quedan como generico (el bot Starter, con su onboarding guiado).

Slug (install)	Giro	BOT_NICHE
restaurante	Restaurante	restaurante
cafeteria	Cafetería	cafeteria
panaderia	Panadería	panaderia
barberia	Barbería	barberia
salon · salon-de-belleza	Salón de belleza	salon
spa	Spa	spa
dentista	Dentista	dentista
clinica	Clínica	clinica
gimnasio	Gimnasio	gimnasio
coach	Coach	coach
inmobiliaria	Inmobiliaria	inmobiliaria
tienda	Tienda	tienda
crm · crm-ventas	CRM / Ventas	crm
hoteleria	Hotelería	hoteleria

salon-de-belleza y crm-ventas son alias: instalan el mismo giro que salon y crm. La disponibilidad real (y qué requiere plan) la manda el catálogo en vivo — corre list para verla.

Dónde se guarda todo

Tu idioma y tu licencia viven en ~/.forja/config.json. La versión instalada de cada bot vive en .horizontes-bot.json, dentro de la carpeta del bot — es lo que update y doctor comparan contra el catálogo. No los borres.

No existen otros comandos

El CLI es exactamente estos cinco: init · list · install · update · doctor. No hay forja crear, forja publicar, forja panel ni forja marca. El panel no es un comando: vive en tu propio worker, en /admin. Desplegar lo hace tu agente con pnpm deploy. Y la marca (nombre del bot y del negocio) se estampa dentro de init. Para operar el bot ya instalado —reportes, mejoras, campañas— usa los Comandos del agente.