Install Forja

Forja doesn't install like a heavyweight program: it runs with a single command. You need four things —Node, a Cloudflare account, an AI agent, and an AI key— and in a couple of minutes you have your first bot ready to deploy. All of them are free to get started.

You don't need to know how to code

Your AI agent (Claude Code or Codex) types the commands for you. You talk to it in plain language —"install Forja," "configure my chatbot"— and it runs what you see on this page. If you want, in the masterclass we set it up together live.

What You Need

Four requirements. None of them cost anything to get started, and you don't have to download Forja: it lives in the catalog and pulls itself when you install it.

Requirement	What It's For
Node 18+	Brings `npx`, the command that runs Forja's installer. If you already have Node, nothing else is needed.
Cloudflare account Free	This is your own cloud: it's where the bot lives. We don't host it. The free plan is more than enough.
An AI agent	Claude Code or Codex. It's the one that writes and runs the commands for you; you just approve.
An AI key	From Anthropic, OpenAI, or xAI. This is the bot's "brain." It's saved as a Cloudflare secret — never typed into the CLI.

Cloudflare is where your bot runs: your account, your data. The agent is your pair of hands in the terminal. And the AI key is what makes the assistant think — you get it from the Anthropic, OpenAI, or xAI dashboard, and save it later as a secret (not now, not here). We'll cover that in your AI key.

One Command, No Global Install

There's nothing to install permanently. npx downloads the installer, runs it once, and discards it. The command to get started is always the same:

Terminal

# no global install needed — npx runs it and discards it
$ npx forjabot init

That command opens a wizard that walks you through it. If you'd rather, tell your agent "install Forja" and it runs it for you. Either way ends up the same: a folder with your bot inside, ready to configure.

Going to use it often? Install it globally

With npx you don't install anything — ideal to get started. But if you manage several bots and want to just type forjabot (like claude), install it once globally: npm install -g forjabot. From then on you run forjabot init, forjabot doctor, etc. without the npx.

It's not an app that stays open

forjabot is a task CLI: you run a command (install, update, diagnose), it does its thing, and it exits. The bot's day-to-day work —reports, maintenance, campaigns— you do from your agent with the agent commands, not "inside" forjabot.

What `init` Asks You

The wizard is interactive and asks you a handful of questions. You answer them one by one:

Language
Spanish or English (ES / EN). This is the wizard's language and it's saved for next time.
License
Two paths: paste your Forja + key in the format HZN-XXXX-XXXX-XXXX, or choose start free and give your email. With that we activate a free-plan license instantly.
Template
You pick your business type from the catalog —barbershop, restaurant, real estate…— and Forja pulls that template into a new folder.
A few business questions
Bot name, what you do, hours, and which brain it'll use (Anthropic, OpenAI, or xAI). With this your bot already knows who you are — without asking you for any key yet.

npx forjabot init

? Idioma / Language      English
? License                Start free (with your email)
✓ license activated · plan: free
? Pick your template     Barbershop
✓ bot downloaded to ./barberia
→ next: cd barberia · tell your agent "configure my chatbot"

When it's done, you go into the folder (cd barberia) and tell your agent "configure my chatbot": it deploys the bot to Cloudflare, connects your channels, and —only then— saves your AI key as a secret. That step lives in Quick Start.

Your AI Key Is Never Typed Into the CLI

This is the rule that matters most. During init you pick which AI provider you'll use (Anthropic, OpenAI, or xAI), but you don't paste the key. The key gets saved later, at deploy time, as a Cloudflare secret — encrypted, outside the code, and outside your terminal history.

The key goes in as a Cloudflare secret — never in the CLI

Don't type it into npx forjabot init, don't paste it into the chat with your agent, and don't leave it in a project file. Your agent saves it with wrangler secret put at publish time. That way it lives encrypted in your Cloudflare account and no one else sees it.

Where Your License Lives

Forja remembers your license and language between sessions, so you don't have to paste them in again every time. It saves them in a small file on your machine:

~/.forja/config.json

# stores your license and language — don't edit this file by hand
{
  "lang": "en",
  "key":  "HZN-XXXX-XXXX-XXXX"
}

The next time you run a Forja command, your license is already there. This file doesn't store any AI key — those live separately, as secrets in Cloudflare.

Windows, Mac, or Linux — works the same

Forja relies on Node and npx, which run the same way on all three systems. The commands in this guide are identical no matter your machine; there's no different version per operating system.