modular_cli_sdk library

SDK for building modular CLIs with Dart.

Import package:modular_cli_sdk/modular_cli_sdk.dart to use:

  • ModularCli — entry point that orchestrates modules and global flags
  • ModuleBuilder — per-module route registration
  • Query — a unit that reads and answers, and changes nothing
  • Command — a unit that changes something, as an ordered list of steps that say what they would do before anything runs
  • Input / Output — typed DTOs for I/O
  • CliParam — a route's declared parameter contract (help + enforcement)
  • CommandException — structured error with code, message, and exit code
  • ExitCode — semantic exit code constants
  • CliOutput / JsonCliOutput / TextCliOutput — output formatting
  • Approver / PlanSink — the two decisions a host keeps: how approval is taken, and where a plan is filed

Step, Preview, Outcome and Execution come from preview_executor and are re-exported here, so a command author imports one package.

PreviewExecutor is deliberately not among them. The engine publishes it because the engine's consumer is a framework, and running steps is what a framework does with it. This library's consumer is a command author, and for them the same class is a way out of the arrangement: a command that could reach the executor could run steps with no plan shown, no approval taken, and no check that what happened is what was announced.

Narrowing the surface for a different audience is what this re-export is for. Tests are the one place the executor is legitimately needed, and they get it — along with the lifecycle already assembled — from package:modular_cli_sdk/testing.dart.

Classes

ChangeFlags
The three flags every Command carries, parsed and validated together.
CliOutput
Contract for writing structured data to the terminal.
CliParam
One declared parameter of a command.
Command<I extends Input, O extends Output>
A unit of work that changes something, as an ordered list of steps.
CommandCatalog
Every command the CLI has registered, as declared at registration.
CommandContract
The declared contract of one registered command.
ConsoleApprover
The default Approver: prints the plan and reads one line from stdin.
DeclinedOutput
The answer when --apply asked and the answer was no — or when there was nobody to ask.
Discrepancy
A step that did something other than what it said it would.
Execution
What happened when a list of steps was performed.
ExitCode
Semantic exit codes for CLI commands.
HelpRenderer
Renders the command catalog as the plain, aligned text a user reads.
Input
Inbound DTO that a Command receives.
JsonCliOutput
Formats all output as JSON — one JSON value per write call.
ModularCli
Entry point for a modular CLI application.
ModuleBuilder
Registers Querys and Commands within a named module.
Outcome
What a Step actually did, reported after it ran.
Output
Outbound DTO returned by a Command after execution.
PlanDocument
What a command would do, rendered once and used everywhere.
PlanOutput
The answer to --plan: what would change, and where the plan was filed.
Preview
What a Step says it would do, stated before anything runs.
Query<I extends Input, O extends Output>
A unit of work that reads and answers, and changes nothing.
Step
One unit of work: something that can say what it would do, and then do it.
StepContext
What a step can see of the steps that ran before it.
StepFailure
A step that threw instead of reporting an outcome.
TextCliOutput
Formats output as human-readable plain text.

Enums

ChangeMode
Which of the two things the caller asked for.
CliParamKind
How a parameter is written on the command line.
CliParamType
The type a raw argument string is coerced into.
CommandKind
Which of the two kinds of unit a route was registered as.

Properties

globalOptions → List<CliParam>
The options the framework handles for every command, whatever it declares.
final

Typedefs

Approver = Future<bool> Function(String renderedPlan)
Asks a human whether the shown plan may be carried out.
PlanSink = String? Function(PlanDocument plan)
Where a plan is filed, when the host files it.

Exceptions / Errors

CommandException
Structured error thrown during Command execution.
NoApproverAvailable
Thrown when --apply needs an approval and no terminal can give one.