Introduce --simple-output CLI argument

[christianhelle]

This pull request adds a new --simple-output CLI option to Refitter, enabling plain-text console output without colors, ASCII art, tables, or emojis. This is especially useful for integration with IDEs and build tools that do not support rich terminal formatting. The implementation includes updates to documentation, command-line help, and the CLI's output logic to support this new mode across all relevant user interactions.

Key changes include:

New Feature: Simple Output Mode

• Added the --simple-output CLI option to generate plain, unformatted console output, bypassing Spectre.Console features for improved compatibility with IDEs and limited consoles. This affects banners, progress indicators, file summaries, error handling, and support messages. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11]

Documentation Updates

• Updated README.md and CLI documentation to describe the --simple-output option, its use cases, and sample output. Also added the option to the command-line help and examples. [1] [2] [3] [4] [5]

Developer and Contribution Guide Improvements

• Enhanced .github/copilot-instructions.md to reflect the new CLI option, update the workflow for adding options, and list recent CLI options for easier onboarding. Also documented new and existing CI/CD workflows. [1] [2]

Internal Refactoring

• Updated method signatures and logic to pass the new settings parameter where needed (e.g., validation and warning display), ensuring correct output mode is respected throughout the codebase. [1] [2]

Overall, these changes improve the usability of the Refitter CLI in diverse environments and clarify the process for contributing new options.

This fixes #750

Example output with the --simple-output flag

Refitter v1.0.0.0 (local build)
OpenAPI to Refit Interface Generator

Support key: +/lp/mx

Validating OpenAPI specification...
OpenAPI Analysis Results
Path Items: 13 - API endpoints defined
Operations: 19 - HTTP operations available
Parameters: 17 - Input parameters defined
Request Bodies: 9 - Request body schemas
Responses: 19 - Response schemas defined
Links: 0 - Operation links
Callbacks: 0 - Callback definitions
Schemas: 70 - Data schemas defined

Generating multiple files...
Generated Output Files
File                           Size       Lines     
-------------------------------------------------------
ISwaggerPetstoreDirect.cs      16,2 KB    379       
Contracts.cs                   13,9 KB    354       
DependencyInjection.cs         1,2 KB     40        
-------------------------------------------------------
Total (3 files)                31,4 KB    773       

Generation completed successfully!
Duration: 00:00.3649
Performance: Multi-file generation

Support
Enjoying Refitter? Consider supporting the project!

Sponsor: https://github.com/sponsors/christianhelle
Buy me a coffee: https://www.buymeacoffee.com/christianhelle

Found an issue? https://github.com/christianhelle/refitter/issues

Configuration Warnings
Warning: Deprecated Setting
Description: The 'usePolly' property is deprecated. Use 'transientErrorHandler: Polly' instead

Summary by CodeRabbit

• New Features

  • Added Simple Output mode with a new --simple-output CLI flag for plain-text output (no colors, ASCII art, emojis, or tables).
  • Mode-aware validation and generation: clearer plain text summaries for single/multiple files, statistics, errors, and success messages.
  • Simplified text-only support/donation banner when not suppressed.

• Documentation

  • Updated README and CLI docs to include --simple-output usage and examples.
  • Expanded UI/console output guidance and OpenAPI testing recommendations.
  • Cataloged recent CLI options and refreshed repo-wide guidance.
  • Added notes on CI/CD workflows and build timing insights.

[coderabbitai]

Walkthrough

Adds a new CLI flag --simple-output and integrates a dual output mode into GenerateCommand: plain text vs. rich Spectre.Console UI. Updates validation, headers/banners, diagnostics, and file generation summaries to respect the new mode. Documentation is updated across README, docs, and contributor guidance.

Changes

