Commands — moonctl

One binary, mctl, and a verb for each thing it can write. Every generator takes a file and writes beside it unless --dir says otherwise.

The surface

Command	Reads	Writes
`mctl gen api <file.api>`	a spec	a moonapi project tree — or one file with `--flat`
`mctl gen rpc <file.proto>`	a proto	a moonrpc project tree: messages, codecs, handler table, client
`mctl gen gql <file.api>`	a spec	a moongql tree — the types as `#gql.type`, the routes as root fields
`mctl gen model <file.api>`	a spec	a moonorm tree — the tables as `#orm` annotations, plus migrations
`mctl gen crud <file.sql>`	DDL	the same tree, plus the typed CRUD helpers
`mctl gen doc <file.api>`	a spec	an OpenAPI document and a Swagger page
`mctl gen agent <file.api>`	a spec	a moonkoog agent skeleton
`mctl api format <file.api>`	a spec	the canonical text, on stdout, or in place with `--write`
`mctl api validate <file.api>`	a spec	the findings, then a count — nothing on disk
`mctl api doc <file.api>`	a spec	`<stem>_api.md` — routes, groups, types, constraints
`mctl api ts\|dart\|kt\|java <file.api>`	a spec	one typed client per route, in that language
`mctl migrate <file.api>`	a spec	`<service>_migrate.sql` — one table per type block
`mctl model mongo <file.api>`	a spec	`<service>_mongo.mbt` — documents and repositories
`mctl model cache <file.api>`	a spec	`<service>_cache.mbt` — cache-aside CRUD
`mctl model mysql datasource <dsn>`	a live MySQL schema	`mysql_model.mbt`
`mctl model pg datasource <dsn>`	a live PostgreSQL schema	`pg_model.mbt`
`mctl gateway <file.proto>`	a proto, and `<stem>.routes` if present	`<stem>_gateway.mbt` — an HTTP front door
`mctl quickstart <name>`	—	a service: scaffold, generate, build
`mctl api new <name>`	—	an empty moonapi project
`mctl rpc new <name>`	—	an empty moonrpc project
`mctl gql new <name>`	—	an empty moongql project
`mctl model new <name>`	—	an empty data-layer project
`mctl docker <name>`	—	`Dockerfile` and `.dockerignore`
`mctl kube <name>`	—	`deploy/deployment.yaml` and `deploy/service.yaml`
`mctl plugin <exe> <file.api>`	a spec, a plugin	whatever the plugin returns, inside the output directory

Housekeeping

Command	What it does
`mctl env`	print the configuration in force and where each value came from
`mctl config list\|get\|set\|path\|migrate`	read and write the config file
`mctl template list\|show [name]`	the bundled template catalogue
`mctl completion <shell>`	a completion script for bash, zsh, fish or powershell
`mctl upgrade [version]`	move the `moonbitstack` pins in `moon.mod` to a release
`mctl bug [title]`	a bug report, pre-filled with the environment
`mctl help`	the command table

Flags

Flag	What it does
`--dir <path>`	write the tree under `path` instead of here
`--flat`	one `.mbt` file instead of a project tree
`--style <template>`	how generated names are spelled: `gozero`, `goZero`, `go_zero`, …
`--write`	rewrite the input file in place (`api format`)
`--home <path>`	use this template home instead of the bundled library
`--remote <url>`	read the template library from a git remote
`--branch <name>`	the branch of `--remote`, `main` by default

The three library flags choose where gen api reads its templates from: a directory laid out like the catalogue for --home, a checkout of --remote at --branch for a shared one. A file's path and its text are both rendered over the parsed spec, so {{.service}}.mbt becomes the entry point of the service the spec describes. --home wins when both are given, and the home in the configuration file is used when neither is; see Configuration.

The template catalogue

terminal

$ mctl template list

Template	Spec	What it produces
`api-service`	api	a moonapi service: routes, handlers, logic, config and a Dockerfile
`api-flat`	api	the same routes and types in one .mbt file, for a small service
`rpc-service`	proto	a moonrpc service: messages, codecs, handler table and a client
`gql-service`	api	a moongql schema and resolver over the spec's types
`mcp-server`	api	an MCP server whose tools are the spec's annotated handlers
`model-mysql`	ddl	moonorm models and CRUD for a MySQL schema, reflected or from DDL
`model-postgres`	ddl	moonorm models and CRUD for a PostgreSQL schema
`model-mongo`	api	document models over a Mongo collection, with a typed collection port
`gateway`	proto	an HTTP gateway that routes to a moonrpc client

The command prints the same rows as a Markdown table.

mctl template show api-service prints one entry; mctl template init <dir> writes a starter library into a directory to edit — a moon.mod, a moon.pkg and one file per service that generates, compiles and answers every route with 200 until the bodies are filled in.

terminal

$ mctl template init my-templates
$ mctl gen api greet.api --home my-templates --dir out
mctl: wrote 4 file(s) from greet.api through the template library at my-templates

The library behind it

Every command is a thin layer over an exported function, so a build script can do the same thing without a subprocess:

moon.pkg

import {
  "moonbitstack/moonctl",
}

Function	What it returns
`parse`, `parse_all`	a `Spec` from one file, or from a file and the sources it imports
`generate`, `generate_tree`	a scaffold as text, or as a tree of files
`render_template_dir`, `render_template_file`	a template library's files, rendered over a spec
`format`, `validate`, `validate_files`	the canonical text, and the findings for a spec
`generate_client`, `client_file`	a typed client in one of four languages
`generate_markdown`, `generate_migrations`	the Markdown reference, the migration SQL
`generate_mongo`, `generate_cached`	documents and repositories, the cache-aside layer
`generate_gateway`, `default_routes`	the gateway, and the routes a proto implies
`generate_grpc`, `parse_proto`	the moonrpc service, and the proto tree it came from
`generate_model`, `generate_crud`	models and the CRUD layer, from a spec or from DDL

The library is pure logic — a string in, a string out — so it runs on all four MoonBit targets, and a build step, a test or a browser page can call it.