cmd

Microbus ships a set of command-line tools that generate artifacts consumed by the framework, your deployment pipeline, or human reviewers. Most read your microservices’ Go source code and emit files (manifests, credentials, diagrams); geninit scaffolds a new project, and genopenapispecs transforms an external OpenAPI document. They all sit outside the normal build flow.

geninit

Scaffolds the boilerplate of a new Microbus project in a directory: the main package, the config and env files, the agent and editor files, and a freshly generated Ed25519 token-signing key.

go run github.com/microbus-io/fabric/cmd/geninit -dir .

It is idempotent: existing files are left as they are, so it is safe to re-run on an established project. The init-project skill invokes it.

genservice

Reads a microservice’s *api/definition.go — the hand-written, typed single source of truth for its API — and generates the five derived artifacts that must stay in sync with it:

• *api/client.go — the Client, MulticastClient, MulticastTrigger, Hook, Executor, and (for services that declare workflows) Subgraph stubs, with one method per feature.
• intermediate.go — the subscription wiring, marshaling, config/metric/ticker registration, and the ToDo interface.
• mock.go — a Mock type with one MockXxx(handler) setter per ToDo method. Unmocked methods return zero values for all named results (including nil for error).
• mock_test.go — the per-microservice mock smoke test. Hand-written TestXxx_Mock blocks are no longer needed.
• manifest.yaml — the catalog of everything the microservice exposes.

go run github.com/microbus-io/fabric/cmd/genservice <service-dir>

Run this after editing definition.go to add, modify, or remove a feature; the framework’s housekeeping skill invokes it automatically. Because every artifact is regenerated from one declarative spec, the files can never drift apart — each generated file carries a DO NOT EDIT header, so you change definition.go and regenerate rather than touching the generated files. The tool reads and writes a single microservice and does not touch others, so an API change does not cascade.

For a task or workflow, each field of the In and Out structs is read from and written to the flow’s state as its own field, by its JSON name, and the generated task wrapper writes each declared output with its own flow.Set after the task body returns. So genservice rejects an In or Out field the state cannot carry as written: an unexported field or one tagged json:"-", an embedded struct, the ,string JSON option, and a JSON name ending in ! or +.

A -check flag regenerates in memory and compares against what is on disk, exiting non-zero if anything is stale, so CI can guard against a forgotten regeneration. Upstream services consume the generated mock in their integration tests.

genworkflowmmd

Generates a Mermaid flowchart for every workflow graph a microservice defines. It finds each graph endpoint in the microservice’s source, a method of the form func (svc *Service) Foo(ctx context.Context) (graph *workflow.Graph, err error), builds the graph by calling it, and writes the diagram to <METHOD>.mmd in the microservice’s directory.

go run github.com/microbus-io/fabric/cmd/genworkflowmmd --path <service-dir>

The diagram is the engine’s own rendering of the graph, workflow.NewGraphRenderer(g).Render(), so it shows exactly what the foreman runs. The housekeeping skill runs it after a workflow changes. It builds and runs a short program under the microservice’s tmp/ directory and deletes it afterwards; --keep-tmp keeps it for debugging.

gencreds

Reads a microservice bundle’s source code, derives per-microservice NATS ACL rule sets via static analysis of the code, and signs them into <hostname>_nats.creds files using an operator’s account NKey.

go run github.com/microbus-io/fabric/cmd/gencreds \
  --bundle main/main.go \
  --signing-key /path/to/account.nk \
  --plane prod \
  --out ./deploy/creds/

For each microservice in the bundle, gencreds walks the source code to determine the exact NATS subjects the microservice publishes to and subscribes from, then signs one user JWT per microservice carrying the corresponding ACL allow-list. The output is one .creds file per microservice, ready to ship with the deployment binary. Operational Security covers the full deploy workflow.

Key flags:

• --bundle <main.go> parses app.Add(...) calls to discover the microservices in the application.
• --manifests <dir,dir,...> is an alternative to --bundle for non-standard bundle compositions.
• --plane <name> ties the issued .creds to a specific plane and must match the deployment’s MICROBUS_PLANE. Defaults to microbus, which matches the framework’s local-development default.
• --signing-key <path> points at the operator’s account NKey seed file.
• --expiration <duration> sets an exp claim on each signed .creds. Default 0 (no expiration).
• --persist-user-nkeys <dir> keeps user NKeys stable across runs instead of rotating them per deploy.

gentopology

Reads the bundle’s manifests and renders a Mermaid topology diagram showing the call graph between microservices.

go run github.com/microbus-io/fabric/cmd/gentopology \
  --bundle main/main.go \
  --out ./topology.mmd

Useful for code review, architecture documentation, and onboarding. The diagram captures who calls whom and on which port tier (safe vs danger).

genopenapispecs

Normalizes an external OpenAPI (Swagger) document into the openapispecs.json intermediate consumed by the OpenAPI import skill. It is a pure offline filter — it reads the document on stdin, writes the normalized specs on stdout, and never touches the network.

go run github.com/microbus-io/fabric/cmd/genopenapispecs -base-url 'https://api.example.com/v1' \
  < openapi.src > myservice/openapispecs.json

JSON and YAML documents are both accepted. The tool captures only what the scaffolding skills need — functions, web endpoints, type definitions, the remote base URL, and the authentication scheme. -base-url is optional and defaults to the document’s first servers URL; set it explicitly when the document declares a relative server. The resulting openapispecs.json is committed to source control as the durable record of the remote API; re-running the import skill reads it without re-fetching.

Shared Schema

The cmd/schema package is a library shared by these tools. It defines the in-memory shape of manifest.yaml. It is not a CLI tool and is not invoked directly.