Microforge Starter

An interactive, dependency-free CLI that generates a production-oriented, Docker-first orchestration monorepo. Capable of harboring frameworks: NestJS, FastAPI, or Spring Boot. Each service is initialized as its own Git repository and tracked by the root through a Git submodule. Services can use PostgreSQL, MongoDB, or no database.

Every project also includes a mandatory microforge-shared repository containing canonical JSON Schemas plus native TypeScript, Python, and Java adapters, so all stacks share HTTP envelopes, request headers, pagination metadata, and domain-event contracts without coupling non-Node services to NestJS.

Install

Install globally from npm, then start the wizard:

npm install --global @microforge/cli
microforge new

Or run it once without keeping a global installation:

npx @microforge/cli new

Microforge requires Node.js 18+ and Python 3.11+. The npm package contains the complete generator, so uv, pipx, and a repository clone are not required.

Install the agent skill

After installing the CLI, install its bundled microforge skill into Codex:

microforge skill install

For a one-off npm invocation, run npx @microforge/cli skill install. The default destination is $CODEX_HOME/skills/microforge (or ~/.codex/skills/microforge); pass --destination <skills-directory> for another skill-compatible agent, and --force to update an older copy. Start a new agent task, then ask it to “use the microforge skill to create my microservice project.” The skill guides you through the actual interactive CLI and verifies the generated workspace.

The wizard walks through project details, communication style, gateway and broker, then every service. At the end it can install local dependencies and start the selected infrastructure.

Choose REST for HTTP-only services, event-driven for broker consumers with health/readiness HTTP endpoints, or hybrid for both. HTTP projects can use Kong, Nginx, or no gateway. Event-driven projects have no gateway. RabbitMQ and Kafka work across all three frameworks; BullMQ uses Redis and is available for NestJS-only projects. The wizard shows the framework-native validation and persistence defaults while you configure each service.

| Framework | Validation | PostgreSQL | MongoDB | | ----------- | ----------------------- | --------------- | ------------------- | | NestJS | class-validator + Joi | TypeORM | Mongoose | | FastAPI | Pydantic | SQLAlchemy | Motor | | Spring Boot | Jakarta Bean Validation | Spring Data JPA | Spring Data MongoDB |

Python alternatives

From a local clone, you can still install Microforge with uv tool install . or pipx install ..

Non-interactive use

microforge new commerce \
  --service users:nestjs:postgres \
  --service catalog:fastapi:mongodb \
  --service billing:springboot:postgres \
  --root-repo [email protected]:acme/commerce.git \
  --shared-repo [email protected]:acme/microforge-shared.git \
  --git-base [email protected]:acme \
  --communication hybrid \
  --gateway kong \
  --broker rabbitmq \
  --output .

Service syntax is name:framework:database[:port].

framework: nestjs | fastapi | springboot
database:  postgres | mongodb | none
communication: rest | events | hybrid
gateway:       kong | nginx | none
broker:        rabbitmq | kafka | bullmq | none

REST requires --broker none; event-driven and hybrid require a broker. BullMQ supports NestJS services only. Use --repo [email protected]:other/users.git to override a single derived service URL. Add --install to install local dependencies or --start to start the selected infrastructure and application stack. Microforge configures remotes but never creates or pushes remote repositories.

What is generated

your-project/
├── services/
│   ├── microforge-shared/ # contracts + TypeScript/Python/Java adapters
│   ├── users/             # independent NestJS Git repository
│   ├── catalog/           # independent FastAPI Git repository
│   └── billing/           # independent Spring Boot Git repository
├── docker-compose.yml
├── docker-compose.infra.yml
├── kong/kong.yml        # or nginx/nginx.conf, or neither
├── config/shared.env.example
├── secrets/.env.<service>.example
├── .gitmodules
├── Makefile
├── AGENTS.md
└── .agents/skills/microservice-starter/SKILL.md

The root Git repository tracks orchestration files and submodule gitlinks, not service source code. The selected gateway routes /<service>/*; without one, services expose their own ports. Shared non-secret settings live under config/, ignored runtime secrets live under secrets/, and each stateful service owns its database container and credentials.

Each generated service includes validated configuration, JWT protection, request correlation, structured logging, standard success/error envelopes, OpenAPI docs, liveness/readiness probes, sample item handling over the selected communication style, database and broker integration when selected, tests, CI, and a non-root multi-stage container where appropriate. Event-driven services omit item HTTP routes but retain health/readiness endpoints.

Develop this generator

python -m unittest discover -s tests -v
python -m microforge.cli --help