create-iai

Instalador dos starters SaaS da IAI Cursos (Next.js + Convex + Clerk): do zero a um app rodando localmente, com backend em tempo real e autenticação.

npm create iai@latest
# ou
npx create-iai

Rodando sem argumentos, o assistente pergunta todas as decisões no próprio terminal — template, stack de addons (Sentry, Stripe, Storybook…), shadcn/ui, storage, GitHub, deploy — mostra um resumo para conferir e só então executa tudo de uma vez (o padrão dos scaffolders profissionais, como create-next-app). Flags pré-respondem perguntas; --yes não pergunta nada.

Quem preferir montar a instalação clicando pode usar npx create-iai --ui: sobe um servidor local e abre uma página que monta o comando pronto para copiar e rodar no terminal (opt-in — o terminal é o caminho padrão).

Renomeada em v0.3.0. Até a v0.2.0 este pacote se chamava create-live1 — o nome ficou estreito quando o catálogo passou a ter mais de um template. O pacote antigo está deprecated apontando para cá; quem já tinha login não precisa refazer (o token em ~/.create-live1/ é migrado sozinho).

Acesso: exclusivo para alunos pagos

A CLI só instala para alunos com assinatura ativa na comunidade. No primeiro uso ela abre o navegador para você autorizar o computador (OAuth 2.0 Device Flow); o template privado é baixado pela própria comunidade — você não precisa de acesso aos repositórios GitHub. O acesso é revalidado a cada uso (reembolso/expiração cortam na hora).

npx create-iai --login    # autentica este computador
npx create-iai --whoami   # status da assinatura
npx create-iai --logout   # revoga + remove o token local

Detalhes e setup (backend + envs): docs/cli-paid-gate.md.

How the template is distributed

The CLI lives on npm (tiny: just bin/ + src/); the template lives on GitHub and is cloned at install time. This split is intentional:

• Updating the template (new pages, tables, components) requires no npm release — the next install picks it up automatically.
• The npm package stays small and fast to download via npx.
• Private templates work too (the clone goes through the authenticated gh).

Point TEMPLATE.repo / TEMPLATE.gitUrl in src/config.js at another repository to change the default, or use --template owner/repo per-install.

The same split applies to the harness (the agent-workflow scaffold that is now the base of every install): it lives in the private repo elberrd/harness, is cloned through the authenticated gh at install time, and has a local dev checkout under harness/ (gitignored, own remote — like live1/). Config lives in HARNESS in src/config.js.

Two install modes

Right after the project name/folder, the installer asks what to install:

• Só o harness (--mode harness / --harness-only) — merges just the agent-workflow harness into the folder and touches nothing else. No template, no Convex/Clerk, no addons, no deploy. Ideal to plug the harness into a project that already exists.
• Harness + template (--mode full, the default under --yes) — clones the Next.js + Convex + Clerk starter and runs the whole stack setup; you pick the addons and everything below.

The harness is always installed in both modes — the choice is only whether the template comes along.

What it does (in order)

The steps below are the full flow. In harness-only mode the installer runs just steps 1–2, the mode choice, a lightweight CLI check (git + gh, no Vercel), the harness merge, and the finish summary — every template-specific step is skipped.

