{"id":51412834,"url":"https://github.com/citomni/cli","last_synced_at":"2026-07-04T16:01:14.255Z","repository":{"id":362567952,"uuid":"1065713355","full_name":"citomni/cli","owner":"citomni","description":"CitOmni CLI is a lean, low-overhead command-line runtime for PHP, sharing the CitOmni kernel boot model with deterministic config composition, explicit services, and provider-driven command registration.","archived":false,"fork":false,"pushed_at":"2026-06-04T20:59:16.000Z","size":37,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T22:17:55.108Z","etag":null,"topics":["citomni","citomni-framework","citomni-php","cli","cli-app","command-line","command-runner","console","deterministic","green-coding","high-performance","kernel","low-overhead","php","php-cli","php-cli-framework","php-framework","php8","runtime","service-container"],"latest_commit_sha":null,"homepage":"https://www.citomni.com/","language":"PHP","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/citomni.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-28T09:29:07.000Z","updated_at":"2026-06-04T21:00:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/citomni/cli","commit_stats":null,"previous_names":["citomni/cli"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/citomni/cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citomni%2Fcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citomni%2Fcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citomni%2Fcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citomni%2Fcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/citomni","download_url":"https://codeload.github.com/citomni/cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citomni%2Fcli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35127443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["citomni","citomni-framework","citomni-php","cli","cli-app","command-line","command-runner","console","deterministic","green-coding","high-performance","kernel","low-overhead","php","php-cli","php-cli-framework","php-framework","php8","runtime","service-container"],"created_at":"2026-07-04T16:01:13.145Z","updated_at":"2026-07-04T16:01:14.243Z","avatar_url":"https://github.com/citomni.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CitOmni CLI\n\nDeterministic command-line runtime for CitOmni applications.\n\n`citomni/cli` is the dedicated CLI delivery layer in the CitOmni ecosystem. It provides the runtime boundary for command execution in the same architectural spirit as `citomni/http` provides the runtime boundary for web delivery: explicit boot, deterministic composition, minimal entrypoint code, and no framework magic disguised as convenience.\n\nThe package is intentionally narrow in scope. It owns the CLI runtime, its boot process, command dispatch, and CLI-specific failure rendering/logging. It does not attempt to absorb every command-related concern into itself. Shared abstractions and reusable command infrastructure may live in other CitOmni packages where that ownership is more appropriate.\n\nIn practical terms, `citomni/cli` gives a CitOmni application a formal command-line execution model rather than a pile of ad-hoc PHP scripts wearing the ceremonial robes of a console framework.\n\n---\n\n## Highlights\n\n- **Dedicated CLI runtime for CitOmni** with explicit kernel boot and command dispatch\n- **Deterministic composition model** aligned with the wider CitOmni architecture\n- **Minimal entrypoint philosophy** through a slim `bin/console` front controller\n- **Provider-aware boot pipeline** for CLI config and service-map contributions\n- **CLI-specific error handling** with controlled diagnostics and logging behavior\n- **No command scanning magic** beyond explicit package/application composition rules\n- **Shared architectural DNA with CitOmni HTTP** while remaining a proper CLI runtime in its own right\n- ♻️ **Low-overhead by design** - explicit boot, predictable resolution, and minimal runtime indirection\n\n---\n\n## What this package is\n\n`citomni/cli` is the command-line mode of the CitOmni framework.\n\nIt provides the application-facing runtime required to execute commands in a structured and deterministic way. That includes bootstrapping the application in CLI mode, resolving CLI-relevant config and services, locating registered commands, dispatching execution, and handling runtime failures in a way appropriate to terminal usage rather than HTTP delivery.\n\nThis package therefore occupies the same conceptual layer for CLI that `citomni/http` occupies for web requests. It is not merely a convenience script collection, and it is not a general-purpose shell framework bolted onto CitOmni after the fact.\n\n---\n\n## What this package provides\n\n### CLI runtime responsibilities\n\n- CLI kernel boot and handoff\n- CLI-specific config assembly\n- CLI-specific service-map assembly\n- Command discovery from the composed application/runtime graph\n- Command dispatch from process arguments\n- Command-list rendering for discovery/help scenarios\n- CLI-specific error, exception, and fatal handling\n\n### Delivery-layer concerns\n\n- Terminal-oriented execution flow\n- Exit-oriented runtime behavior\n- Developer-friendly diagnostics in development contexts\n- Safe, constrained failure output in non-development contexts\n- Logging hooks for operational visibility where configured\n\n---\n\n## What this package does not own\n\n`citomni/cli` is intentionally not a monolithic home for every command-related abstraction.\n\nIt does **not** need to own:\n\n- Every reusable command base class\n- Every argv parsing helper in the ecosystem\n- Every command help formatter\n- Domain command logic itself\n- Shared orchestration used by both HTTP and CLI\n- Persistence logic\n- Application/domain services merely because they are invoked from commands\n\nThose concerns may live in other packages when that boundary is architecturally cleaner. A command-line runtime should not annex neighboring responsibilities simply because it happens to be holding the terminal.\n\n---\n\n## Relationship to the wider CitOmni architecture\n\nCitOmni separates delivery layers from orchestration, persistence, and reusable services.\n\nWithin that model:\n\n1. `citomni/kernel` provides the application core, config/service composition, and service resolution model.\n2. `citomni/http` provides HTTP delivery.\n3. `citomni/cli` provides CLI delivery.\n4. Shared/domain packages contribute services, config, routes, commands, and other package-owned capabilities through explicit boot metadata.\n5. The application composes the final runtime.\n\n`citomni/cli` therefore exists as a first-class delivery layer, not as an afterthought, and not as a thin wrapper around a generic command runner with ambitions above its station.\n\n---\n\n## Runtime model\n\nThe package follows the standard CitOmni principles:\n\n- explicit boot\n- deterministic composition\n- fail-fast behavior\n- minimal entrypoint code\n- no namespace scanning as a substitute for design\n\nAt runtime, a typical CLI process looks conceptually like this:\n\n`bin/console` -\u003e `Cli\\Kernel::run()` -\u003e `new App($configDir, Mode::CLI)` -\u003e CLI config/services built from vendor baseline, providers, and app overrides -\u003e CLI error handler installed -\u003e command runner resolves and executes the requested command\n\nThis keeps CLI execution aligned with the broader CitOmni boot model while respecting the very different operational semantics of a terminal process.\n\n---\n\n## Deterministic composition\n\nLike the rest of CitOmni, `citomni/cli` favors explicit composition over hidden discovery.\n\nCLI config and services are assembled from defined sources in a deterministic order. The exact mechanics are intentionally parallel to the broader framework model: vendor baseline first, then provider contributions, then application-level overrides.\n\nThis matters operationally. A command should not change behavior because a package happened to be scanned differently, nor because an autoloading side effect quietly altered registration order. Determinism is not academic polish here; it is a practical debugging advantage.\n\n---\n\n## Requirements\n\n- PHP **8.2+**\n- `citomni/kernel`\n\nOPcache is strongly recommended in production-like environments where CLI workloads are frequent or operationally important.\n\n---\n\n## Installation\n\n```bash\ncomposer require citomni/cli\ncomposer dump-autoload -o\n````\n\nRegister the package provider in your application configuration if your composition model requires it.\n\nYour application's `composer.json` should also expose your own code through PSR-4 autoloading:\n\n```json\n{\n\t\"autoload\": {\n\t\t\"psr-4\": {\n\t\t\t\"App\\\\\": \"src/\"\n\t\t}\n\t}\n}\n```\n\nThen refresh the autoloader:\n\n```bash\ncomposer dump-autoload -o\n```\n\n---\n\n## Quick start\n\nA minimal `bin/console` entrypoint typically looks like this:\n\n```php\n\u003c?php\ndeclare(strict_types=1);\n\ndefine('CITOMNI_ENVIRONMENT', 'dev');           // dev | stage | prod\ndefine('CITOMNI_APP_PATH', \\dirname(__DIR__));\n\nrequire CITOMNI_APP_PATH . '/vendor/autoload.php';\n\n\\CitOmni\\Cli\\Kernel::run(__DIR__);\n```\n\nThe point of this file is not to become clever. Its job is to hand execution to the CLI kernel and then get out of the way.\n\n---\n\n## Typical app layout\n\n```text\n/app-root\n  /bin\n    citomni\n  /config\n    providers.php\n    services.php\n    citomni_cli_cfg.php\n    citomni_cli_cfg.dev.php\n    citomni_cli_cfg.stage.php\n    citomni_cli_cfg.prod.php\n    citomni_cli_commands.php\n    citomni_cli_commands.dev.php\n    citomni_cli_commands.stage.php\n    citomni_cli_commands.prod.php\n  /src\n    /Cli\n      /Command\n      /Exception\n    /Operation\n    /Repository\n    /Service\n    /Util\n  /var\n    /cache\n    /flags\n    /logs\n    /state\n  /vendor\n```\n\nThe exact application structure can vary, but the important distinction remains: commands belong to the CLI-facing adapter layer; orchestration belongs elsewhere; persistence belongs in repositories.\n\n---\n\n## Commands and architectural boundaries\n\nCommands are CLI adapters.\n\nThat means they own terminal-facing concerns such as:\n\n* receiving process arguments\n* validating user input at the CLI boundary\n* formatting terminal output\n* choosing exit codes\n* delegating actual business workflows to operations/repositories/services as appropriate\n\nThey should **not** become storage layers, mailers, HTTP simulators, or miniature god-objects with a text cursor.\n\nIn normal CitOmni architecture terms:\n\n* **Commands** own CLI transport concerns\n* **Operations** own orchestration\n* **Repositories** own persistence\n* **Services** provide reusable runtime capabilities\n\nThis is not merely a cleanliness preference. Command code remains easier to reason about, easier to test, and less likely to accumulate irreversible \"just this once\" terminal logic that metastasizes into application policy.\n\n---\n\n## Command discovery and dispatch\n\n`citomni/cli` provides the runtime machinery needed to locate registered commands and dispatch them from argv input.\n\nIn a typical setup, the command runner is responsible for:\n\n* receiving raw process arguments\n* resolving the intended command\n* showing grouped command lists when no command or an unknown command is supplied\n* invoking the matching command class\n* delegating command-specific parsing/validation to the command-side infrastructure in use\n\nThis separation is deliberate. The runtime should know how to find and launch commands; it should not need intimate knowledge of every argument grammar in the ecosystem.\n\n---\n\n## Error handling\n\nCLI failure semantics differ from HTTP failure semantics, and `citomni/cli` treats them accordingly.\n\nThe CLI error handler is responsible for handling:\n\n* uncaught exceptions\n* PHP errors promoted or surfaced during runtime\n* fatal shutdown scenarios where relevant\n\nIn development contexts, richer diagnostic output may be rendered to support debugging. In non-development contexts, output should remain controlled, operationally sane, and suitable for logs or automated runners rather than theatrical terminal collapse.\n\nFail-fast remains the governing principle. Recoverability should be explicit. Silent swallowing of runtime failures is not resilience; it is deferred confusion.\n\n---\n\n## Configuration\n\nCLI configuration follows the same broad CitOmni model of explicit layered composition.\n\nTypical sources include:\n\n1. vendor CLI baseline\n2. provider CLI config contributions\n3. application CLI base config\n4. optional environment overlay for CLI mode\n\nThis enables command runtimes to remain predictable across environments without collapsing environment concerns into command classes themselves.\n\nA minimal `config/citomni_cli_cfg.php` may look like:\n\n```php\n\u003c?php\ndeclare(strict_types=1);\n\nreturn [\n\t'identity' =\u003e [\n\t\t'app_name' =\u003e 'My CitOmni App',\n\t],\n\n\t// Add CLI-specific runtime settings here, such as error-handler\n\t// options, logging paths, or package-specific CLI configuration.\n];\n```\n\nEnvironment-specific overlays can then refine operational details without contaminating the baseline.\n\n---\n\n## Services\n\nAs with the rest of CitOmni, services are resolved through explicit service maps rather than runtime scanning.\n\nThat means:\n\n* predictable resolution\n* clear ownership\n* cacheable composition\n* lower runtime overhead\n* fewer surprises when debugging boot behavior\n\nIf your application or provider contributes CLI-relevant services, they should do so through the normal explicit registration mechanisms rather than magical discovery strategies that behave impressively until examined closely.\n\n---\n\n## Providers\n\nProviders may contribute CLI-specific metadata through the standard CitOmni boot/registry pattern.\n\nThat can include:\n\n* CLI service-map entries\n* CLI config overlays\n* CLI command registrations where applicable\n\nThis allows packages to participate in the CLI runtime without requiring the CLI package itself to know package-specific details in advance.\n\nIn other words, composition remains explicit, but it is not parochial.\n\n---\n\n## Operational philosophy\n\n`citomni/cli` is designed for systems that value:\n\n* low runtime overhead\n* explicit architecture\n* repeatable behavior\n* production sanity\n* composable package boundaries\n\nIt is not trying to be a maximalist \"developer experience\" console framework where every ergonomic flourish is purchased with hidden indirection, runtime scanning, and enough implicit behavior to qualify as folklore.\n\nCitOmni's position is simpler: commands should run predictably, boot cheaply, fail clearly, and respect architectural boundaries.\n\nThat is usually more useful than spectacle.\n\n---\n\n## Performance notes\n\n* Use optimized Composer autoloading in production:\n\n  ```json\n  {\n  \t\"config\": {\n  \t\t\"optimize-autoloader\": true,\n  \t\t\"classmap-authoritative\": true,\n  \t\t\"apcu-autoloader\": true\n  \t}\n  }\n  ```\n\n* Then run:\n\n  ```bash\n  composer dump-autoload -o\n  ```\n\n* Keep vendor baselines lean\n\n* Prefer explicit service registration over dynamic discovery\n\n* Avoid putting domain orchestration directly into commands\n\n* Use OPcache in operational environments where CLI processes are frequent\n\nThe package is aligned with the broader CitOmni preference for predictable low-cost execution rather than clever abstractions with a surprisingly healthy appetite for CPU cycles.\n\n---\n\n## Contributing\n\n* PHP 8.2+\n* PSR-4\n* Tabs for indentation\n* K\u0026R brace style\n* Keep delivery-layer boundaries sharp\n* Keep persistence in repositories\n* Keep orchestration out of command adapters unless the task is genuinely trivial\n* Avoid framework magic\n* Prefer explicit behavior over implicit convenience\n\n---\n\n## Coding \u0026 Documentation Conventions\n\nAll CitOmni projects follow the shared conventions documented here:\n[CitOmni Coding \u0026 Documentation Conventions](https://github.com/citomni/docs/blob/main/contribute/CONVENTIONS.md)\n\n---\n\n## License\n\n**CitOmni CLI** is open-source under the **MIT License**.\nSee [LICENSE](LICENSE).\n\n**Trademark notice:** \"CitOmni\" and the CitOmni logo are trademarks of **Lars Grove Mortensen**.\nYou may not use the CitOmni name or logo to imply endorsement or affiliation without prior written permission.\nFor details, see [NOTICE](NOTICE).\n\n---\n\n## Trademarks\n\n\"CitOmni\" and the CitOmni logo are trademarks of **Lars Grove Mortensen**.\nYou may make factual references to \"CitOmni\", but do not modify the marks, create confusingly similar logos, or imply sponsorship, endorsement, or affiliation without prior written permission.\nDo not register or use \"citomni\" (or confusingly similar terms) in company names, domains, social handles, or top-level vendor/package names.\nFor details, see [NOTICE](NOTICE).\n\n---\n\n## Author\n\nDeveloped by Lars Grove Mortensen © 2012-present.\n\n---\n\nCitOmni - low overhead, high performance, ready for anything.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcitomni%2Fcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcitomni%2Fcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcitomni%2Fcli/lists"}