Cohort / File(s)	Summary
Docs: CLI flag and guidance README.md, docs/docfx_project/articles/cli-tool.md	Documents new --simple-output flag with examples and behavior description (plain text, no colors/emojis/banners).
Contributor instructions .github/copilot-instructions.md	Revises steps for adding CLI options; catalogs recent flags; expands UI/console and CI documentation.
CLI settings surface src/Refitter/Settings.cs	Adds public bool Settings.SimpleOutput with [CommandOption("--simple-output")], default false.
Command flow and output rendering src/Refitter/GenerateCommand.cs	Implements mode-aware output throughout: headers, validation messaging, diagnostics, stats, success/failure summaries, donation banner, and single/multi-file generation displays; introduces SimpleDonationBanner and extends helper signatures to support plain output.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor U as User
  participant CLI as GenerateCommand
  participant V as OpenAPI Validator
  participant G as Refit Generator
  participant Out as Console Output

  U->>CLI: refitter ./openapi.json [--simple-output]
  CLI->>CLI: Parse Settings (SimpleOutput)
  alt SimpleOutput = true
    CLI->>Out: Plain header lines
  else
    CLI->>Out: Rich ASCII banner/panel
  end

  CLI->>V: Validate(spec)
  alt Validation OK
    V-->>CLI: Diagnostics (warnings/info)
    CLI->>Out: Mode-aware warnings/info
    CLI->>G: Generate interfaces/files
    G-->>CLI: Results (files, stats)
    alt SimpleOutput
      CLI->>Out: Plain stats and per-file summary
      CLI->>Out: Plain success + duration
      CLI->>Out: Simple donation banner (if !NoBanner)
    else
      CLI->>Out: Tables/panels for stats and files
      CLI->>Out: Success panel + performance
      CLI->>Out: Rich donation banner (if !NoBanner)
    end
  else Validation Failed
    V-->>CLI: Errors
    alt SimpleOutput
      CLI->>Out: Plain failure message + diagnostics
    else
      CLI->>Out: Panels with errors/diagnostics
    end
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Fancy CLI output using Spectre Console #695 — Prior work introducing/expanding rich UI flow; this PR branches that flow with SimpleOutput.
• Fix table alignments in CLI Output #720 — Changes warning/table rendering in GenerateCommand; overlaps with this PR’s mode-aware output paths.
• ASCII Art Title #729 — Adjusts header/banner rendering; directly related to this PR’s conditional banners.

Poem

I thump the keys with gentle might,
Turning banners dark to light—
When glyphs go wild and colors pout,
I flip a flag: plain text out.
Quiet console, tidy view,
Hippity-hop, your logs are new. 🐇

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The PR title "Introduce --simple-output CLI argument" succinctly and accurately describes the main change (adding a SimpleOutput CLI flag and associated behavior). It is concise, single-line, and avoids noise or vague wording. The title is specific enough for teammates scanning history to understand the primary intent.
Linked Issues Check	✅ Passed	The changes implement a --simple-output setting (Settings.SimpleOutput) and propagate it through GenerateCommand.cs so banners, validation output, and file summaries are rendered as plain ASCII/text, and README and CLI docs were updated; this directly addresses the linked issue #750's symptom of mangled/unreadable Unicode output. The implementation routes error/diagnostic printing to Console.WriteLine when simple output is enabled, which fulfills the coding-related requirement to produce legible output. Because the mode is opt-in (default false) the fix restores readable output for users who enable the flag but does not change default behavior for existing users.
Out of Scope Changes Check	✅ Passed	All modifications are scoped to adding and supporting the new SimpleOutput CLI flag and updating documentation; changed files (src/Refitter/Settings.cs and src/Refitter/GenerateCommand.cs, plus README/docs and .github/copilot-instructions.md) align with the PR objectives and the linked issue. I do not see unrelated code changes to other subsystems or unexpected public API alterations beyond the intended Settings.SimpleOutput property. No out-of-scope code changes were detected.

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch simple-log-output

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

• Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
• Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Please see the documentation for more information.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull Request Overview

This pull request introduces a new --simple-output CLI option to Refitter that generates plain-text console output without rich formatting, colors, ASCII art, tables, or emojis. This is particularly valuable for integration with IDEs and build tools that don't support rich terminal formatting.

Key changes include:

