PHPackages                             citomni/cli - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. citomni/cli

ActiveLibrary[Framework](/categories/framework)

citomni/cli
===========

High-performance CLI runtime for CitOmni apps: kernel boot glue, command runner, console dispatch, and CLI error handling.

v1.0.0.1(3mo ago)001MITPHPPHP ^8.2

Since Mar 26Pushed 2w agoCompare

[ Source](https://github.com/citomni/cli)[ Packagist](https://packagist.org/packages/citomni/cli)[ Docs](https://github.com/citomni/cli)[ GitHub Sponsors](https://github.com/LarsGMortensen)[ Fund](https://ko-fi.com/)[ RSS](/packages/citomni-cli/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (1)Dependencies (3)Versions (2)Used By (1)

CitOmni CLI
===========

[](#citomni-cli)

Deterministic command-line runtime for CitOmni applications.

`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.

The 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.

In 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.

---

Highlights
----------

[](#highlights)

- **Dedicated CLI runtime for CitOmni** with explicit kernel boot and command dispatch
- **Deterministic composition model** aligned with the wider CitOmni architecture
- **Minimal entrypoint philosophy** through a slim `bin/console` front controller
- **Provider-aware boot pipeline** for CLI config and service-map contributions
- **CLI-specific error handling** with controlled diagnostics and logging behavior
- **No command scanning magic** beyond explicit package/application composition rules
- **Shared architectural DNA with CitOmni HTTP** while remaining a proper CLI runtime in its own right
- ♻️ **Low-overhead by design** - explicit boot, predictable resolution, and minimal runtime indirection

---

What this package is
--------------------

[](#what-this-package-is)

`citomni/cli` is the command-line mode of the CitOmni framework.

It 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.

This 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.

---

What this package provides
--------------------------

[](#what-this-package-provides)

### CLI runtime responsibilities

[](#cli-runtime-responsibilities)

- CLI kernel boot and handoff
- CLI-specific config assembly
- CLI-specific service-map assembly
- Command discovery from the composed application/runtime graph
- Command dispatch from process arguments
- Command-list rendering for discovery/help scenarios
- CLI-specific error, exception, and fatal handling

### Delivery-layer concerns

[](#delivery-layer-concerns)

- Terminal-oriented execution flow
- Exit-oriented runtime behavior
- Developer-friendly diagnostics in development contexts
- Safe, constrained failure output in non-development contexts
- Logging hooks for operational visibility where configured

---

What this package does not own
------------------------------

[](#what-this-package-does-not-own)

`citomni/cli` is intentionally not a monolithic home for every command-related abstraction.

It does **not** need to own:

- Every reusable command base class
- Every argv parsing helper in the ecosystem
- Every command help formatter
- Domain command logic itself
- Shared orchestration used by both HTTP and CLI
- Persistence logic
- Application/domain services merely because they are invoked from commands

Those 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.

---

Relationship to the wider CitOmni architecture
----------------------------------------------

[](#relationship-to-the-wider-citomni-architecture)

CitOmni separates delivery layers from orchestration, persistence, and reusable services.

Within that model:

1. `citomni/kernel` provides the application core, config/service composition, and service resolution model.
2. `citomni/http` provides HTTP delivery.
3. `citomni/cli` provides CLI delivery.
4. Shared/domain packages contribute services, config, routes, commands, and other package-owned capabilities through explicit boot metadata.
5. The application composes the final runtime.

`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.

---

Runtime model
-------------

[](#runtime-model)

The package follows the standard CitOmni principles:

- explicit boot
- deterministic composition
- fail-fast behavior
- minimal entrypoint code
- no namespace scanning as a substitute for design

At runtime, a typical CLI process looks conceptually like this:

`bin/console` -> `Cli\Kernel::run()` -> `new App($configDir, Mode::CLI)` -> CLI config/services built from vendor baseline, providers, and app overrides -> CLI error handler installed -> command runner resolves and executes the requested command

This keeps CLI execution aligned with the broader CitOmni boot model while respecting the very different operational semantics of a terminal process.

---

Deterministic composition
-------------------------

[](#deterministic-composition)

Like the rest of CitOmni, `citomni/cli` favors explicit composition over hidden discovery.

CLI 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.

This 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.

---

Requirements
------------

[](#requirements)

- PHP **8.2+**
- `citomni/kernel`

OPcache is strongly recommended in production-like environments where CLI workloads are frequent or operationally important.

---

Installation
------------

[](#installation)

```
composer require citomni/cli
composer dump-autoload -o
```

Register the package provider in your application configuration if your composition model requires it.

Your application's `composer.json` should also expose your own code through PSR-4 autoloading:

```
{
	"autoload": {
		"psr-4": {
			"App\\": "src/"
		}
	}
}
```

Then refresh the autoloader:

```
composer dump-autoload -o
```

---

Quick start
-----------

[](#quick-start)

A minimal `bin/console` entrypoint typically looks like this:

```