Developer tools

The Wyrd CLI

Generate contracts and diagrams, then turn an instance history into a replay test.

Run it from the repository

Wyrd.Tool is a .NET tool with the command name wyrd. The examples below run the current source directly from the repository root with the .NET 10 SDK, so they do not depend on a published tool package.

dotnet run --project src/Wyrd.Tool -- --help
dotnet run --project src/Wyrd.Tool -- asyncapi --help
dotnet run --project src/Wyrd.Tool -- diagram --help

Export integration contracts

asyncapi reads the reviewed contracts.wyrd.txt snapshot and writes an AsyncAPI 3.0 YAML document. It needs no running application or compiled domain assembly. Message names, versions, and payload schemas come from the snapshot.

dotnet run --project src/Wyrd.Tool -- asyncapi \
  --contracts samples/Shop/contracts.wyrd.txt \
  --title "Shop integration events" \
  --version 0.3.0 \
  --output samples/Shop/asyncapi.yaml

--contracts defaults to contracts.wyrd.txt. --title defaults to the snapshot folder name and --version defaults to 0.0.0. Use these options to describe the API you are exporting.

Draw the process model

diagram loads a compiled assembly and discovers public static fields and properties that expose Wyrd processes. It writes a Markdown document containing Mermaid diagrams, including steps, retries, awaits, timeouts, and compensation.

dotnet build samples/Shop

dotnet run --project src/Wyrd.Tool -- diagram \
  --assembly samples/Shop/bin/Debug/net10.0/Shop.dll \
  --output docs/shop-processes.md

Use it in your workflow

Both commands accept --output or -o. Omit it to write the generated document to standard output; diagnostics go to standard error. Invalid input returns a nonzero exit code, so a CI job can fail immediately.

Generate the files during CI or commit them alongside the model for review. AsyncAPI describes the public integration boundary; Mermaid describes the compiled business process. They are generated documentation, not a replacement for contract compatibility checks.

Replay a recorded instance

Export shop.HistoryOf(process, key).ToJson() to a file. The replay command prints its timeline; --as-testwrites an xUnit test embedding the history and invoking Urd. A history comes from any host: the in-memory runtime, a durable one (HistoryOfAsync), or a history archive. It replays the same way.

dotnet run --project src/Wyrd.Tool -- replay A-1.history.json

dotnet run --project src/Wyrd.Tool -- replay A-1.history.json --as-test \
  --runtime Shop.ShopModule.CreateRuntime \
  --process Shop.Fulfillment.Processes.OrderFulfillment

See the API reference for InstanceHistory, Urd and ReplayReport.