mlcl — the Molecule.dev CLI

Install

npm install -g mlcl

or run it without installing: npx mlcl <command> everywhere below works the same.

Quickstart (60 seconds)

npx mlcl create my-app --template blog --no-interactive
cd my-app
# put credentials in api/.env and app/.env (local defaults work for Postgres/SQLite)
npm run dev

You get: an Express API with routes and migrations, a React app with real screens, auth, i18n, tests, e2e specs, .env templates, CI security workflows — and an AGENTS.md that teaches any AI coding agent the project’s conventions.

Pick a starting point

Option A — a flagship template (recommended). A complete, polished app you shape: 152 flagship templates (blog, CRM, team chat, online store, project management, helpdesk, AI chatbot builder, database admin, …), each carrying its own framework and full package list — no other flags needed.

npx mlcl templates                        # browse the gallery
npx mlcl create store --template online-store --no-interactive

Option B — exactly the stack you want. Find packages by capability — not by guessing names — and compose your own stack from 1000+ @molecule/* packages. You name the capabilities; the scaffold auto-resolves default providers, transitive companions, locale bonds, and template-required packages.

npx mlcl search "send emails" --stack api

npx mlcl create my-api --type api \
  --packages @molecule/api-database-postgresql,@molecule/api-resource-user \
  --no-interactive

npx mlcl create my-app --type full-stack --framework react \
  --packages @molecule/api-database-postgresql,@molecule/app-auth \
  --no-interactive

Project types: api · app · full-stack · static · status-page · status-page-edge.

Grow and reconfigure the project

Every capability — auth, payments, email, uploads, AI — is a package wired behind a swappable bond. add --inject installs the package AND generates its bond wiring, peer deps, migrations, and routes in one step; swap changes the provider without rewriting the app; inject --dry-run previews any of it, changing nothing.

npx mlcl add @molecule/api-emails-mailgun --inject
npx mlcl add @molecule/api-logger              # dependency only, no wiring

npx mlcl swap @molecule/api-database-mysql      # PostgreSQL → MySQL
npx mlcl swap @molecule/api-emails-ses -r @molecule/api-emails-mailgun

npx mlcl inject --dry-run                       # preview, change nothing

Keep environment variables honest

env check scans your code for env reads, unions the requirements of every installed package, and tells you exactly which variables are missing, optional, or provided for you — locally, no sandbox needed. --fix writes the fixable ones. The rest of the env surface is format-preserving and script-friendly: values are masked on list, unset comments out (value preserved).

npx mlcl env check                              # what’s missing, and how to fix each
npx mlcl env list --raw
npx mlcl env set STRIPE_SECRET_KEY=sk_test_…
npx mlcl env get DATABASE_URL                   # scripts: $(mlcl env get DATABASE_URL)
npx mlcl env unset STRIPE_SECRET_KEY

npx mlcl env push --project <id>                # local .env → the project env
npx mlcl env pull --project <id>                # project env → local (secrets skipped)

Operate the project (database, staging, deploy)

The IDE’s operational surface, on your machine. Log in once (device-code flow — or --no-browser over SSH) and every platform verb works against your projects: the same deploy pipeline as the IDE’s button, sandboxes, snapshots, runtime logs with live tailing, cloud databases, domains, and per-device session revocation as the kill-switch for a stolen login.

npx mlcl db migrate          # runs the scaffolded migrate.ts
npx mlcl db reset --force    # drop/recreate + migrate (DESTRUCTIVE)
npx mlcl db console          # psql on the project DB
npx mlcl db url              # print DATABASE_URL (resolves .env)

npx mlcl stage up # per-branch staging (Docker Compose)

npx mlcl login                                # browser → Approve → done
npx mlcl deploy --project <id> --follow       # production, same pipeline as the IDE
npx mlcl logs --project <id> --stream         # runtime logs, live tail
npx mlcl sandbox exec --project <id> -- npm test
npx mlcl device revoke --all-but-current      # sign out everywhere but here

Machine-readable results

For scripts, CI, and agents: pass --json to any command and you get one clean document — create --json prints the path, type, packages, and the secrets to fill in .env, with all progress chatter suppressed. env check --json returns the full classified report.

npx mlcl search auth --json
npx mlcl env check --json | jq '.missingCount'

Using it with AI agents

Most people build through an agent — Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Windsurf, Cline, Zed, … Five ways to wire molecule in; pick any:

Zero setup — paste the block below into any agent chat: it scaffolds through the CLI and follows the conventions.

One command — npx mlcl agent init writes the conventions into the files your harness reads (AGENTS.md, Cursor rules, Claude skill, Gemini extension, Windsurf rule).

MCP tools — npx mlcl mcp install registers the molecule MCP server (package search, scaffolding, add/swap, env checks, package docs, deploys) with Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Windsurf, Kiro, Trae, Zed, Amp, Crush, Cline, VS Code, …

Hosted URL — point any MCP client at https://mcp.molecule.dev/mcp — the read tools (search / templates / docs / conventions) with no local install; works from Lovable, v0, and bolt.new connectors too.

Build this app with molecule.dev: run `npx mlcl templates` and pick the closest
flagship template (or `npx mlcl search <capability>` to find packages for a
custom stack); scaffold with `npx mlcl create <name> --template <slug>
--no-interactive --json`; then follow the scaffolded AGENTS.md conventions —
prefer @molecule/* packages over hand-rolled code, provider wiring only in
src/bonds/ (swap with `npx mlcl swap`), ClassMap styling, i18n for all
user-facing text, and each package’s README at
node_modules/@molecule/<name>/README.md for usage.

Every project mlcl create scaffolds ships an AGENTS.md — whichever agent opens the project, even one that has never heard of molecule, gets the conventions in context immediately.

Using it in an app you already have

add / inject / swap work on any project with a package.json — no re-scaffolding. Build a feature in the molecule.dev IDE, export, integrate locally; the commands look for the same conventions the scaffold writes (src/bonds/ wiring, src/index.ts package docs).

Package authors

npx mlcl init --name api-my-feature --type core --description "Interface for …"
npx mlcl init --name api-my-feature-redis --type provider --category my-feature
npx mlcl validate ./packages/api-my-feature

Package docs are generated from source: write the module-level JSDoc, commit, and the README in the package (and on npm) regenerates itself.

Telemetry & privacy

Anonymous, opt-out usage telemetry: command name, outcome, duration, versions, platform — nothing else. No paths, no project names, no argument values, no identity, no code. The only identifier is a random per-install UUID; MOLECULE_TELEMETRY=0 turns it off per run, and emission is fire-and-forget with a 5s timeout so it can never break a command.

FAQ

Where are the docs for package X? In the package: node_modules/@molecule/<name>/README.md — generated from source, always current. Online: molecule.dev/packages · llms-full.txt (everything, concatenated for LLMs).

Where do secrets go? .env files at each workspace root; the scaffold prints every key it expects. Never in code.

Why does my scaffolded project have a .npmrc with legacy-peer-deps=true? One pinned dev dependency still declares eslint ^9 peers while the toolchain pins eslint 10. The file explains itself and tells you when to delete it.

Everything in the CLI

Every command on its own line — click a line’s Copy to run it anywhere. Local project work plus the whole molecule.dev platform; mlcl --help lists every flag.

Links

GitHub · npm · Templates · Packages · Full package reference