NextGenSoftware.CLI.Engine 2.0.3

NextGenSoftware.CLI.Engine

A feature-rich CLI engine for .NET — colour output, animations, spinners, tables, progress bars, ASCII art, interactive prompts, non-interactive / CI mode, and more. The terminal backbone of the OASIS Omniverse ecosystem, used in HoloNET, the OASIS API CLI, STAR ODK, and OurWorld.

Part of the OASIS Omniverse v2.0 Reboot. Visit oasisomniverse.one.

Installation

dotnet add package NextGenSoftware.CLI.Engine

Global Properties

CLIEngine.SuccessMessageColour   = ConsoleColor.Green;     // default
CLIEngine.ErrorMessageColour     = ConsoleColor.Red;       // default
CLIEngine.WarningMessageColour   = ConsoleColor.DarkYellow;// default
CLIEngine.WorkingMessageColour   = ConsoleColor.Yellow;    // default
CLIEngine.SupressConsoleLogging  = false;                  // set true to silence all output
CLIEngine.NonInteractive         = false;                  // set true for CI / shell mode
CLIEngine.AssumeYes              = false;                  // auto-yes for GetConfirmation in NonInteractive
CLIEngine.JsonOutput             = false;                  // flag for JSON-line host apps
CLIEngine.Quiet                  = false;                  // suppress banners/donation messages
CLIEngine.MaxHolonSearchResults  = 0;                      // 0 = unlimited
CLIEngine.ErrorHandlingBehaviour = ErrorHandlingBehaviour.OnlyThrowExceptionIfNoErrorHandlerSubscribedToOnErrorEvent;

Events

CLIEngine.OnError += (sender, e) => {
    Console.WriteLine($"CLIEngine error: {e.Reason}");
    Console.WriteLine(e.ErrorDetails);
};

Output Methods

ShowMessage

CLIEngine.ShowMessage("Hello world");                            // yellow, with leading blank line
CLIEngine.ShowMessage("Done.", ConsoleColor.Cyan);              // custom colour
CLIEngine.ShowMessage("Inline", lineSpace: false, noLineBreaks: true); // no newline appended
CLIEngine.ShowMessage("Indented", intendBy: 4);                // extra indent spaces
CLIEngine.ShowMessage("After gap", addLineBefore: true);       // blank line before message

ShowSuccessMessage / ShowErrorMessage / ShowWarningMessage

CLIEngine.ShowSuccessMessage("All packages published!");
CLIEngine.ShowErrorMessage("Connection failed.", addLineBefore: true);
CLIEngine.ShowWarningMessage("Proceeding with defaults.");

ShowDivider

CLIEngine.ShowDivider();                         // 119 "*" characters
CLIEngine.ShowDivider("-", 80);                  // 80 dashes
CLIEngine.ShowDivider("=", 60, lineSpace: false);

DisplayProperty

CLIEngine.DisplayProperty("Status", "Connected", displayFieldLength: 20);
// Output:  Status:             Connected
CLIEngine.DisplayProperty("Version", "4.0.0", 20, displayColon: false);

Working Message Spinner

Displays a message then starts an animated spinner on the same line. EndWorkingMessage stops the spinner and prints a result on the same line.

CLIEngine.BeginWorkingMessage("Connecting to Holochain conductor...");
await client.ConnectAsync();
CLIEngine.EndWorkingMessage("DONE");           // prints " DONE" on the same line

// Or with a custom colour:
CLIEngine.BeginWorkingMessage("Loading data...", ConsoleColor.Cyan);
var data = await LoadDataAsync();
CLIEngine.EndWorkingMessage("Loaded.", ConsoleColor.Green);

ShowWorkingMessage (lower level)

CLIEngine.ShowWorkingMessage("Processing...");
// ... do work ...
// spinner continues until next ShowMessage call or Spinner.Stop()

UpdateWorkingMessage / UpdateWorkingMessageWithPercent

CLIEngine.BeginWorkingMessage("Uploading...");
for (int i = 0; i <= 100; i += 10)
{
    await Task.Delay(200);
    CLIEngine.UpdateWorkingMessageWithPercent(i);
}
CLIEngine.EndWorkingMessage("Complete.");

CLIEngine.UpdateWorkingMessage("Still going...", ConsoleColor.Cyan);

Progress Bar

