CLI Reference · forjabot

The starting point. A wizard that takes you from zero to a bot ready to deploy, asking you one thing at a time.

Usage

npx forjabot init — or simply npx forjabot (with no command it starts the wizard).

What It Does

1) Picks a language (Spanish/English) and saves it. 2) License — three options you navigate with arrow keys ↑↓: paste your HZN-XXXX-XXXX-XXXX, "start free" (creates you a license for the Starter bot), or "Get Forja+" (explains that the license comes with the Horizontes IA community). 3) Validates the license and prints your plan. 4) Shows the catalog filtered by your plan — premium ones show up locked as 🔒 requires <plan>. 5) Downloads the bot and creates the ./<slug> folder. 6) Stamps tier, language, and business type into wrangler.toml. 7) If it's the generic bot (Starter), picks the brain (Claude / OpenAI / Grok) and asks you ~6 business questions, writing your member/config.local.ts.

Flags

Interactive with arrow-key ↑↓ menus. Accepts --key HZN-… (skips pasting the license) and --email / --name (for starting free without typing it in). Your API key is never typed here: at deploy time, it goes in as a Cloudflare secret.

# wizard — no global install needed
$ npx forjabot init

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

  Do you already have a license?
   1. Yes, paste my license
   2. No — start free (Starter bot)
  › 2

  Validating license… ✓  plan free

  Available bots:
   1. Starter Bot · generic
  Downloading Starter Bot… ✓ 84 KB · v1.0.0

  ✓ Config ready · your bot already knows your business
  ✓ Bot installed  →  ./starter

The catalog, as-is. Useful for seeing which business types exist and which are available before installing.

Usage

npx forjabot list

What It Does

Queries the live catalog and prints, for each bot, its name, its business type, its status —available or coming soon— and a short description.

Flags

None. Doesn't require a license — anyone can see the catalog.

$ npx forjabot list

  ◇ Forja  ·  AI bots for your business · by Horizontes IA

  Restaurant        restaurante          available
  Takes orders and reservations over WhatsApp, 24/7.

  Real Estate       inmobiliaria         available
  Qualifies buyers and schedules visits.

  Hospitality          hoteleria            coming soon
  Room bookings and event quotes.

The direct route: installs a business type by its slug, skipping the wizard. Ideal when you already know what you want and already have a saved license — or when you're setting up bots in bulk.

Usage

npx forjabot install <slug> · with an explicit license: npx forjabot install barberia --key HZN-XXXX-XXXX-XXXX

What It Does

Validates the license, downloads the bot, creates the ./<slug> folder, and stamps tier, language, and business type into wrangler.toml. Finishes with the steps your agent follows. Doesn't run onboarding (unlike init): your agent fills in the business config using the business type's template.

Flags

<slug> is required — if missing: "Missing bot. Use install <slug> or list." --key HZN-… is optional if you already have a saved license; if it's missing entirely: "Missing license. Use --key or run init." If the bot is premium and your plan doesn't cover it, you'll see why + how to unlock it.

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

  ◇ Forja  ·  AI bots for your business
  Downloading barberia… ✓ 84 KB · v1.0.0

  ✓ Bot installed  →  ./barberia

  What's next (your Claude Code agent does this for you):
    1.  cd barberia
    2.  tell your agent:  "configure my chatbot"  (skill /configurar-mi-chatbot)
    3.  connect your Cloudflare and your channels — the agent guides you.

Pulls the bot's new version without touching your work. Run this when we ship improvements.

Usage

npx forjabot update — from inside the bot's folder, or from its parent folder (it's auto-detected). Also npx forjabot update <folder>.

What It Does

Revalidates the license, compares your installed version against the catalog, and if there's a new one, downloads and extracts it preserving your stuff: member/*.local.ts, member/kb/, your .env/.dev.vars, and the install state. If you're already up to date, it tells you and does nothing.

Flags

[dir] optional (the bot's folder). --key HZN-… for revalidation; without a license it can't update, but your bot keeps running on its current version.

$ npx forjabot update

  ◇ Forja  ·  AI bots for your business
  Revalidating license… ✓
  Installed: v1.0.0  ·  Latest: v1.1.0
  Downloading v1.1.0… ✓ 86 KB

  ✓ Updated to v1.1.0  (your config and your KB were preserved)
  To publish the changes, tell your agent:
    "reinstall dependencies and deploy my bot"  (pnpm install && pnpm deploy)

The health checkup. When something feels off, run doctor: it checks the essentials and tells you ✓ what's fine, ⚠ what's worth a look, and ✗ what's broken, with a hint on how to fix it.

Usage

npx forjabot doctor — from inside the bot's folder (or pass it: npx forjabot doctor <folder>).

What It Does

Six checks: 1) finds the bot's folder and its install marker; 2) key files — wrangler.toml, package.json, node_modules, member/config.local.ts; 3) reads the BOT_NAME, the BOT_NICHE, and the panel URL from wrangler.toml; 4) your version vs. the catalog; 5) validates the license; 6) pings <panel>/admin/overview — a 200 or a 401 means the bot responds online.

Flags

[dir] optional. --key HZN-… for the license check (if not, it warns it's missing but runs the rest). Closes with a count of "things to check."

$ npx forjabot doctor

  ◇ Forja  ·  AI bots for your business
  ✓ Bot found in ./barberia
  ✓ Installed: barberia v1.1.0
  ✓ wrangler.toml present
  ✓ package.json present
  ✓ Dependencies installed
  ✓ Business configured (member/config.local.ts)
  ✓ Business name: Barbershop El Filo
  ✓ Business type (niche): barberia
  ✓ You're on the latest version
  ✓ Active license (pro)
  ✓ The bot responds online (https://mi-bot.workers.dev)

  All good. Your Bot is healthy.

Connects your terminal to your forjabots.com account — just like wrangler login or gh auth login. The browser opens on its own (sign in with Google or GitHub) and the terminal detects when you're done. Works the same on Windows, Mac, and Linux; if the browser doesn't open, the CLI prints the URL to open by hand.

Usage

npx forjabot login — once per machine. The credentials are stored in ~/.forja/credentials.json (yours only, restricted permissions).

What It Unlocks

Your panel at app.forjabots.com: your bots with live metrics, and automatic pair at deploy time.

Flags

--no-browser doesn't try to open the browser (just prints the URL). --force signs in again even if there's already an active session.

$ npx forjabot login

  Opening the browser to sign in (Google or GitHub)…
  If it doesn't open: https://app.forjabots.com/api/cli/auth?...

  ✓ connected as tu@correo.com
  Next: deploy your bot and run  forjabot pair

Links a bot that's already deployed to your app.forjabots.com panel. Registers the bot under your account and configures the Worker's secrets on its own (via wrangler) — you don't copy tokens by hand. It's idempotent: running it again doesn't duplicate or break anything.

Usage

npx forjabot pair — from inside the bot's folder, after the deploy. Requires a session (login first).

What It Does

1) verifies the bot responds; 2) registers it to your account; 3) sets CONTROL_PLANE_TOKEN and CONTROL_PLANE_URL on the Worker; 4) confirms the connection. When it's done, your bot shows up in your panel with its metrics.

Flags

--url the Worker's URL if wrangler.toml doesn't have it yet. --name to rename it in the panel. If your bot is from before, run forjabot update first (needs the version with the panel API).

$ npx forjabot pair

  Verifying the bot… ✓
  Registering to your account… ✓
  Configuring secrets… ✓

  ✓ bot connected — see it at https://app.forjabots.com/dashboard

whoami tells you which account the terminal is connected with (or if there's no session). logout deletes the local credentials from this machine.