{"id":44708350,"url":"https://github.com/ikelaiah/cli-fp","last_synced_at":"2026-02-15T11:13:59.776Z","repository":{"id":269093987,"uuid":"906194231","full_name":"ikelaiah/cli-fp","owner":"ikelaiah","description":"A robust Free Pascal framework for building professional CLI applications. Create powerful command-line tools with hierarchical commands, rich interactions, and comprehensive help systems - all with type-safe, object-oriented design.","archived":false,"fork":false,"pushed_at":"2025-12-31T08:25:44.000Z","size":3803,"stargazers_count":28,"open_issues_count":3,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-09T10:25:59.575Z","etag":null,"topics":["cli","command-line","commandline","framework","free-pascal","lazarus-ide","object-pascal"],"latest_commit_sha":null,"homepage":"https://github.com/ikelaiah/cli-fp","language":"Pascal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ikelaiah.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-20T11:09:40.000Z","updated_at":"2025-12-31T08:25:51.000Z","dependencies_parsed_at":"2025-06-20T05:30:00.822Z","dependency_job_id":null,"html_url":"https://github.com/ikelaiah/cli-fp","commit_stats":null,"previous_names":["ikelaiah/cli-fp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ikelaiah/cli-fp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikelaiah%2Fcli-fp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikelaiah%2Fcli-fp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikelaiah%2Fcli-fp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikelaiah%2Fcli-fp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ikelaiah","download_url":"https://codeload.github.com/ikelaiah/cli-fp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikelaiah%2Fcli-fp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29476300,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T10:25:47.032Z","status":"ssl_error","status_checked_at":"2026-02-15T10:25:01.815Z","response_time":118,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line","commandline","framework","free-pascal","lazarus-ide","object-pascal"],"created_at":"2026-02-15T11:13:59.564Z","updated_at":"2026-02-15T11:13:59.771Z","avatar_url":"https://github.com/ikelaiah.png","language":"Pascal","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Command-Line Interface Framework for Free Pascal 🚀\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Version](https://img.shields.io/badge/version-1.1.5-blue.svg)](https://github.com/ikelaiah/cli-fp/releases)\n[![Free Pascal](https://img.shields.io/badge/Free%20Pascal-3.2.2-blue.svg)](https://www.freepascal.org/)\n[![Lazarus](https://img.shields.io/badge/Lazarus-4.0-orange.svg)](https://www.lazarus-ide.org/)\n[![GitHub stars](https://img.shields.io/github/stars/ikelaiah/cli-fp?style=social)](https://github.com/ikelaiah/cli-fp/stargazers)\n[![GitHub issues](https://img.shields.io/github/issues/ikelaiah/cli-fp)](https://github.com/ikelaiah/cli-fp/issues)\n\nA robust toolkit for building command-line (terminal) applications in Free Pascal. Leverage Pascal's strong typing and compile-time checks while creating sophisticated terminal tools with features like `git`-style commands, progress bars, and coloured output for better readability.\n\nCombines Free Pascal's speed and reliability with professional-grade features. The object-oriented design handles the complex parts, letting you focus on your application's logic.\n\n## 📑 Table of Contents\n\n- [Command-Line Interface Framework for Free Pascal 🚀](#command-line-interface-framework-for-free-pascal-)\n  - [📑 Table of Contents](#-table-of-contents)\n  - [✨ Features](#-features)\n  - [🚀 Quick Start](#-quick-start)\n  - [🎯 Parameter Types and Validation](#-parameter-types-and-validation)\n    - [Basic Types](#basic-types)\n    - [Boolean and Flags](#boolean-and-flags)\n    - [Complex Types](#complex-types)\n    - [Validation Rules](#validation-rules)\n  - [📖 Screenshots](#-screenshots)\n  - [📖 System Requirements](#-system-requirements)\n    - [Tested Environments](#tested-environments)\n    - [Theoretical Compatibility](#theoretical-compatibility)\n    - [Dependencies](#dependencies)\n    - [Build Requirements](#build-requirements)\n  - [📖 Documentation](#-documentation)\n  - [🎯 Use Cases](#-use-cases)\n  - [🤝 Contributing](#-contributing)\n  - [📝 License](#-license)\n  - [🙏 Acknowledgments](#-acknowledgments)\n  - [� Completion Script Testing](#-completion-script-testing)\n  - [🧩 How to Generate Completion Scripts](#-how-to-generate-completion-scripts)\n  - [🧩 Bash Completion Script (`--completion-file`)](#-bash-completion-script---completion-file)\n  - [🧩 PowerShell Completion Script (`--completion-file-pwsh`)](#-powershell-completion-script---completion-file-pwsh)\n\n## ✨ Features\n\n- 🎯 **Command \u0026 Subcommand Support**: Organize complex CLIs with hierarchical commands\n- 🔍 **Smart Parameter Handling**: Automatic validation and type checking\n- 📊 **Progress Indicators**: Built-in spinners and progress bars\n- 🎨 **Colored Output**: Rich console output with basic color support\n- 📚 **Comprehensive Help System**: Auto-generated help with examples\n- 🛡️ **Type-Safe**: Interface-based design with strong typing\n- 🔌 **Extensible**: Easy to extend with custom commands and parameters\n- **Modern Command-Line Interface**\n  - Subcommand support (e.g., `app repo init`, `app repo clone`)\n  - Short and long flags (`-h`, `--help`)\n  - Automatic help generation\n  - Colored output support\n  - **Shell Completion**: Generate completion scripts for Bash (`--completion-file`) and PowerShell (`--completion-file-pwsh`) with automatic value completion for boolean and enum parameters\n- **Robust Error Handling**\n  - Clear error messages for unknown commands and subcommands\n  - Validation of command-line flags and parameters\n  - Helpful suggestions when errors occur\n  - Context-aware help display\n- **Developer-Friendly**\n  - Interface-based design\n  - Easy command registration\n  - Extensible parameter system\n  - Built-in progress indicators\n- **User-Friendly**\n  - Consistent help formatting\n  - Command suggestions\n  - Default values support\n  - Required parameter validation\n\n## 🚀 Quick Start\n\n1. **Installation**\n\nNo complex build system needed! Just:\n\n\u003e **Note:** All example builds output their executables and units to the `example-bin/` folder in the repository root for easy access and cleanup.\n\u003e\n\u003e **Tip:** To build or clean all example projects at once, use the provided scripts:\n\u003e\n\u003e - On **Linux/macOS**: `./compile-all-examples.sh` and `./clean-all-examples.sh`\n\u003e - On **Windows**: `./compile-all-examples.ps1` and `./clean-all-examples.ps1`\n\n\n```bash\n# Clone the repository\ngit clone https://github.com/ikelaiah/cli-fp.git\n\n# Or copy the source files to your project's directory\n```\n\n2. **Use in Your Project**\n\n- Add the source directory to your project's search path (Project -\u003e Project Options ... -\u003e Compiler Options -\u003e Paths -\u003e Other unit files)\n- Add the units to your uses clause:\n\n```pascal\nuses\n  CLI.Interfaces,    // Core interfaces\n  CLI.Application,   // Main application framework\n  CLI.Command,       // Base command implementation\n  CLI.Parameter,     // Parameter handling\n  CLI.Progress,      // Optional: Progress indicators\n  CLI.Console;       // Optional: Colored console output\n```\n\n3. **Create Your First CLI App**\n\n```pascal\nprogram MyApp;\n\n{$mode objfpc}{$H+}{$J-}\n\nuses\n  SysUtils,\n  CLI.Interfaces,\n  CLI.Application,\n  CLI.Command;\n\ntype\n  // Define a new command\n  TGreetCommand = class(TBaseCommand)\n  public\n    function Execute: integer; override;\n  end;\n\n  function TGreetCommand.Execute: integer;\n  var\n    Name: string;\n  begin\n    // Get parameter value using helper method\n    if GetParameterValue('--name', Name) then\n      WriteLn('Hello, ', Name, '!')\n    else\n      WriteLn('Hello, World!');\n    Result := 0;\n  end;\n\n{ Main program }\nvar\n  App: ICLIApplication;\n  Cmd: TGreetCommand;\n\nbegin\n  App := CreateCLIApplication('MyApp', '1.0.0');\n  \n  // Create and configure command\n  Cmd := TGreetCommand.Create('greet', 'Say hello');\n  Cmd.AddStringParameter('-n', '--name', 'Name to greet', False, 'World');\n  \n  // Register command\n  App.RegisterCommand(Cmd);\n  \n  // Execute application\n  ExitCode := App.Execute;\nend.\n```\n\n**Output:**\n```\n$ ./myapp greet --name \"John\"\nHello, John!\n\n$ ./myapp greet\nHello, World!\n\n$ ./myapp greet --help\nUsage: myapp greet [options]\n\nSay hello\n\nOptions:\n  -n, --name           Name to greet\n      Default: World\n  -h, --help          Show this help message\n```\n\n**Lazarus users:**\nA runtime-only Lazarus package is provided in `packages/lazarus/cli_fp.lpk`.\nTo use it, open the `.lpk` file in Lazarus, click “Compile,” then click “Add” to add it to your project’s required packages.\n\n## 🎯 Parameter Types and Validation\n\nThe framework provides comprehensive type-safe parameter handling with built-in validation:\n\n### Basic Types\n\n```pascal\n// String parameter\nCmd.AddStringParameter('-n', '--name', 'Name to greet');\n\n// Integer parameter (required)\nCmd.AddIntegerParameter('-c', '--count', 'Number of items', True);\n\n// Float parameter with default\nCmd.AddFloatParameter('-r', '--rate', 'Processing rate', False, '1.0');\n```\n\n### Boolean and Flags\n\n```pascal\n// Flag (true when present, false by default)\nCmd.AddFlag('-v', '--verbose', 'Enable verbose output'); // Standard CLI behavior\n\n// Boolean parameter (explicit true/false)\nCmd.AddBooleanParameter('-d', '--debug', 'Enable debug mode', False, 'false');\n```\n\n\u003e **Note:** By default, flags created with `AddFlag` are `false` unless present on the command line. If you specify a default value of `'true'`, the flag will be `true` even if not present, which is nonstandard for CLI flags and not recommended unless you have a specific use case.\n\n### Complex Types\n\n```pascal\n// DateTime (YYYY-MM-DD HH:MM)\nCmd.AddDateTimeParameter('-d', '--date', 'Start date');\n\n// Enum with allowed values\nCmd.AddEnumParameter('-l', '--level', 'Log level', 'debug|info|warn|error');\n\n// URL with protocol validation\nCmd.AddUrlParameter('-u', '--url', 'Repository URL');\n\n// Array (comma-separated)\nCmd.AddArrayParameter('-t', '--tags', 'Tag list');\n\n// Password (masked in output)\nCmd.AddPasswordParameter('-k', '--api-key', 'API Key');\n```\n\n### Validation Rules\n\nEach parameter type has built-in validation:\n\n- `String`: No validation\n- `Integer`: Must be a valid integer number\n- `Float`: Must be a valid floating-point number\n- `Boolean`: Must be 'true' or 'false' (case-insensitive)\n- `DateTime`: Must be in format \"YYYY-MM-DD HH:MM\" (24-hour)\n- `Enum`: Must match one of the pipe-separated allowed values\n- `URL`: Must start with http://, https://, git://, or ssh://\n- `Array`: No validation on individual items\n- `Password`: No validation, but value is masked in output\n\n## 📖 Screenshots\n\n![ColorDemo Help](docs/images/colordemo-help.png)\n![ColorDemo Greeting](docs/images/colordemo-greeting.png)\n*Above: The ColorDemo example showing professional CLI styling with colors, Unicode characters, and progress indicators.*\n\n## 📖 System Requirements\n\n### Tested Environments\n\n- **Operating System**: Windows 11, Ubuntu 24.04\n- **Compiler**: Free Pascal (FPC) 3.2.2\n- **IDE**: Lazarus 3.6, Lazarus 4.0\n\n### Theoretical Compatibility\n\n- **Operating Systems**:\n  - Windows (7, 8, 10, 11)\n  - Linux (Any distribution with FPC support)\n  - macOS (with FPC support)\n  - FreeBSD\n- **Compiler**: Free Pascal 3.2.2 or higher\n- **IDE \u0026 Editor**: Any IDE that supports Free Pascal\n  - Lazarus 3.6 or higher\n  - VS Code with Pascal extensions\n  - Other text editors\n\n### Dependencies\n\n- No external dependencies required\n- Uses only standard Free Pascal RTL units\n\n### Build Requirements\n\n- Free Pascal Compiler (FPC) 3.2.2+\n- Lazarus 3.6+\n- Basic development tools (git, terminal, etc)\n\n## 📖 Documentation\n\n- [User Manual](docs/user-manual.md): Complete guide for using the framework, *including a cheat sheet*\n- [API Reference](docs/api-reference.md): Detailed API reference for the framework\n- [Technical Documentation](docs/technical-docs.md): Architecture and implementation details\n- [Examples](examples/): Working example applications\n- [Changelog](CHANGELOG.md): Version history and updates\n\n## 🎯 Use Cases\n\nPerfect for building:\n\n- Version Control Systems\n- Build Tools\n- Package Managers\n- Development Tools\n- System Utilities\n- DevOps Tools\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Inspired by modern CLI frameworks\n- Built with Free Pascal and Lazarus IDE\n- Thanks to the Free Pascal community for their support and contributions\n\n## 🧪 Completion Script Testing\n\n- **Bash Completion**: Tested on Bash 4.4.23 via Git Bash (Windows)\n  - **30/30 manual test cases passing (100%)**\n  - All root-level, command, subcommand, and flag completions verified\n  - See [BASH_COMPLETION_GUIDE.md](docs/completion-testing/BASH_COMPLETION_GUIDE.md) for user guide\n  - See [BASH_COMPLETION_TESTS.md](docs/completion-testing/BASH_COMPLETION_TESTS.md) for test suite\n\n- **PowerShell Completion**: Tested on PowerShell 7.5.4 (Windows)\n  - **30/30 manual test cases passing (100%)**\n  - All completion features working as designed\n  - See [PS_COMPLETION_GUIDE.md](docs/completion-testing/PS_COMPLETION_GUIDE.md) for user guide\n  - See [PS_COMPLETION_TESTS.md](docs/completion-testing/PS_COMPLETION_TESTS.md) for test suite\n\n\u003e **Full Documentation:** All test documentation, guides, and analysis available in [docs/completion-testing/](docs/completion-testing/)\n\u003e\n\u003e **Tip:** To check your PowerShell version, run:\n\u003e ```powershell\n\u003e $PSVersionTable.PSVersion\n\u003e ```\n\n## 🧩 How to Generate Completion Scripts\n\n- **Bash:**\n  ```bash\n  ./yourcli --completion-file \u003e myapp-completion.sh\n  ```\n- **PowerShell:**\n  ```powershell\n  ./yourcli.exe --completion-file-pwsh \u003e myapp-completion.ps1\n  ```\n\n### 💡 Completion Behavior Note\n\n**Commands First Design:** When you press TAB at the root level without typing anything, completion shows **commands only**, not flags. To see flags, type `-` or `--` first:\n\n```bash\n# Shows commands only\n./yourcli [TAB]\n\n# Shows all flags\n./yourcli --[TAB]\n./yourcli -[TAB]\n```\n\nThis intentional design keeps the initial suggestions focused on the most common workflow (choosing a command first), while keeping flags easily accessible with a prefix. This behavior is consistent across both Bash and PowerShell.\n\n## 🧩 Bash Completion Script (`--completion-file`)\n\nGenerate a Bash completion script for your CLI with:\n\n```bash\n./yourcli --completion-file \u003e myapp-completion.sh\n```\n\n- **Root level:** All global flags (`--help`, `-h`, `--help-complete`, `--version`, `--completion-file`) are offered.\n- **Subcommands:** Only `-h` and `--help` are offered as global flags.\n- **Completions are always context-aware**—only valid subcommands and parameters for the current path are suggested.\n- **Automatic value completion:** Boolean parameters automatically complete with `true`/`false`, and enum parameters complete with their allowed values.\n\n\u003e This matches the CLI's actual argument parsing and ensures completions are always valid. See the user manual for full details and safe usage instructions.\n\n## 🧩 PowerShell Completion Script (`--completion-file-pwsh`)\n\nGenerate a PowerShell completion script for your CLI with:\n\n```powershell\n./yourcli.exe --completion-file-pwsh \u003e myapp-completion.ps1\n```\n\n- **Context-aware:** Tab completion for all commands, subcommands, and flags at every level\n- **No file fallback:** Only valid completions are shown (never files)\n- **Automatic value completion:** Boolean parameters automatically complete with `true`/`false`, and enum parameters complete with their allowed values.\n- **Works in PowerShell 7.5+** (cross-platform)\n\n\u003e See the user manual for setup and usage details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fikelaiah%2Fcli-fp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fikelaiah%2Fcli-fp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fikelaiah%2Fcli-fp/lists"}