Cast.Cli 1.0.15

Cast

A command-line tool for scaffolding PlantUML sequence diagrams.

Cast turns command-line participants and messages into a PlantUML sequence diagram starter.

Requirements

• .NET SDK 8.0 or later (the tool targets net8.0 and runs on the .NET 8 runtime and later)

Install From NuGet

Install the latest published Cast.Cli tool package from NuGet:

dotnet tool install --global Cast.Cli

Or pin the currently published latest version:

dotnet tool install --global Cast.Cli --version 1.0.8

After installation, run Cast with the cast command:

cast --help
cast generate -p actor:User -p OS -m "User -> OS : place order"
cast ng --service projects/api/src/lib/services/dashboard.service.ts

Update an existing global install:

dotnet tool update --global Cast.Cli

For a repository-local tool install:

dotnet new tool-manifest
dotnet tool install Cast.Cli
dotnet tool run cast -- --help

Build And Test

git clone https://github.com/QuinntyneBrown/Cast.git
cd Cast
dotnet build Cast.sln
dotnet test Cast.sln

Run From Source

Use dotnet run --project src/Cast.Cli -- followed by a Cast command:

dotnet run --project src/Cast.Cli -- generate `
  -p actor:User `
  -p "OS:Order Service" `
  -p database:DB `
  -m "User -> OS : place order" `
  -m "OS -> DB : persist" `
  --title "Checkout" `
  --autonumber `
  --stdout

By default the diagram is written to cast.puml in the current directory; pass --stdout to print it to standard output instead, or -o <file> to choose another path.

Output:

@startuml
' Scaffolded by cast
!pragma teoz true
skinparam defaultFontSize 10
title Checkout
autonumber

actor User
box #PHYSICAL
  box #AZURE
    participant "Order Service" as OS
    database DB
  end box
end box

User -> OS : place order
OS -> DB : persist
@enduml

Every diagram runs the teoz engine with a default font size of 10, and the non-actor participants are wrapped in a double nested box — outer #PHYSICAL, inner #AZURE by default. Actors always stay outside the boxes. Override the colors with --outer-box-color and --inner-box-color (a missing # prefix is added automatically).

Commands

generate

Scaffolds a PlantUML sequence diagram from participants and optional messages.

Participant examples:

User
actor:Customer
database:DB:Main Database

Message examples:

User -> OS : place order
OS --> User : confirmation

When participants are supplied without messages, Cast generates a placeholder request/response flow unless --no-sample is used.

kinds

Lists supported participant kind prefixes:

dotnet run --project src/Cast.Cli -- kinds

Supported kinds are participant, actor, boundary, control, entity, database, collections, and queue.

ng

Inspects an Angular .ts file and emits a PlantUML sequence diagram explaining how Angular's dependency injector supplies that consumer's dependencies. The consumer can be any construct that uses inject(...) — an @Injectable service, an @Component/@Directive/@Pipe, a functional interceptor/guard/resolver, or an exported function (a factory or initializer). It recognises both idiomatic DI shapes: the inject(X) function (in class fields, functional providers, and function declarations) and classic constructor injection (including @Inject(TOKEN) and @Optional()). Symbols written in SCREAMING_CASE or injected via @Inject are treated as InjectionTokens; PascalCase symbols such as HttpClient or Router are treated as classes the injector constructs. Parsing is done in pure .NET — no Node runtime is required.

By default the diagram is written next to the source as a .puml file; pass --stdout to print it to standard output instead.

dotnet run --project src/Cast.Cli -- ng `
  --service projects/api/src/lib/services/dashboard.service.ts

For an @Injectable({ providedIn: 'root' }) service that injects HttpClient and the API_BASE_URL token, Cast produces a narrated diagram:

@startuml
' Generated by cast ng
!pragma teoz true
skinparam defaultFontSize 10
title How Angular injects dependencies into DashboardService

actor "App\n(a component or service\nthat needs DashboardService)" as App
box #PHYSICAL
  box #AZURE
    participant "Angular Injector\n(the built-in DI container)" as DI
    participant "DashboardService\n(the consumer)" as Consumer
    participant "HttpClient\n(injected service)" as D1
    participant "API_BASE_URL\n(injected token)" as D2
  end box
end box

App -> DI : Give me a DashboardService
note over DI
  Angular inspects DashboardService and sees it needs 2 dependencies:
  - HttpClient (service)
  - API_BASE_URL (token)
end note
DI -> D1 : resolve HttpClient
DI -> D2 : look up API_BASE_URL
DI -> Consumer : create DashboardService
DI --> App : a ready-to-use DashboardService\n(dependencies already wired inside)
@enduml

A functional provider (an interceptor, guard, or resolver) is rendered with the "pull" narrative it actually follows — the function runs inside an injection context and calls inject(...) for each dependency it needs.

style

Applies the default styling to existing PlantUML sequence diagrams, in place. Pass a single .puml file, or a folder — every .puml file beneath it (recursively) is checked. Each file that is a sequence diagram gains whichever pieces of the house style it is missing:

• !pragma teoz true directly after @startuml;
• skinparam defaultFontSize 10 (placed after any !theme so the size still wins);
• the double nested box around the explicitly declared non-actor participants (actors are hoisted above the box and stay outside it).

cast style docs/diagrams                      # restyle every sequence .puml under docs/diagrams
cast style flow.puml --outer-box-color Gray   # single file, custom outer box color

The command is conservative and idempotent: re-running it changes nothing, non-sequence diagrams (class, component, state, activity, …) are left byte-for-byte untouched, files that already have a teoz pragma, a defaultFontSize setting, or any box keep what they have, and when participant declarations are interleaved with messages or comments the box step backs off rather than reorder the diagram (the other rules still apply). Files containing multiple @startuml blocks are skipped. Line endings (CRLF/LF), trailing-newline-ness, and the file's encoding (UTF-8 with or without BOM, UTF-16/32) are all preserved.

Exit Codes

Project Layout

License

Distributed under the MIT License. See LICENSE for details.