for (double i = 0; i <= 1.0; i += 0.1)
{
    CLIEngine.ShowProgressBar(i);       // 0.0 – 1.0
    await Task.Delay(200);
}
CLIEngine.DisposeProgressBar();         // clears bar from console
CLIEngine.DisposeProgressBar(clearText: false); // leaves final bar text visible

ASCII Art Banner

CLIEngine.WriteAsciMessage("OASIS", System.Drawing.Color.Cyan);

Colour Helpers

CLIEngine.ShowColoursAvailable();           // lists all valid ConsoleColor names in their own colour
CLIEngine.PrintColour("DarkGreen");         // writes "DarkGreen" in dark green

Interactive Input Methods

All input methods throw CLIEngineNonInteractiveInputRequiredException when CLIEngine.NonInteractive = true.

Text Input

string name  = CLIEngine.GetValidInput("Enter your name:");
string title = CLIEngine.GetValidTitle("Enter title (Mr/Mrs/Ms/Miss/Dr):");
string email = CLIEngine.GetValidInputForEmail("Enter email:");

Numeric Input

int    count  = CLIEngine.GetValidInputForInt("How many?");
int    ranged = CLIEngine.GetValidInputForInt("Pick 1–10:", checkForLowestOrHighestRange: true, lowest: 1, highest: 10);
long   big    = CLIEngine.GetValidInputForLong("Enter a large number:");
double rate   = CLIEngine.GetValidInputForDouble("Enter rate:");
decimal price = CLIEngine.GetValidInputForDecimal("Enter price:");
Guid   id     = CLIEngine.GetValidInputForGuid("Enter GUID:");

Date Input

DateTime date = CLIEngine.GetValidInputForDate("Enter date (yyyy-mm-dd):");
// Type "exit" or "none" to cancel and return DateTime.MinValue

Enum Input

object result = CLIEngine.GetValidInputForEnum("Choose log level:", typeof(LogType));
LogType level = (LogType)result;
// Shows all valid enum values automatically; re-prompts on invalid input

Boolean / Confirmation

bool yes = CLIEngine.GetConfirmation("Are you sure? (Y/N)");
// Returns AssumeYes when NonInteractive = true

Password Input

string password = CLIEngine.GetValidPassword();
// Prompts twice, masks input with *, requires matching entries

string pw = CLIEngine.ReadPassword("Enter master password:");
// Single masked read

File and Folder Input

string folder = CLIEngine.GetValidFolder("Enter folder path:", createIfDoesNotExist: true);
string file   = CLIEngine.GetValidFile("Enter file path:");
byte[] bytes  = CLIEngine.GetValidFileAndUpload("Select file to upload:");

URI Input

Uri uri = await CLIEngine.GetValidURIAsync("Enter URL:", checkFileExists: true);
// Validates format and optionally does an HTTP HEAD to confirm resource exists

Colour Picker

ConsoleColor fav = ConsoleColor.Blue;
ConsoleColor cli = ConsoleColor.Green;
CLIEngine.GetValidColour(ref fav, ref cli);
// Interactive wizard: pick favourite colour + CLI display colour, with confirmation loop

Spinner (standalone)

var spinner = new Spinner();
spinner.Colour   = ConsoleColor.Cyan;
spinner.Sequence = @"/-\|";    // animation frames
spinner.Delay    = 100;        // ms per frame

spinner.Start();               // auto-positions at current cursor
spinner.Start(left: 20, top: 5, delay: 80); // explicit position
spinner.Stop();
spinner.Dispose();

// CLIEngine.Spinner is a shared singleton:
CLIEngine.Spinner.Colour = ConsoleColor.Magenta;

Animations

var anim = new Animations();

// Rotating spinner character at current position:
anim.Turn("Loading");

// Matrix-style grid animation at a fixed console position:
anim.SequencedMatrix(row: 5, column: 10, width: 8, height: 4);

// ASCII loading bar at a fixed position:
anim.LoadingBar("Loading", row: 3, column: 0);

anim.Ready(); // advance frame counter + sleep 75ms

// Simple inline spinner:
var spin = new ConsoleSpiner();
spin.Turn(); // writes one frame character and backtracks cursor

ConsoleHelper (Windows — Font Control)

var fontInfo = ConsoleHelper.SetCurrentFont("Lucida Console", fontSize: 16);
// Returns FontInfo[] { before, set, after }

Exceptions

ErrorHandlingBehaviour

• oasisomniverse.one | GitHub

MIT — Copyright © NextGen Software Ltd 2019 - 2026