systhema create

Scaffold a new Systhema project from one of the bundled templates.

systhema create my-app                       # interactive
systhema create my-app --template next       # pick template up front
systhema create my-app --template payload --yes --no-install
systhema create --path . --force             # scaffold into the current folder

Scaffolding into an existing folderLink to this section

Research, notes, or a brief often land in a folder before the project does. --path <dir> says where the scaffold goes (. is the current directory) and --force allows a target that isn't empty:

cd ~/projects/acme-site
systhema create --path . --force --template payload

--force overwrites colliding files (README.md, package.json, …) and leaves everything else in place. The colliding files are listed before the confirmation prompt, so you can bail; under --yes the two flags together are the confirmation. Without --force, a non-empty target still exits with an error.

The package name is derived from the target directory's name (sanitized for npm). Pass the positional argument alongside --path to set it explicitly: systhema create acme-web --path ..

An existing .git directory in the target is left alone — no second "initial commit" over your history.

OptionsLink to this section

Flag behaviorLink to this section

• -p, --path <dir> — directory to scaffold into, relative or absolute (e.g. .). Defaults to [name]. When given, the positional [name] becomes the package.json name instead of the directory.

• --skills / --no-skills — install Systhema agent skills into the project (default: prompt, recommended). With --yes, skills are installed unless --no-skills is passed.

• --skill-agents <agents> — comma-separated agent targets for the skills, e.g. claude,agents. Interactive checkbox if omitted; --yes defaults to the cross-agent .agents/ location.

• --ai <provider> — (payload) AI assistant single text provider: none (default, disables the module), openai, anthropic, google, groq, or openai-compatible (self-hosted endpoint; requires --ai-base-url). Generates an env-gated single-provider src/payload/ai.ts that reads the conventional SYSTHEMA_AI_* variables at runtime and forwards them into the ai plugin option (the package itself reads no env vars).

• (payload) A Custom multi-model setup (build your own models[] with optional locked upgrade teasers, a packageName label, and a credit budget — all your own values) is offered interactively in the create questionnaire; there's no flag for it. Keys for each provider are read from the conventional per-provider env vars (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY). The CLI ships no prescribed plan presets — pricing/quota structure is the licensee's own business logic.

• --analytics <provider> — (payload) Analytics dashboard provider: none (default), ga4, plausible, umami, matomo, or fathom. Generates an env-gated src/payload/analytics.ts that reads the conventional SYSTHEMA_ANALYTICS_* variables at runtime and forwards them into the analytics plugin option (the package itself reads no env vars). Blank credentials are written as fill-later .env lines — analytics disables itself with a startup warning until they're filled in.

• --analytics-site-id <id> — (payload) the provider's site identifier: GA4 property id, Plausible domain, Umami website id, Matomo idSite, or Fathom site id (payload; env: SYSTHEMA_ANALYTICS_SITE_ID).

• (payload) GA4's service-account fields (SYSTHEMA_ANALYTICS_GA_CLIENT_EMAIL / SYSTHEMA_ANALYTICS_GA_PRIVATE_KEY) and Umami self-hosted login (SYSTHEMA_ANALYTICS_USERNAME / SYSTHEMA_ANALYTICS_PASSWORD) are env-only — no flags; create writes blank .env lines and points at them.

• --cloudflare <mode> — (payload) Cloudflare integration auth method: none (default), token, or key (env: SYSTHEMA_CLOUDFLARE_MODE). Generates an env-gated src/payload/cloudflare.ts that reads CLOUDFLARE_API_TOKEN / CLOUDFLARE_API_KEY + CLOUDFLARE_EMAIL / CLOUDFLARE_ZONE_ID and forwards them into the cloudflare plugin option (the package itself reads no env vars). Blank credentials are written as fill-later .env lines.

• --locales <codes|none> — (payload) frontend locales: comma-separated BCP 47 codes (e.g. en,hu), or none (default) for a single language. Writes the locale contract into systhema.config.ts and — once dependencies are installed — runs the locale migration (systhema-core sync --migrate-locales) that generates the localized route seams.

• (payload) credential flags — every secret can be passed non-interactively, so one command wires a fully-configured project: --email-from, --resend-key, --sendgrid-key, --smtp-host / --smtp-port / --smtp-user / --smtp-pass, --recaptcha-site-key / --recaptcha-secret-key, --turnstile-site-key / --turnstile-secret-key, --ai-key, --analytics-site-id / --analytics-api-key / --analytics-host, --cloudflare-api-token / --cloudflare-api-key / --cloudflare-email / --cloudflare-zone-id. Each also reads its project env var when the flag is omitted (see below).

