⚡ cli-fp: Native CLIs for Free Pascal

• Start smallBuild one useful root command with the class-based API.
• Grow cleanlyAdd named and nested commands when the CLI needs them.
• Stay consistentShare validation, help, completion and terminal output.
• Generate when usefulUse cli-fp-gen for larger command trees, not for your first step.

cli-fp is a small Free Pascal framework for native command-line programs. It provides command trees, validated options, generated help and shell completion, colours, spinners, and progress bars—without third-party runtime dependencies.

Your first CLI

This complete root-command program is also QuickStartDemo, compiled by the Windows and Linux example smoke checks.

program QuickStartDemo;

{$mode objfpc}{$H+}{$J-}

uses
  CLI.Interfaces, CLI.Application, CLI.Command;

type
  THelloCommand = class(TBaseCommand)
  public
    function Execute: Integer; override;
  end;

function THelloCommand.Execute: Integer;
var
  PersonName: string;
begin
  if not GetParameterValue('--name', PersonName) then
    PersonName := 'World';
  WriteLn('Hello, ', PersonName, '!');
  Result := 0;
end;

var
  App: ICLIApplication;
  Main: THelloCommand;
begin
  Main := THelloCommand.Create('', 'Print a greeting');
  Main.AddStringParameter('-n', '--name', 'Name to greet', False, 'World');
  App := CreateCLIApplication('hello', '1.0.0', Main);
  Halt(App.Execute);
end.

Compile from a clone of this repository:

fpc -Fu./src ./examples/QuickStartDemo/QuickStartDemo.lpr
./examples/QuickStartDemo/QuickStartDemo --name Ada

$ ./examples/QuickStartDemo/QuickStartDemo --name Ada
Hello, Ada!

On PowerShell, use fpc "-Fu.\src" .\examples\QuickStartDemo\QuickStartDemo.lpr and run .\examples\QuickStartDemo\QuickStartDemo.exe --name Ada.

Choose a CLI shape

Documentation

• Documentation site — navigate by goal.
• Your first cli-fp program — compile and understand the example above.
• How do I...? — short recipes for options, output, completion, the generator, and debugging.
• Current limitations — find the supported boundaries.
• API reference — look up public signatures.
• Technical documentation — architecture and maintainer material.

Examples and generator

The runnable examples progress from QuickStartDemo through root, named, nested, error-handling, colour, and progress applications. They are compiled by the cross-platform cleanup smoke checks.

Use cli-fp-gen when a larger command tree benefits from a scaffolded project layout. It is optional; the program above is the shortest way to start.

Requirements

• Free Pascal 3.2.2 is the tested compiler version.
• Windows and Linux run the repository's CI checks.
• Lazarus is optional; a runtime package is available in the packages/lazarus/ directory.
• The runtime has no third-party dependencies. The generator uses FCL JSON units.

Contributing

See the contribution guide. On Windows, run:

powershell -ExecutionPolicy Bypass -File tests\run_tests.ps1
powershell -ExecutionPolicy Bypass -File tests\codegen\run_all_tests.ps1
powershell -ExecutionPolicy Bypass -File tests\run_cleanup_smoke.ps1

The Bash equivalents and the full project map are in the contribution guide.

License

cli-fp is available under the MIT License.