mlcl: the Molecule.dev CLI

Install

npm install -g mlcl

or run it without installing: prefix any command below with npx and it works the same.

Quickstart (60 seconds)

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 app you shape: 100+ 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.

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

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

mlcl search "send emails" --stack api

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

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.

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

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

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

Environment variables

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; it runs 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).

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

mlcl env push --project <id>                # local .env → the project env
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 (the kill-switch for a stolen login).

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

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

mlcl login                                # browser → Approve → done
mlcl deploy --project <id> --follow       # production, same pipeline as the IDE
mlcl logs --project <id> --stream         # runtime logs, live tail
mlcl sandbox exec --project <id> -- npm test
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.

mlcl search auth --json
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, …). Four 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: mlcl agent init writes the conventions into the files your harness reads (AGENTS.md, Cursor rules, Claude skill, Gemini extension, Windsurf rule).

MCP tools: 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, …

No install: builder and chat platforms connect by URL alone (next section).

Build this app with molecule.dev: run `mlcl templates` and pick the closest
flagship template (or `mlcl search <capability>` to find packages for a
custom stack); scaffold with `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 `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, so whichever agent opens the project gets the conventions in context immediately.

Builders & chat platforms: no install

Lovable, v0, bolt.new, Base44 and other platforms with a remote-MCP (custom MCP server) field connect by URL, no CLI and no account:

https://mcp.molecule.dev/mcp

The platform’s own agent gains the read side of the catalog: search 1,000+ @molecule/* packages, browse the flagship templates, read any package’s generated usage docs, and load the molecule conventions as a resource, so it composes real packages instead of hand-rolling them. Read-only by design: the endpoint never sees your code or credentials, and it is rate-limited per client.

Writing packages, scaffolding, env and deploys stay with the local CLI (mcp install above); every @molecule/* package is a plain npm install.

Vibe-coded to production

Exported a prototype from Lovable, v0, bolt.new, Replit? mlcl turns it into a production app without a rewrite: agent init writes the conventions into the repo, then add --inject replaces the stubs with production packages for auth, transactional email, and payments; each arrives wired (bonds, migrations, routes) and stays swappable with one command.

mlcl agent init
mlcl add @molecule/app-auth --inject
mlcl add @molecule/api-emails-mailgun --inject
mlcl add @molecule/api-payments-stripe --inject
mlcl swap @molecule/api-emails-ses -r @molecule/api-emails-mailgun

The full walkthrough (export, conventions, packages, and the build-in-the-IDE-first variant) is in the repo: docs/FROM-VIBECODING.md.

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

mlcl init --name api-my-feature --type core --description "Interface for …"
mlcl init --name api-my-feature-redis --type provider --category my-feature
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. 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