• --pm, --package-manager <pm> — pnpm, npm, or yarn. A pnpm project gets packageManager pinned to a pnpm 10 release. pnpm 11 and later switch to the pinned version, and so does a build host that honours the field. Without the pin they would ignore the pnpm field of package.json, which holds the project's security overrides, build allowlist and Lexical patch. When create installs, it runs pnpm with manage-package-manager-versions on, so pnpm 9.7 and later switch too. An older pnpm cannot switch, so the project pins that pnpm instead, to match the lockfile it writes. npm and yarn projects get no pin.

• -y, --yes — skip every prompt and use defaults (payload: SQLite + Resend, Forms and Redirects on, no maps/captcha/AI/analytics/Cloudflare, single language). Those are the template's own defaults, so --yes produces exactly what the template ships. Any credential not supplied via a flag or env var is left blank to fill in later.

Non-interactive credential resolutionLink to this section

Each credential resolves in this order: flag → environment variable → interactive prompt (only without --yes) → blank. The env var is the same name the generated project reads, so exporting it both configures the scaffold and is what the running app uses:

A fully non-interactive, fully-wired example:

systhema create acme --template payload --yes \
  --db postgres --db-url "$DATABASE_URI" \
  --email resend --resend-key "$RESEND_API_KEY" \
  --captcha turnstile --turnstile-site-key "$TS_SITE" --turnstile-secret-key "$TS_SECRET" \
  --maps-key "$MAPS_KEY"

What the scaffolder doesLink to this section

• Copies the template, restoring .gitignore and .npmrc (renamed to neutral names in the published bundle so npm pack doesn't strip them).
• Rewrites the project's package.json name.
• Pins every @systhemaui/* dep to the running CLI's exact version. Stable CLIs use a caret (e.g. ^1.6.0); prerelease CLIs (-internal.<sha>, -canary.<n>, -rc.<n>, etc.) use an exact pin so the project tests against the same code as the CLI that scaffolded it.
• (Payload) Walks a short setup questionnaire (database adapter, email provider, Google Maps, form captcha, Forms, Redirects, AI assistant, analytics dashboard, Cloudflare, locales) and wires each choice:
  • Swaps the matching @payloadcms/* adapter dependency — so only the packages you actually picked are installed (no Postgres driver for SQLite, no email package for None, SendGrid adds nodemailer-sendgrid).
  • (Re)generates src/payload/database.ts, src/payload/email.ts, src/payload/forms.ts, src/payload/redirects.ts, src/payload/ai.ts, src/payload/analytics.ts and src/payload/cloudflare.ts for the chosen adapters and module toggles. For AI: None, a single provider (env-driven), or Custom (build your own model list — models, an optional credit budget, and an optional plan label, all your own values). Single-provider scaffolds keep the env-gated module; a custom list emits an explicit models[] config with keys referenced from per-provider env vars. The CLI prescribes no plans — pricing/quota structure is the licensee's own business logic. For analytics: None or one of the five providers — the env-gated module activates on SYSTHEMA_ANALYTICS_PROVIDER and blank credentials stay as fill-later .env lines. For Cloudflare: None, API token (recommended), or Global API key — the env-gated module activates on CLOUDFLARE_API_TOKEN or CLOUDFLARE_API_KEY + CLOUDFLARE_EMAIL, with an optional zone ID (auto-resolved from the site URL when left blank).
  • Writes a .env with auto-generated PAYLOAD_SECRET and SYSTHEMA_API_SECRET.
  • Fills in credentials you supply; comments out integrations you skip (config feature-flags on env vars, so absent keys disable features).
  • For a multilingual choice: writes the locale contract into systhema.config.ts, then — after the dependency install — runs <pm> exec systhema-core sync --migrate-locales to generate the localized route seams. If the install was skipped (or failed), the migration becomes a printed Next step instead.
  • Result: the default SQLite setup runs with pnpm dev immediately, no external service needed.
• (If skills enabled) installs the selected Systhema agent skills into .{agent}/skills/ (e.g. .claude/skills/, .agents/skills/) — the same skills systhema skills install manages. This runs before git init, so the skills are tracked in the initial commit.
• (If --git) initializes a git repository on main and creates the initial commit.
• (If --install) runs the chosen package manager.

After it's done you'll have a project that's already wired up with Systhema, Tailwind v4, and the chosen framework.