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); genopenapispecs instead transforms an external OpenAPI document. They all sit outside the normal build flow.

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.

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.

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.