SiroccoCLIFx 1.2.0

SiroccoCLIFx

A lightweight, feature-rich .NET library for building beautiful console applications.

SiroccoCLIFx v1.2.0 Release Notes

Major stability & correctness update. All 1.0.x / 1.1.x users are advised to upgrade.

Features

None

Bug Fixes

• ConsoleFx CJK/Emoji width �� Fixed WrapText and WriteWrapped to correctly calculate display width for CJK/Emoji characters (count as 2 columns), preventing misaligned wrapping.
• ConsoleFx ANSI stripping �� Added StripAnsi to remove escape sequences before width calculation, avoiding interference from color codes.
• ConsoleFx style state stack �� SetForeground/SetBackground now push/pop state via _styleStateStack, allowing ResetStyles to restore previous colors without pollution.
• ConsoleFx Filter exceptions �� Exceptions in Filter delegate are now caught and logged (Debug only), no longer crashing or blocking output.
• Windows fallback �� On legacy Windows terminals without VT support, true color is disabled and falls back to 16-color mode to prevent garbage output.
• Terminal mode restoration �� Original console mode is restored on process exit (including Ctrl+C), preventing permanent color corruption.
• MenuSelector non?interactive fallback �� When stdin is redirected, Select falls back to plain numeric selection, avoiding InvalidOperationException.
• MenuSelector safe window size �� Console.WindowWidth/Height now fall back to 80x24 when output is redirected, preventing exceptions.
• MenuSelector screen cleanup �� Menu exit now clears all rows with correct width, leaving no stray characters.
• MenuSelector prompt control �� The prompt parameter now only outputs when non?null; null means no prompt, giving full caller control.
• MenuSelector layout offset �� linesWritten now correctly increments only when output is actually written, fixing title/menu alignment.
• Chart vertical bar labels �� BarChartOrientation.Vertical now displays numeric labels above bars.
• Chart line chart �� DrawLineChart is now fully implemented (was a stub).
• Chart safe window size �� DrawBarChart uses safe terminal dimension reads to avoid exceptions in redirected environments.
• ProgressTracker bottom mode infinite recursion �� Fixed StackOverflowException when logging occurred with EnableBottomMode enabled.
• ProgressTracker redirect protection �� EnableBottomMode now returns early when output is redirected, preventing log pollution.
• ProgressTracker trailing cleanup �� DrawProgressBarCore uses safe width values to clear trailing characters.
• ArgumentParser bool Required �� [Option(Required = true)] now correctly validates bool properties (checks if explicitly set, not value).
• ArgumentParser collection Required �� Required string[]/List<T> options now accept empty collections as explicitly provided, no longer falsely reporting missing.
• ArgumentParser positional Required �� [Value(Required = true)] now correctly enforces required positional parameters.
• **Obsolete methods** �� ForceSplitandFindBestSplitmarked[Obsolete]` to prevent accidental use.
• ArgumentParser JSON/XML value retention �� ParseFromJson and ParseFromXml now preserve values from config files even when ApplyDefaults runs; only command-line overrides take effect.
• ProgressTracker immediate progress refresh �� Update now redraws the progress bar immediately in bottom mode, preventing stale 0% display.
• ProgressTracker log emission �� Fixed OnLogWrite/OnLogWriteLine to ensure logs are emitted without being swallowed, using proper locking and original output stream.
• ProgressTracker spinner deadlock �� RunWithSpinner and RunWithSpinnerAsync no longer deadlock due to nested locks; spinner tasks run without holding the main lock.
• ParserContext collection defaults �� ApplyDefaults now correctly instantiates List<T> for interface types like IList<T> and IEnumerable<T>.
• ConsoleFx color state isolation �� SetForeground/SetBackground now use an internal style stack to prevent interference with Write style scopes.
• ProgressTracker bottom mode cursor positioning �� Fixed off-by-one clearing of the progress line, ensuring no stray characters remain.
• ArgumentParser subcommand set tracking �� Subcommand instances now correctly track which properties were set, fixing Requires/Excludes validation for nested commands.

Upgrade Recommended

dotnet add package SiroccoCLIFx --version 1.2.0

If you encounter any new issues, please submit them on GitHub Issues. https://github.com/Ricespoon-y/SiroccoCLIFx/

Overview

SiroccoCLIFx is a lightweight .NET library that supercharges your console applications with:

• True color support (with automatic fallback to 16 colors)
• Bold and italic text styles
• Customizable progress bars with weighted branches and ETA estimation
• Interactive menus with keyboard navigation (arrow keys, PageUp/PageDown)
• Command-line argument parsing with nesting, dependencies, and JSON/XML config loading
• Smart text wrapping (auto-break at punctuation)
• Spinner animations for long-running operations
• Output filtering and thread-safe operations
• Charting & Plotting �V Draw function curves, bar charts (horizontal/vertical), and line charts with customizable colors and styles.
• Hyperlinks �V Output clickable links (OSC 8) supported by modern terminals.
• Underline style �V Use TextStyle.Underline for underlined text.

All functionality is exposed via clean, intuitive APIs, and the library has zero external dependencies (only System.Text.Json for JSON support, which is built into .NET Core 3.0+).

Features

Installation

Via NuGet

dotnet add package SiroccoCLIFx

Via source

• Clone the repository and build:
• git clone https://github.com/Ricespoon-y/SiroccoCLIFx.git
• cd SiroccoCLIFx
• dotnet build -c Release
• Then reference the DLL in your project.

Quick Start

1. Colored Output

using SiroccoCLIFx;

ConsoleFx.WriteLine("Hello, World!", new TextStyle(
    foreground: ConsoleColorEx.BrightGreen,
    bold: true,
    italic: true
));

// RGB color (if terminal supports true color)
ConsoleFx.WriteLine("RGB Text", new TextStyle(foreground: Color.FromRgb(255, 128, 64)
));

2. Progress Bar with Branching

using SiroccoCLIFx.Progress;

using var progress = new ProgressTracker();

using (var branch = progress.Branch(100)) // total weight = 100
{
    for (int i = 0; i < 50; i++)
    {
        branch.Update(2);   // each step = 2 weight
        progress.DrawProgressBarAtRow(row: 3, width: 40, fillStr: "=");
        Thread.Sleep(50);
    }
} // leftover branch weight is automatically removed

3. Bottom-Mode Progress Bar (No Flicker)

using SiroccoCLIFx.Progress;

using var progress = new ProgressTracker();
progress.EnableBottomMode(width: 50, fillStr: "=", emptyStr: "-");

for (int i = 0; i <= 100; i++)
{
    Console.WriteLine($"Processing item {i}...");
    progress.Update(1);
    Thread.Sleep(30);
}

Console.WriteLine("All done!"); // appears right after the 100% bar

4. Interactive Menu

string[] options = { "Option A", "Option B", "Option C" };
int choice = MenuSelector.Select(
    options: options,
    defaultIndex: 0,
    title: "Please select:",
    selectedStyle: new TextStyle(
        foreground: ConsoleColorEx.BrightYellow,
        background: ConsoleColorEx.DarkBlue,
        bold: true
    )
);
Console.WriteLine($"You chose: {options[choice]}");

5. Argument Parsing

using SiroccoCLIFx.Parsing;

public class MyArgs
{
    [Option("--input", "-i", Required = true)]
    public string Input { get; set; }

    [Option("--verbose", "-v")]
    public bool Verbose { get; set; }

    [Value(0)]
    public string Source { get; set; }
}

var args = new[] { "--input", "data.txt", "--verbose", "source" };
var parsed = ArgumentParser.Parse<MyArgs>(args);
var errors = ArgumentParser.Validate(parsed);

6. Drawing a Function Curve

using SiroccoCLIFx.Charting;

Chart.Draw(
    func: x => Math.Sin(x),
    xMin: -5, xMax: 5,
    width: 80, height: 20,
    lineChar: '#',
    axisColor: ConsoleColorEx.BrightBlack,
    lineColor: ConsoleColorEx.BrightRed
);

7. Bar Chart

var data = new Dictionary<string, double>
{
    ["Apple"] = 85,
    ["Banana"] = 120,
    ["Cherry"] = 60,
    ["Date"] = 95
};

// Horizontal
Chart.DrawBarChart(data, width: 30, orientation: BarChartOrientation.Horizontal);

// Vertical with values
Chart.DrawBarChart(data, width: 20, orientation: BarChartOrientation.Vertical, showValues: true);

8. Line Chart

var points = new List<(double x, double y)>();
for (int i = 0; i < 100; i++)
{
    double x = i / 10.0;
    points.Add((x, Math.Sin(x)));
}

Chart.DrawLineChart(points, width: 40, height: 10, lineChar: '*');

9. Spinner Animation

using var progress = new ProgressTracker();
progress.RunWithSpinner("Processing...", () =>
{
    Thread.Sleep(3000); // Simulate a long task
});

10. Hyperlink

ConsoleFx.WriteLink("Visit the repo", "https://github.com/Ricespoon-y/SiroccoCLIFx");

API Overview

ConsoleFx static class

• Write(string text, TextStyle? style) Write colored/styled text
• WriteLine(string text, TextStyle? style) Write colored/styled text with newline
• WriteWrapped(string text, int maxWidth, TextStyle? style) Auto-wrap text
• SetForeground(Color color) Set foreground color
• SetBackground(Color color) Set background color
• ResetStyles() Reset all styles
• WriteLink(string text, string url, TextStyle? style) Output clickable hyperlink
• GetDisplayWidth(string text) Get the actual terminal display width (CJK/Emoji count as 2)
• TruncateToWidth(string text, int maxWidth, string suffix) Truncate text to fit a display width
• Filter Delegate to filter output lines

ProgressTracker class

• Branch(double weight) Returns IProgressBranch
• Update(double step) Root-mode update
• DrawProgressBar(...) Draws progress bar on current line
• DrawProgressBarAtRow(int row, ...) Draws on a fixed row
• EnableBottomMode(...) New in 1.2.0 Fixes progress bar to bottom with no flicker
• DisableBottomMode() New in 1.2.0 Disables bottom mode
• RunWithSpinner(...) Synchronous spinner
• RunWithSpinnerAsync(...) Asynchronous spinner
• EstimateRemaining() Returns TimeSpan? ETA

MenuSelector static class

• Select(string[] options, int defaultIndex, ...) Returns selected index

ArgumentParser static class

• Parse<T>(string[] args) Parses into T
• ParseFromJson<T>(string jsonPath, string[] args) Loads from JSON then overrides with CLI
• ParseFromXml<T>(string xmlPath, string[] args) Same for XML
• Validate<T>(T obj) Returns list of validation errors

Chart static class

• Draw(...) Draws a function curve
• DrawBarChart(...) Draws a horizontal or vertical bar chart
• DrawLineChart(...) Draws a line chart from points

Changelog

[1.2.0] - 2026-08-31

• ConsoleFx CJK/Emoji width �� Fixed WrapText and WriteWrapped to correctly calculate display width for CJK/Emoji characters (count as 2 columns), preventing misaligned wrapping.
• ConsoleFx ANSI stripping �� Added StripAnsi to remove escape sequences before width calculation, avoiding interference from color codes.
• ConsoleFx style state stack �� SetForeground/SetBackground now push/pop state via _styleStateStack, allowing ResetStyles to restore previous colors without pollution.
• ConsoleFx Filter exceptions �� Exceptions in Filter delegate are now caught and logged (Debug only), no longer crashing or blocking output.
• Windows fallback �� On legacy Windows terminals without VT support, true color is disabled and falls back to 16-color mode to prevent garbage output.
• Terminal mode restoration �� Original console mode is restored on process exit (including Ctrl+C), preventing permanent color corruption.
• MenuSelector non?interactive fallback �� When stdin is redirected, Select falls back to plain numeric selection, avoiding InvalidOperationException.
• MenuSelector safe window size �� Console.WindowWidth/Height now fall back to 80x24 when output is redirected, preventing exceptions.
• MenuSelector screen cleanup �� Menu exit now clears all rows with correct width, leaving no stray characters.
• MenuSelector prompt control �� The prompt parameter now only outputs when non?null; null means no prompt, giving full caller control.
• MenuSelector layout offset �� linesWritten now correctly increments only when output is actually written, fixing title/menu alignment.
• Chart vertical bar labels �� BarChartOrientation.Vertical now displays numeric labels above bars.
• Chart line chart �� DrawLineChart is now fully implemented (was a stub).
• Chart safe window size �� DrawBarChart uses safe terminal dimension reads to avoid exceptions in redirected environments.
• ProgressTracker bottom mode infinite recursion �� Fixed StackOverflowException when logging occurred with EnableBottomMode enabled.
• ProgressTracker redirect protection �� EnableBottomMode now returns early when output is redirected, preventing log pollution.
• ProgressTracker trailing cleanup �� DrawProgressBarCore uses safe width values to clear trailing characters.
• ArgumentParser bool Required �� [Option(Required = true)] now correctly validates bool properties (checks if explicitly set, not value).
• ArgumentParser collection Required �� Required string[]/List<T> options now accept empty collections as explicitly provided, no longer falsely reporting missing.
• ArgumentParser positional Required �� [Value(Required = true)] now correctly enforces required positional parameters.
• Obsolete methods �� ForceSplit and FindBestSplit marked [Obsolete] to prevent accidental use.
• ArgumentParser JSON/XML value retention �� ParseFromJson and ParseFromXml now preserve values from config files even when ApplyDefaults runs; only command-line overrides take effect.
• ProgressTracker immediate progress refresh �� Update now redraws the progress bar immediately in bottom mode, preventing stale 0% display.
• ProgressTracker log emission �� Fixed OnLogWrite/OnLogWriteLine to ensure logs are emitted without being swallowed, using proper locking and original output stream.
• ProgressTracker spinner deadlock �� RunWithSpinner and RunWithSpinnerAsync no longer deadlock due to nested locks; spinner tasks run without holding the main lock.
• ParserContext collection defaults �� ApplyDefaults now correctly instantiates List<T> for interface types like IList<T> and IEnumerable<T>.
• ConsoleFx color state isolation �� SetForeground/SetBackground now use an internal style stack to prevent interference with Write style scopes.
• ProgressTracker bottom mode cursor positioning �� Fixed off-by-one clearing of the progress line, ensuring no stray characters remain.
• ArgumentParser subcommand set tracking �� Subcommand instances now correctly track which properties were set, fixing Requires/Excludes validation for nested commands.

[1.1.2] - 2026-08-31

• Fixed StackOverflowException in ProgressTracker.EnableBottomMode
• Fixed boolean [Option(Required = true)] validation in ArgumentParser
• Fixed MenuSelector cleanup leaving stray characters
• Fixed ValueAttribute.Required positional parameter validation
• Implemented DrawLineChart method
• Vertical bar charts now display numeric values
• Made ConsoleFx.Filter thread-safe
• Automatic terminal mode restore on process exit
• Added EnableBottomMode and DisableBottomMode APIs

[1.1.0] - 2026-08-19

• Added bottom-fixed progress bar mode
• Added charting module (function curves, bar charts)
• Added hyperlink support (OSC 8)
• Added spinner animations
• Fixed various progress bar edge cases

[1.0.0] - Initial release

• Basic colored output with ConsoleFx
• Progress tracker with branching
• Interactive menu selector
• Command-line argument parsing

Requirements

• .NET Standard 2.0 or later (.NET Core 3.0+, .NET 5/6/7/8, .NET Framework 4.6.2+)

• A modern terminal that supports ANSI escape codes (Windows Terminal, iTerm2, etc.) for full color experience.

Contributing

Pull requests and issues are welcome! Please ensure you follow the existing code style and add tests where applicable.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Enjoy building better console apps with SiroccoCLIFx!