Commands
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 schema and resolvers |
mctl gen model <file.api> | a spec | <stem>_model.mbt — models and migrations |
mctl gen crud <file.sql> | DDL | <stem>_model.mbt — models and typed CRUD |
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 reach the configuration and the env report, but the
generator still reads the bundled catalogue; see
Configuration.
The template catalogue
$ 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 writes the library into a directory to edit, and is not implemented yet.
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 |
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.