cli-fp API reference

How do I...? · Commands · Options · Current limitations

Use this page to look up the current public, application-facing API. For a complete program, start with your first CLI. The public units in src/ are the authoritative declarations. Signature blocks below are API declarations; application code is always labelled as a program-setup fragment and names its variables or states the command pattern it depends on.

Units to use

Application

Create and run

function CreateCLIApplication(const Name, Version: string): ICLIApplication; overload;
function CreateCLIApplication(const Name, Version: string;
  const RootCommand: ICommand): ICLIApplication; overload;

Use the two-argument overload for a command-first application. Use the three-argument overload when an unnamed root command should run for myapp [options].

The following program-setup fragment needs CLI.Interfaces and CLI.Application. It assumes TRootCommand is a declared TBaseCommand descendant with an overridden Execute; Root is the instance passed to the factory.

var
  App: ICLIApplication;
  Root: TRootCommand;
begin
  Root := TRootCommand.Create('', 'Run the default action');
  App := CreateCLIApplication('myapp', '1.0.0', Root);
  Halt(App.Execute);
end.

ICLIApplication exposes:

procedure RegisterCommand(const Command: ICommand);
function Execute: Integer;

Execute parses and validates arguments, services built-in requests, and returns the selected command's exit code.

Concrete application features

TCLIApplication also exposes DebugMode, Version, RootCommand, and Commands. It has test-oriented helpers and deprecated completion callback methods; those are not needed for ordinary applications. The callback methods are no-op compatibility members in 1.x—see limitations.

Commands

TBaseCommand

constructor Create(const AName, ADescription: string);
function Execute: Integer; virtual; abstract;
procedure AddSubCommand(const Command: ICommand);
function GetParameterValue(const Flag: string; out Value: string): Boolean;

Subclass TBaseCommand, override Execute, register options during setup, and return 0 on success. Use an empty AName for a root command.

GetParameterValue is protected, so call it from your descendant's Execute. It finds either registered flag spelling and returns values as strings.

Register parameters

All parameters use string flag and description arguments. AllowedValues is a pipe-separated string, such as debug|info|warn. See options for validation behavior and How do I...? for minimal examples.

Parameter kinds

TParameterType contains ptString, ptInteger, ptFloat, ptBoolean, ptPath, ptEnum, ptDateTime, ptArray, ptPassword, and ptUrl.

ICommandParameter exposes ShortFlag, LongFlag, Description, Required, ParamType, DefaultValue, and AllowedValues. For lower-level registration, use:

function CreateParameter(const ShortFlag, LongFlag, Description: string;
  Required: Boolean; ParamType: TParameterType;
  const DefaultValue: string = ''; const AllowedValues: string = ''): ICommandParameter;

Then pass the result to AddParameter(const Parameter: ICommandParameter).

Command contracts

ICommand is the minimal command contract:

function GetName: string;
function GetDescription: string;
function GetParameters: specialize TArray<ICommandParameter>;
function GetSubCommands: specialize TArray<ICommand>;
function Execute: Integer;

TBaseCommand implements it and is the normal choice when your command needs framework-managed parameter lookup. A custom ICommand may also implement ICommandParameterReceiver.SetParsedParams to receive parsed values.

Terminal output

TConsole

class procedure Write(const Text: string); overload;
class procedure Write(const Text: string; const FgColor: TConsoleColor); overload;
class procedure WriteLn(const Text: string); overload;
class procedure WriteLn(const Text: string; const FgColor: TConsoleColor); overload;

For cursor-oriented terminal work, TConsole also provides foreground and background colour setters, ResetColors, ClearLine, cursor movement, and save/restore cursor methods. TConsoleColor offers standard and bright colour values, including ccGreen, ccYellow, and ccRed.

Progress

function CreateSpinner(const Style: TSpinnerStyle = ssLine): IProgressIndicator;
function CreateProgressBar(const Total: Integer;
  const Width: Integer = 10): IProgressIndicator;

IProgressIndicator has Start, Stop, and Update(const Progress: Integer; const ACaption: string = ''). Spinner styles are ssDots, ssLine, ssCircle, ssSquare, ssArrow, ssBounce, and ssBar. Use Update repeatedly during work, then call Stop in finally.

Errors and built-in requests

ECLIException is the framework exception type in CLI.Errors. Catch it or a broader Exception only where your application can add useful recovery or context.

Applications receive -h/--help, --help-complete, and -v/--version. When it is the first argument, --completion-file prints a Bash script and --completion-file-pwsh prints a PowerShell script. See shell completion for usage.