• Added the --simple-output command-line option with corresponding logic throughout the CLI
• Updated all output paths to provide both rich (Spectre.Console) and simple (plain text) formatting modes
• Enhanced documentation to describe the new option and its use cases

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/Refitter/Settings.cs	Added SimpleOutput property with CommandOption attribute
src/Refitter/GenerateCommand.cs	Implemented dual output modes throughout all CLI interactions
docs/docfx_project/articles/cli-tool.md	Added --simple-output to CLI documentation examples and options
README.md	Added --simple-output to examples and comprehensive documentation section
.github/copilot-instructions.md	Updated development guidelines with recent CLI options and UI information

[sonarqubecloud]

Quality Gate failed

Failed conditions
4.1% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.52%. Comparing base (0b9fb99) to head (2056e3c).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #751      +/-   ##
==========================================
+ Coverage   95.47%   98.52%   +3.05%     
==========================================
  Files          60       60              
  Lines        2982     2918      -64     
==========================================
+ Hits         2847     2875      +28     
+ Misses        102        4      -98     
- Partials       33       39       +6     

Flag	Coverage Δ
unittests	98.52% <ø> (+3.05%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

src/Refitter/GenerateCommand.cs (2)

88-96: Bug: Overwrites OpenApiPath from .refitter with null when CLI arg not provided.

If the user relies on openApiPath inside the settings file, this line nulls it and breaks generation/validation.

-                refitGeneratorSettings = Serializer.Deserialize<RefitGeneratorSettings>(json);
-                refitGeneratorSettings.OpenApiPath = settings.OpenApiPath!;
+                refitGeneratorSettings = Serializer.Deserialize<RefitGeneratorSettings>(json);
+                // Only override when CLI argument is explicitly provided
+                if (!string.IsNullOrWhiteSpace(settings.OpenApiPath))
+                {
+                    refitGeneratorSettings.OpenApiPath = settings.OpenApiPath!;
+                }

Optional: resolve relative paths in the .refitter file against its directory.

+                var baseDir = Path.GetDirectoryName(settings.SettingsFilePath) ?? string.Empty;
+                if (!string.IsNullOrWhiteSpace(refitGeneratorSettings.OpenApiPath) &&
+                    !Path.IsPathRooted(refitGeneratorSettings.OpenApiPath))
+                {
+                    refitGeneratorSettings.OpenApiPath = Path.GetFullPath(Path.Combine(baseDir, refitGeneratorSettings.OpenApiPath));
+                }

---

108-127: Remove emojis from --simple-output output

Console.WriteLine at src/Refitter/GenerateCommand.cs:111 prints "⚠️"; ensure simple-output mode emits a plain-text warning instead.

🧹 Nitpick comments (6)

docs/docfx_project/articles/cli-tool.md (2)

87-87: Unify wording across docs/README/Settings.

Consider aligning this description with Settings.cs and README to a single canonical sentence to avoid drift. Suggest: “Generate simple, plain-text console output without ASCII art, tables, emojis, or ANSI color/markup (suitable for IDE output windows).”

-        --simple-output                                          Generate output with no color, no formatting, no emojis, and no banners suitable for terminal or IDE output                            
+        --simple-output                                          Generate simple, plain‑text console output without ASCII art, tables, emojis, or ANSI color/markup (suitable for IDE output windows)

---

139-141: System requirements inconsistent with README.

README states “.NET 8.0 or .NET 9.0” while this doc says “.NET 8.0”. Update for consistency.

-.NET 8.0
+.NET 8.0 or .NET 9.0

README.md (1)

151-172: Great section; add one sentence tying to garbled output issue.

Explicitly call out that this mode avoids ANSI and non-ASCII causing “mangled/unreadable” output (issue #750).

 This mode generates plain text output without:
@@
 - Tables and panels
+
+This helps avoid “mangled” or unreadable characters in environments that strip or misinterpret ANSI/Unicode (see issue #750).

.github/copilot-instructions.md (3)

140-146: Clarify when to add to RefitGeneratorSettings.

UI-only flags (like --simple-output) don’t need Core settings; tighten guidance.

-1. Add new property to `src/Refitter/Settings.cs` with `[CommandOption("--option-name")]` attribute
-2. Update `CreateRefitGeneratorSettings()` method in `src/Refitter/GenerateCommand.cs` to map the setting
-3. Add corresponding property to `src/Refitter.Core/Settings/RefitGeneratorSettings.cs`
+1. Add new property to `src/Refitter/Settings.cs` with `[CommandOption("--option-name")]` attribute
+2. Update `CreateRefitGeneratorSettings()` in `src/Refitter/GenerateCommand.cs` to map the setting when the generator needs it
+3. Add a corresponding property to `src/Refitter.Core/Settings/RefitGeneratorSettings.cs` only if the generator logic requires it (do NOT add UI-only flags)
 4. Implement logic in `src/Refitter.Core/RefitInterfaceGenerator.cs` or related generator classes
 5. Add unit tests in `src/Refitter.Tests/Examples/` following the established pattern
-6. Update README.md documentation with the new option
+6. Update README.md and docs (`docs/docfx_project/articles/cli-tool.md`) with the new option

---

147-153: Add --simple-output to “Recent CLI Options Added.”

 - `--no-banner`: Hide donation banner in CLI output
+- `--simple-output`: Produce plain-text output without colors/ASCII art/emojis/tables

---

167-173: Document simple output behavior here to guide contributors.

 - CLI uses **Spectre.Console** for rich terminal output with colors, tables, and panels
 - ASCII art banner is displayed on startup (can be disabled with `--no-banner`)
 - Progress indicators and formatted tables show generation status and file information
 - Error handling includes styled panels and structured exception display
 - Support key display for troubleshooting (disabled when `--no-logging` is used)
+ - When `--simple-output` is set, never write ANSI markup, colors, emojis, or box-drawing characters; use Console.WriteLine only

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ea3deb1 and 2056e3c.

📒 Files selected for processing (5)

• .github/copilot-instructions.md (2 hunks)
• README.md (3 hunks)
• docs/docfx_project/articles/cli-tool.md (2 hunks)
• src/Refitter/GenerateCommand.cs (12 hunks)
• src/Refitter/Settings.cs (1 hunks)

🧰 Additional context used

📓 Path-based instructions (5)

README.md

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Update README.md when adding new CLI options or features

Files:

• README.md

**/*.cs

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

**/*.cs: Follow existing C# coding conventions defined in .editorconfig
Use PascalCase for public members and camelCase for parameters and local variables
Use meaningful variable and method names
Keep methods focused with single responsibility

Files:

• src/Refitter/Settings.cs
• src/Refitter/GenerateCommand.cs

src/{Refitter,Refitter.Core,Refitter.SourceGenerator,Refitter.MSBuild}/**/*.cs

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Include XML documentation for public APIs

Files:

• src/Refitter/Settings.cs
• src/Refitter/GenerateCommand.cs

docs/**

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Validate that every documented command actually works before adding it to documentation or instructions

Files:

• docs/docfx_project/articles/cli-tool.md

src/Refitter/GenerateCommand.cs

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

When adding a new CLI option, update GenerateCommand.cs with new command-line arguments

Files:

• src/Refitter/GenerateCommand.cs

🧠 Learnings (8)

📓 Common learnings

Learnt from: CR
PR: christianhelle/refitter#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-13T18:27:12.292Z
Learning: Applies to README.md : Update README.md when adding new CLI options or features

📚 Learning: 2025-08-13T18:27:12.292Z

Learnt from: CR
PR: christianhelle/refitter#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-13T18:27:12.292Z
Learning: Applies to README.md : Update README.md when adding new CLI options or features

Applied to files:

• README.md
• docs/docfx_project/articles/cli-tool.md
• .github/copilot-instructions.md

📚 Learning: 2025-08-13T18:27:12.292Z

Learnt from: CR
PR: christianhelle/refitter#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-13T18:27:12.292Z
Learning: Applies to src/Refitter.Core/RefitInterfaceGenerator.cs : When adding a new CLI option, implement the generation logic in RefitInterfaceGenerator

Applied to files:

• README.md
• .github/copilot-instructions.md

📚 Learning: 2025-08-13T18:27:12.292Z

Learnt from: CR
PR: christianhelle/refitter#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-13T18:27:12.292Z
Learning: Applies to src/Refitter.Core/Settings/RefitGeneratorSettings.cs : When adding a new CLI option, add a corresponding property to RefitGeneratorSettings

Applied to files:

• src/Refitter/Settings.cs
• .github/copilot-instructions.md

📚 Learning: 2025-08-13T18:27:12.292Z

Learnt from: CR
PR: christianhelle/refitter#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-13T18:27:12.292Z
Learning: Applies to src/Refitter/GenerateCommand.cs : When adding a new CLI option, update GenerateCommand.cs with new command-line arguments

Applied to files:

• .github/copilot-instructions.md

📚 Learning: 2025-08-13T18:27:12.292Z

Learnt from: CR
PR: christianhelle/refitter#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-13T18:27:12.292Z
Learning: Applies to src/Refitter.Tests/Examples/**/*.cs : When adding a new CLI option, add unit tests under Refitter.Tests/Examples

Applied to files:

• .github/copilot-instructions.md

📚 Learning: 2025-08-13T18:27:12.292Z

Learnt from: CR
PR: christianhelle/refitter#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-13T18:27:12.292Z
Learning: For CLI changes, test with a real OpenAPI specification to ensure generation works

Applied to files:

• .github/copilot-instructions.md

📚 Learning: 2025-08-13T18:27:12.292Z

Learnt from: CR
PR: christianhelle/refitter#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-13T18:27:12.292Z
Learning: Applies to src/{Refitter.Tests,Refitter.SourceGenerator.Tests}/**/*.cs : All new code must include unit tests following the Refitter.Tests.Examples pattern (xUnit [Fact], assertions, and compile check)

Applied to files:

• .github/copilot-instructions.md

🧬 Code graph analysis (1)

src/Refitter/GenerateCommand.cs (4)

src/Refitter/Validation/OpenApiValidationException.cs (2)

• OpenApiValidationException (3-13)
• OpenApiValidationException (7-12)

src/Refitter/Analytics.cs (1)

• Task (105-126)

src/Refitter/Validation/OpenApiValidator.cs (2)

• Task (8-19)
• OpenApiValidator (6-20)

src/Refitter/Settings.cs (1)

• Settings (7-256)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

• GitHub Check: script
• GitHub Check: 👌 Verify build
• GitHub Check: 👌 Verify build
• GitHub Check: 👌 Verify build
• GitHub Check: Analyze (csharp)

🔇 Additional comments (7)

README.md (2)

64-64: Example addition looks good.

---

107-107: Option entry looks good; matches CLI.

src/Refitter/GenerateCommand.cs (4)

48-64: Header branching looks good; no ANSI/ASCII when simple.

---

131-152: Success summary branching looks good.

---

320-333: Progress indication: OK.

Spinner preserved in rich mode; plain message in simple mode.

---

657-763: Validation output handles both modes well.

Good split: plain text list vs Spectre table.

docs/docfx_project/articles/cli-tool.md (1)

43-43: Example addition looks good — manual end-to-end verification required

dotnet not available in the sandbox (dotnet: command not found). Run the following locally to verify the CLI help shows --simple-output and generation works with a sample spec:

#!/bin/bash
set -euo pipefail
# Check help includes --simple-output
dotnet run --project src/Refitter --configuration Release --framework net9.0 -- --help | rg -n -- '--simple-output'

# Find a bundled OpenAPI sample and run generation with simple output
spec="$(fd -a -t f -g 'SwaggerPetstore*.json' src/Refitter.Tests/Resources || true | head -n1)"
if [[ -z "${spec}" ]]; then
  echo "No sample spec found; please provide one." >&2
  exit 1
fi
dotnet run --project src/Refitter --configuration Release --framework net9.0 -- "${spec}" --output ./_tmp.cs --simple-output | rg -nP '[^\x00-\x7F]' && { echo "Non-ASCII char found in simple output" >&2; exit 2; } || true