1. Claude Code — checks it's installed (and, best-effort, logged in). If missing it stops with install + login instructions. This is checked first.
2. Project prompts — asks for a project name and target folder.
3. Install mode — choose só o harness or harness + template (see above).
4. Addons — pick the stack. The template ships "maximal" (unit tests, Sentry, PostHog, CSP, rate limiting, Resend, Stripe/Clerk Billing, Storybook, Knip, semantic-release… all implemented and wired); you choose a preset (padrão, mínimo, saas, completo) or customize group by group, and everything you did NOT pick is removed from the generated code (files, package.json deps/scripts and live1:addon:* marker blocks), guided by the template's template.addons.json manifest. The choice is recorded in the project's live1.config.json.
5. CLIs — ensures Git, GitHub CLI, and Vercel CLI are installed (auto-installs cross-platform via Homebrew / apt / dnf / winget / choco / npm), then pauses for you to sign in to gh and vercel if you aren't already. (Harness-only mode checks just git + gh — no Vercel.)
6. Clone + install — clones the template into your folder, resets git history, sets the package name, applies the addon choice, makes an initial commit (diffable baseline), runs npm install and normalizes formatting. convex/_generated is refreshed by the Convex step below, so codegen always matches the reduced convex/ folder.
7. Dependency refresh (optional) — keep the template's pinned versions (default), npm update within the declared ranges (safe), or bump everything to latest (npm-check-updates -u, includes new Next.js majors — may need manual fixes).
8. MCPs — registers the template's Playwright and Convex MCP servers via claude mcp add / claude mcp add-json.
9. shadcn/ui (optional) — apply a custom design preset from ui.shadcn.com/create (paste the "Get Code" command or just the preset code), and pick which block to install — sidebar-07 (the classic default), another curated block, any custom block name(s), or none.
10. Convex — logs you in (browser), creates a new cloud project and writes CONVEX_DEPLOYMENT / NEXT_PUBLIC_CONVEX_URL (and derives NEXT_PUBLIC_CONVEX_SITE_URL).
11. Clerk — creates (or reuses) a Clerk app, pulls the publishable + secret keys (normalizing the publishable key to NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY), creates the required convex JWT template, derives the issuer domain, writes .env.local, and sets CLERK_JWT_ISSUER_DOMAIN on the Convex deployment.
12. Convex — publish functions — with the Clerk issuer in place, pushes the functions and regenerates convex/_generated for the addon-reduced schema.
13. Webhook (optional) — offers to wire the Clerk → Convex user-sync webhook: mints the Svix dashboard link, shows the exact …convex.site/clerk-users-webhook URL to paste, then captures the signing secret and runs convex env set CLERK_WEBHOOK_SECRET. Fully skippable (the endpoint + secret are dashboard-only in Clerk, so this step is semi-automatic).
14. Storage (optional) — Cloudflare R2 for the Documentos page, or Convex built-in storage. Picking R2:
    • auto-installs the official Cloudflare agent skills (cloudflare + wrangler, from cloudflare/skills) into the project via the skills.sh CLI, recorded in skills-lock.json — same mechanism as the template's pre-installed Convex/Clerk skills;
    • launches a wrangler assistant: checks the Cloudflare CLI (offers npm install -g wrangler if missing), runs wrangler login, auto-detects the Account ID, creates/reuses the bucket and applies the browser-upload CORS policy. Only the S3 API token (R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY) is still pasted from the dashboard — wrangler can't mint those. Everything is skippable; declining wrangler falls back to the manual copy-paste flow.
15. Service keys — activate the chosen integrations — one step, two entry points, all optional (everything degrades gracefully without a key):
    • From the web UI: keys pasted in --ui land in a local file (~/.create-iai/keys/<slug>.env, mode 600) that the generated command references via --keys — secrets never appear in the command line. The installer applies each var where the template actually reads it (Convex deployment env vs .env.local).
    • In the terminal: for each service (Stripe test-mode, Asaas, Resend, Sentry, PostHog, Arcjet) the step offers a ready-made AI prompt — paste it into a browser-automation extension (e.g. Claude in Chrome) and it fetches/creates the keys in the dashboard, returning them as KEY=value lines the installer recognizes.
    • Bonus: with the payment key in hand the installer creates the Stripe/Asaas webhooks via API (pointing at <deployment>.convex.site/...-webhook) and captures the signing secret — no dashboard clicking. SITE_URL is set automatically for dev.
