[I-03] CLI — System.CommandLine: run, resume, compare, benchmark subcommands

[techbuzzz]

Overview

Version: v10.4.0 Intelligence & DX
Effort: M · 3–5 days
Branch: feature/i03-cli
Dependencies: I-01 (Tool Use), I-02 (Debate Diff)

Add a first-class CLI experience to Delibera using System.CommandLine, enabling developers and CI pipelines to run debates, resume checkpoints, compare results, and run benchmarks — all from the terminal.

---

Project Structure

src/
└── Delibera.Cli/
    ├── Commands/
    │   ├── RunCommand.cs
    │   ├── ResumeCommand.cs
    │   ├── CompareCommand.cs
    │   └── BenchmarkCommand.cs
    ├── Program.cs
    └── Delibera.Cli.csproj

---

Commands

delibera run

Run a debate from a JSON scenario file or inline arguments.

# From scenario file
delibera run --scenario ./my-scenario.json --output ./results/

# Inline
delibera run \
  --question "Should we migrate to microservices?" \
  --members Architect,TechLead,DevOps \
  --strategy Critique \
  --chairman gpt-4o \
  --rounds 3 \
  --output ./results/

# Stream rounds to stdout
delibera run --scenario ./scenario.json --stream

Options:

Flag	Type	Default	Description
--scenario	file path	—	JSON scenario file
--question	string	—	Debate question (inline mode)
--members	string[]	—	Comma-separated roles
--strategy	string	Standard	Standard / Critique / Consensus
--chairman	string	—	Model name for chairman
--rounds	int	3	Max rounds
--output	dir path	./output	Save DebateResult JSON + Markdown
--stream	flag	false	Print rounds live to stdout
--label	string	—	Tag for this run

---

delibera resume

Resume a paused or checkpointed debate.

delibera resume --debate-id debate-abc123 --server http://localhost:5000
delibera resume --checkpoint ./results/debate-abc123.checkpoint.json

Options:

Flag	Type	Description
--debate-id	string	ID of the debate to resume (requires --server)
--checkpoint	file path	Local checkpoint file
--server	URL	Delibera.Server base URL

---

delibera compare

Compare two debate result files side-by-side (uses I-02 DebateResult.Diff).

delibera compare ./results/run-a.json ./results/run-b.json
delibera compare ./results/run-a.json ./results/run-b.json --output diff-report.md

Options:

Flag	Type	Description
positional[0]	file path	Left debate result JSON
positional[1]	file path	Right debate result JSON
--output	file path	Save diff Markdown to file
--html	flag	Output as HTML instead of Markdown

Prints DebateDiff.ToMarkdown() to stdout by default.

---

delibera benchmark

Run the same question against N configurations and produce a comparison matrix.

delibera benchmark \
  --question "Monolith vs microservices for our use case" \
  --configs ./bench/config-a.json ./bench/config-b.json ./bench/config-c.json \
  --output ./benchmark-results/

Options:

Flag	Type	Description
--question	string	Shared question for all runs
--configs	file path[]	Scenario JSON files to run
--output	dir path	Save all results + comparison matrix
--parallel	flag	Run configs in parallel

Outputs: individual DebateResult files + a benchmark-matrix.md with side-by-side verdicts, token counts, durations.

---

Output Artifacts

For every run / resume / benchmark:

• {debate-id}.result.json — full DebateResult serialized
• {debate-id}.result.md — DebateResult.ToMarkdown()
• {debate-id}.checkpoint.json — checkpoint for resume (if paused)

---

Delibera.Cli.csproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <AssemblyName>delibera</AssemblyName>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="System.CommandLine" Version="2.*-*" />
    <PackageReference Include="Spectre.Console" Version="0.*" />
  </ItemGroup>
  <ItemGroup>
    <ProjectReference Include="../Delibera.Core/Delibera.Core.csproj" />
  </ItemGroup>
</Project>

Use Spectre.Console for rich terminal output: progress bars during rounds, colored verdict output, diff tables.

---

Tasks

• Create Delibera.Cli project, add to Delibera.slnx
• Implement RunCommand with all options
• Implement ResumeCommand (local checkpoint + server mode)
• Implement CompareCommand (delegates to DebateResult.Diff from I-02)
• Implement BenchmarkCommand with parallel support
• Add Spectre.Console progress display for streaming rounds
• Add colored verdict output (risk level → color)
• Save output artifacts (JSON + Markdown) after each run
• Add delibera --version and delibera --help
• Publish as dotnet tool (dotnet tool install -g Delibera.Cli)
• GitHub Actions: publish CLI tool to NuGet on tag
• Docs: docs/cli.md with full command reference
• Integration tests: run each command against a mock debate

---

Acceptance Criteria

• delibera run --scenario ./scenario.json completes and saves artifacts
• delibera run --stream prints rounds live to stdout
• delibera resume --checkpoint ./file.checkpoint.json resumes correctly
• delibera compare a.json b.json prints DebateDiff Markdown to stdout
• delibera benchmark produces benchmark-matrix.md
• dotnet tool install -g Delibera.Cli installs and runs delibera --help
• All commands exit with code 0 on success, 1 on error
• Spectre.Console progress visible during --stream mode

Labels

enhancement, v10.4.0, CLI