What the wizard does, step by step
The wizard's step sequence in order — what each step asks, what it writes, when it is skipped, and which ones reach your Chatfuel account.
Every command-line mistake is answered before the first question, so a mistyped --logo or a
--supabase-project paired with --supabase-create costs you nothing but the typing.
The sequence
| Step | What it asks | Answered non-interactively by | What it writes |
|---|---|---|---|
| Welcome | Nothing. The banner animates only for a person on a TTY. | — | — |
| Flag checks | Nothing. The auth, brand, agent and admin flags are judged here, before anything is spent. | — | — |
| Preflight | Nothing. Checks Node against the floor of 20.18.1, resolves the package manager, and records which agent CLIs are on PATH. | — | — |
| Mode | New app, or embed into the project you are standing in. | --embed. Plain --yes stays standalone. | — |
| Modules | Which modules you want, then whether to add the ones your selection recommends. | --modules. Under --yes, every ready module except auth and admin. | — |
| Agent | Which coding agent finishes the setup — asked only if both are installed. | --agent | — |
| Skills target | Into the project, or into your home directory. | Nothing; --yes takes the project. | — |
| Token | Your Chatfuel token, masked, then checked against the API. A rejected token is re-asked, up to three times. | CHATFUEL_TOKEN in the environment. | Held in memory until the scaffold writes .env. |
| Workspace | Which Chatfuel workspace this deployment starts in. Taken silently when the account owns one. | --workspace | VITE_CHATFUEL_WORKSPACE_ID, and CHATFUEL_WORKSPACE_ID as well when auth is installed. |
| Trial | Nothing, if the workspace is already subscribed. Otherwise it prints a checkout link, opens it, and waits — offering a way out every five minutes. | --yes prints the link and moves on without a plan. | — |
| Brand | What the app is called, and a path to a logo file. Standalone only. | --app-name, --logo | Both land in files the scaffold step then writes. |
| Auth setup | Only with the auth module: access token or manual, then the project, then the deployed origin. | --supabase-token / SUPABASE_ACCESS_TOKEN with --supabase-project or --supabase-create, or --supabase-url with --supabase-anon-key. | VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY and SUPABASE_PROJECT_REF. |
| Admin setup | Only with the admin module: whether to set your own password. | --admin-password, ADMIN_PASSWORD, else a generated one. | ADMIN_PASSWORD. |
| Scaffold | Where to create the app. | --dir | The app: the template copied, unselected module subtrees deleted, the module registry regenerated, the nav table filtered, ui, api-client and the proxy vendored as sources, the proxy imports rewritten, the package renamed, .env at mode 0600, the skills, and an install. |
| Embed | Nothing beyond a confirm to install the dependencies. Replaces the scaffold step when the mode is embed. | Nothing; --yes declines the install. | src/chatfuel/ in the host, the auth SQL under supabase/chatfuel/, the skills, and only the .env keys the host does not already define. |
| Deploy | Whether to deploy to Vercel now, and what to call the project. | Not offered under --yes. | .vercel/project.json, by way of the app's own deploy script. |
| GitHub | Whether to put the app on GitHub, under what name, and public or private. Then, if a Vercel project exists, whether a push should redeploy. | Not offered under --yes. | A git repository, a first commit, an origin. |
| Handoff | Whether to launch the agent in the new app. | Nothing; --yes writes the files and launches nothing. | CLAUDE.md or AGENTS.md, and the setup checklist at the path that agent reads it from. In embed mode the instructions file gets a marked section appended rather than being overwritten. |
| Outro | Nothing. Prints the next steps, the trial, the sign-in facts and any generated admin password. | — | — |
| Launch | Whether to start the dev server and open the browser. Standalone only, and never after a handoff. | Not offered under --yes. | — |
The order is not alphabetical and not arbitrary. The agent is settled before anything is copied,
because Claude Code and Codex read skills from different directories. The trial comes before
anything is written, because a workspace with no plan produces an app that answers nothing. Deploy
and GitHub come before the handoff, because both need the terminal — the Vercel login and gh auth login are conversations — and a handoff can give the terminal to an agent session.
What reaches an account
| Step | What it does to your account | Stopped by --dry-run |
|---|---|---|
| Token | Reads the current user, to check the token. | No — it creates nothing. |
| Workspace | Creates a Chatfuel workspace, but only when the account owns none. | No. |
| Trial | Opens a Stripe checkout session on the workspace. | Yes. |
| Auth setup | Creates a Supabase project, runs the migrations, patches the auth config and the recovery email template. | Yes — each is printed as the call it would have made. |
| Deploy | Creates a Vercel project and a deployment. With the auth module on the access-token path it then adds the deployed origin to the Supabase redirect allowlist; on the manual path it prints the line for you to add by hand. | Yes — the step is skipped entirely. |
| GitHub | Creates a repository under your account and pushes to it. | Yes — the step is skipped entirely. |
Everything else is local. --dry-run does not stop the scaffold: the app is written to disk and
its dependencies installed either way.
A workspace with no subscription has no AI. The bot answers nothing, and the finished app reads as a broken scaffold — which is why the trial step blocks rather than warns, and why a run that ends without a plan is told again in the closing summary.
The CLI
Every command and flag of npx @chatfuel/wizard, what each one falls back to when you omit it, and the two things --yes refuses to do.
The environment the wizard reads and writes
The variables the wizard itself reads, the .env and .env.example it leaves behind, what --embed appends instead of overwriting, and the guard that refuses to persist a token.