16. Integrations — official skills & CLIs — for each chosen addon with official tooling, installs the agent skills into the project (Stripe: docs.stripe.com, Sentry: getsentry/sentry-for-ai, Resend: resend/resend-skills — via skills.sh, recorded in skills-lock.json) and offers to install + sign in to the official CLI (stripe login, sentry-cli login, resend login), printing the dashboard links where the keys live. Asaas has no official CLI/skills — a project skill ships in the template instead.
17. Git + GitHub (optional) — commits the configured project and offers to create a GitHub repository (asks private/public and confirms the name, defaulting to the app slug) and push via gh repo create.
18. Vercel deploy (optional) — quick production deploy: vercel link, copies the runtime env vars from .env.local to the project, then vercel deploy --prod. Uses the dev Convex/Clerk credentials (great for demos) and prints the checklist for a real production setup (CONVEX_DEPLOY_KEY + npx convex deploy --cmd 'npm run build' + Clerk production instance).
19. Harness — the base scaffold, always installed (in full mode it's the last step, after GitHub/Vercel; in harness-only mode it runs right after the CLI check). Merges the agent-workflow scaffold from the private repo elberrd/harness into the project: slash commands (/start, /dev, /sv, /test-ui, /team), 9 specialist agents and skills for Claude Code and Cursor, plus the ai-docs/ structure (PRD, maps, tasks). The merge adapts to whatever is already there instead of clobbering it: existing files are never overwritten, the harness README.md lands as HARNESS.md, and its AGENTS.md is appended to the project's AGENTS.md between <!-- harness-start/end --> markers. Makes its own commit (initializing a git repo first if the folder has none) and pushes when a remote was created in step 17.
20. Finish — prints a summary (URLs included), an integration status report (what the keys step activated vs what's still pending), activation pointers only for what's NOT done yet, offers to delete the used keys file, and can start the dev server (full mode only).

Every step shows a [i/n] progress header — n reflects the chosen mode (fewer steps in harness-only mode) — and each run writes a debug log to ~/.create-iai/logs/ (the path is printed if something fails).

Full internals manual: DOCS.md.

Non-interactive usage & flags

npx create-iai [nome] [opções]

--name <nome>            Project name (same as the 1st positional arg)
--dir <caminho>          Target folder ("." for the current folder)
--mode <valor>           harness (only the harness) | full (harness + template)
--harness-only           Shortcut for --mode harness (skips the template)
--template <owner/repo>  Alternative GitHub template

--update-deps <modo>     none | safe | latest
--shadcn-preset <val>    shadcn/create preset (code or full command)
--shadcn-block <blocos>  Comma-separated block(s), or "none"
--skip-shadcn            Skip shadcn customization

Addons (whatever you don't pick is REMOVED from the generated project):
--preset <nome>          minimo | padrao | saas | completo
--addons <lista>         commitlint,knip,analyzer,release,storybook | none | all
--observability <lista>  sentry,logging,checkly | none
--analytics <valor>      none | posthog | vercel-analytics
--security <lista>       csp,rate-limit,arcjet | none
--emails <valor>         none | resend
--payments <valor>       none | stripe | asaas | clerk-billing
--tenancy <valor>        single (Live 1, default) | multi (Live 2: Clerk
                         Organizations, per-org data & billing, /admin with
                         org management; JWT template gets org claims)

--keys <arquivo>         .env-style file with service keys (Stripe, Asaas,
                         Resend, Sentry, PostHog, Arcjet, R2). The web UI
                         (--ui) writes one to ~/.create-iai/keys/ when you
                         paste keys in the browser — local-only, mode 600.

--skip-webhook           Skip the Clerk → Convex webhook
--storage <valor>        convex | r2 (file storage backend)
--skip-storage           Skip storage choice (stays on Convex Storage)

--repo <nome>            GitHub repository name (default: app slug)
--public | --private     Repository visibility (default: private)
--push | --no-push       Create the GitHub repo and push (or not)
--skip-github            Skip commit + GitHub entirely

--deploy | --no-deploy   Deploy to Vercel at the end (or not)

--no-harness             (full mode only) install the template WITHOUT the harness
--skip-harness           Same as --no-harness

--ui, --web              Open the local web UI to assemble the install command
--port <n>               Web UI server port (default: 4599)

-y, --yes                Never prompt; safe defaults everywhere (full mode)
-v, --version            Print version
-h, --help               Print help

The harness is now the base — always installed. --no-harness / --skip-harness only apply in full mode (template without the harness); in harness-only mode they're ignored with a warning (nothing would be left).

--yes semantics: full mode, default block installed, no shadcn preset, the padrão addon preset (commitlint, knip, analyzer, sentry, csp, rate-limit — override with --preset/group flags), webhook/storage/deploy skipped, harness installed, commit made but no remote repo created (creating repos is irreversible, so it stays opt-in via --push). Use --harness-only (or --mode harness) to install just the harness non-interactively.

Flag precedence for addons: group flags (--addons, --analytics, …) override --preset, which overrides the default (padrao).

Examples:

npx create-iai meu-app --yes --push --private
npx create-iai meu-app --harness-only            # just the harness, this folder
npx create-iai --dir . --harness-only --yes
npx create-iai meu-app --update-deps latest --shadcn-block dashboard-01 --deploy
npx create-iai meu-saas --preset saas --payments stripe --analytics posthog
npx create-iai meu-mvp --preset minimo --observability sentry

Requirements

• Node.js ≥ 20.9 (checked at startup)
• Claude Code installed and logged in (the installer will not install it for you — it only detects it and tells you how).
• Internet access + a Convex account and a Clerk account (both free; the installer walks you through login).

Design notes

• Built with @clack/prompts + execa (pure-JS, ESM). It deliberately avoids node-pty: every child CLI is driven either by official non-interactive flags (the deterministic "accept the defaults" path) or, for genuine browser logins, by passing your terminal straight through. No native builds, no screen-scraping.
• Idempotent where it can be: re-running skips already-installed tools, already-authenticated CLIs, and an existing convex JWT template.
• If a fatal error happens in a folder the installer itself created, it offers to delete it so the next run starts clean.

Local development

cd create-iai   # this repo
npm install
node bin/create-iai.js        # run it directly
npm test                        # unit tests (node:test)
npm run lint                    # eslint

The installer clones elberrd/live1 (configured in src/config.js). Point TEMPLATE.repo / TEMPLATE.gitUrl at another template if you fork it.

Publishing

npm publish from this folder. Because the package is named create-iai, both npm create iai and npx create-iai resolve to it.

A conta npm usa passkey/WebAuthn e exige OTP no publish, então o npm publish precisa de um terminal de verdade (o fluxo web imprime "Press ENTER to open in the browser" — com stdin redirecionado ele morre em EOTP).