@moduflow/cli

Create, validate, pack, login, and submit Moduflow Module Federation remotes (moduflow bin).

Setup

# Global install (recommended — avoids pnpm dlx cache surprises)
# External / default: npm. Monorepo / pnpm users: pnpm add -g is fine.
npm install -g @moduflow/cli@latest
# or: pnpm add -g @moduflow/cli@latest

moduflow --version
moduflow create my-app --port 6530

# From this monorepo
pnpm --filter @moduflow/cli build
node packages/moduflow/cli/bin/moduflow.mjs --help

Upgrade after releases: npm install -g @moduflow/cli@latest (not npm update -g), then moduflow --version.

Contributor SDK (@moduflow/*)

| Package | Role | |---------|------| | @moduflow/contracts | Host/remote types | | @moduflow/remote-sdk | Runtime hooks + host provider | | @moduflow/ui | Path A UI | | @moduflow/remote-dev | Canonical Mini Host / MSW | | @moduflow/cli | This CLI |

Commands

moduflow login / logout / whoami

Create a token in the Host Contributor Hub (copy Base URL + secret once), then:

moduflow login --base-url http://localhost:3000 --token <token>
moduflow whoami   # prints baseUrl + workspaceId (not the token)
moduflow logout

Credentials: ~/.config/moduflow/credentials.json (mode 0600). submit / promote / release / solution * use Bearer from this store — no --cookie.

moduflow prompt

Prints official AI authoring docs embedded in this CLI (raw Markdown, no ANSI). Works with any AI coding agent:

moduflow prompt plan       # Agentic orchestration (Discovery → VERIFY → WOW)
moduflow prompt host       # Host bridge APIs + platform provides catalog
moduflow prompt platform   # Colocated contracts, permissions/ACL, SWR, secrets, ship path
moduflow prompt remote     # Domain RemoteSpec + foundation few-shot
moduflow prompt ui         # @moduflow/ui component catalog
moduflow prompt solution   # SolutionSpec + from-spec
moduflow prompt workflow   # Workflow JSON cookbook + lint

Example: Run moduflow prompt plan for your product NLP and follow it end-to-end (agent runs create + validate scaffold + Phase 3; escalate only after 3 failed VERIFY attempts).

moduflow create --from-spec

Domain RemoteSpec → runnable dual-surface-crud foundation (split List/Table/Form/Board + AGENTS.md + UI catalog + host-bridge). Presentation is polished by an AI agent — not encoded in YAML.

moduflow create --from-spec ./booking.remote-spec.yaml --path ./apps
moduflow validate scaffold ./booking-remote --spec ./booking.remote-spec.yaml

Fixtures: fixtures/booking.remote-spec.json / .yaml. Legacy UI-rich specs (ui.entities, ui.metrics, …) are rejected with a yellow/orange message.

create always writes .gitignore (npm does not pack template .gitignore, same as .npmrc).

moduflow validate scaffold

Phase-3 readiness gate for agents: required AI context files (AGENTS.md, moduflow-ui-reference.md, moduflow-host-bridge.md; moduflow-platform.md recommended), at least one *List.tsx, Zod-valid RemoteSpec (--spec or discover *.remote-spec.*), plus a UX/anatomy lint over src/**/*.tsx — ux.native_dialog, ux.toast_api, ux.surface_banner are errors; ux.empty_outside_card, ux.metric_card_wall, ux.row_action_buttons are warnings with fix hints. Exit 0 = ready for WOW polish; exit 1 = fix YAML / scaffold and retry (max 3 in the plan template).

moduflow validate scaffold ./my-app-remote --spec ./my-app.remote-spec.yaml

Host-safety checks remain moduflow validate [dir] (separate command).

moduflow solution validate|publish|from-spec

IaC for Solution Bundles (JSON manifest). See SOLUTION_BUNDLES.md.

moduflow solution from-spec ./suite.solution-spec.json -o ./suite.json
moduflow solution validate ./suite.json --strict-graphs
moduflow solution validate ./my-bundle.json
moduflow solution validate ./my-bundle.json --host   # Host dep allow-list
moduflow solution publish ./my-bundle.json --private # Agency toolkit
moduflow solution publish ./my-bundle.json --private --acknowledge-hardcodes
moduflow solution publish ./my-bundle.json           # public (MARKETPLACE_REMOTE_ENABLED)

moduflow create <name>

Scaffolds the Path A Vite template (templates/path-a-vite): Module Federation ./App + sample widget, colocated contract stubs (including Vault requiresSecrets / allowedDomains), i18n/LocaleProvider, and Mini Host boot via @moduflow/remote-dev.

• Scripts: pnpm local = Mini Host; pnpm dev:host = preview MF for Host / Contributor Dev; pnpm dev = Vite MF serve (local experiments only).
• Same three scripts under a Moduflow monorepo apps/ path (ports rewritten to match --port).

There is no separate moduflow local command — use the package scripts above. See the scaffolded remote README.md for Mini Host and Secrets Egress notes. Contributor guides ship in the scaffold docs/ folder (offline copy of Host /docs/contributor, kept in lockstep by pnpm --filter @moduflow/cli sync-docs).

# External (own repo)
moduflow create crm-lite --port 6530

# Inside monorepo apps/ (same scripts; ports aligned)
moduflow create crm-lite --path apps/remotes/external --port 6530

Outside monorepo, workspace:* is rewritten to semver ranges baked into this CLI release (and peers are aligned to the same line). External scaffolds get pnpm-workspace.yaml (+ .npmrc written by create) so pnpm install stays local even under a parent monorepo; under apps/ those files are removed so the remote joins the monorepo workspace.

moduflow validate / pack / submit / promote / release

Run moduflow --help for flags. Ship / Solution checklists also live under the scaffolded docs/ (and Host /docs/contributor).