README

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

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

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

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

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

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

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

Within that model:

citomni/kernel provides the application core, config/service composition, and service resolution model.
citomni/http provides HTTP delivery.
citomni/cli provides CLI delivery.
Shared/domain packages contribute services, config, routes, commands, and other package-owned capabilities through explicit boot metadata.
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

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

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

PHP 8.2+
citomni/kernel

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

Installation

composer require citomni/cli
composer dump-autoload -o

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

A minimal bin/console entrypoint typically looks like this:

<?php
declare(strict_types=1);

define('CITOMNI_ENVIRONMENT', 'dev');           // dev | stage | prod
define('CITOMNI_APP_PATH', \dirname(__DIR__));

require CITOMNI_APP_PATH . '/vendor/autoload.php';

\CitOmni\Cli\Kernel::run(__DIR__);

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

Typical app layout

/app-root
  /bin
    citomni
  /config
    providers.php
    services.php
    citomni_cli_cfg.php
    citomni_cli_cfg.dev.php
    citomni_cli_cfg.stage.php
    citomni_cli_cfg.prod.php
    citomni_cli_commands.php
    citomni_cli_commands.dev.php
    citomni_cli_commands.stage.php
    citomni_cli_commands.prod.php
  /src
    /Cli
      /Command
      /Exception
    /Operation
    /Repository
    /Service
    /Util
  /var
    /cache
    /flags
    /logs
    /state
  /vendor

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

Commands and architectural boundaries

Commands are CLI adapters.

That means they own terminal-facing concerns such as:

receiving process arguments
validating user input at the CLI boundary
formatting terminal output
choosing exit codes
delegating actual business workflows to operations/repositories/services as appropriate

They should not become storage layers, mailers, HTTP simulators, or miniature god-objects with a text cursor.

In normal CitOmni architecture terms:

Commands own CLI transport concerns
Operations own orchestration
Repositories own persistence
Services provide reusable runtime capabilities

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

Command discovery and dispatch

citomni/cli provides the runtime machinery needed to locate registered commands and dispatch them from argv input.

In a typical setup, the command runner is responsible for:

receiving raw process arguments
resolving the intended command
showing grouped command lists when no command or an unknown command is supplied
invoking the matching command class
delegating command-specific parsing/validation to the command-side infrastructure in use

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

Error handling

CLI failure semantics differ from HTTP failure semantics, and citomni/cli treats them accordingly.

The CLI error handler is responsible for handling:

uncaught exceptions
PHP errors promoted or surfaced during runtime
fatal shutdown scenarios where relevant

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

Fail-fast remains the governing principle. Recoverability should be explicit. Silent swallowing of runtime failures is not resilience; it is deferred confusion.

Configuration

CLI configuration follows the same broad CitOmni model of explicit layered composition.

Typical sources include:

vendor CLI baseline
provider CLI config contributions
application CLI base config
optional environment overlay for CLI mode

This enables command runtimes to remain predictable across environments without collapsing environment concerns into command classes themselves.

A minimal config/citomni_cli_cfg.php may look like:

<?php
declare(strict_types=1);

return [
	'identity' => [
		'app_name' => 'My CitOmni App',
	],

	// Add CLI-specific runtime settings here, such as error-handler
	// options, logging paths, or package-specific CLI configuration.
];

Environment-specific overlays can then refine operational details without contaminating the baseline.

Services

As with the rest of CitOmni, services are resolved through explicit service maps rather than runtime scanning.

That means:

predictable resolution
clear ownership
cacheable composition
lower runtime overhead
fewer surprises when debugging boot behavior

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

Providers

Providers may contribute CLI-specific metadata through the standard CitOmni boot/registry pattern.

That can include:

CLI service-map entries
CLI config overlays
CLI command registrations where applicable

This allows packages to participate in the CLI runtime without requiring the CLI package itself to know package-specific details in advance.

In other words, composition remains explicit, but it is not parochial.

Operational philosophy

citomni/cli is designed for systems that value:

low runtime overhead
explicit architecture
repeatable behavior
production sanity
composable package boundaries

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

CitOmni's position is simpler: commands should run predictably, boot cheaply, fail clearly, and respect architectural boundaries.

That is usually more useful than spectacle.

Performance notes

Use optimized Composer autoloading in production:

{
	"config": {
		"optimize-autoloader": true,
		"classmap-authoritative": true,
		"apcu-autoloader": true
	}
}

Then run:
```
composer dump-autoload -o
```
Keep vendor baselines lean
Prefer explicit service registration over dynamic discovery
Avoid putting domain orchestration directly into commands
Use OPcache in operational environments where CLI processes are frequent

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

Contributing

PHP 8.2+
PSR-4
Tabs for indentation
K&R brace style
Keep delivery-layer boundaries sharp
Keep persistence in repositories
Keep orchestration out of command adapters unless the task is genuinely trivial
Avoid framework magic
Prefer explicit behavior over implicit convenience

Coding & Documentation Conventions

All CitOmni projects follow the shared conventions documented here: CitOmni Coding & Documentation Conventions

License

CitOmni CLI is open-source under the MIT License. See LICENSE.

Trademark notice: "CitOmni" and the CitOmni logo are trademarks of Lars Grove Mortensen. You may not use the CitOmni name or logo to imply endorsement or affiliation without prior written permission. For details, see NOTICE.

Trademarks

"CitOmni" and the CitOmni logo are trademarks of Lars Grove Mortensen. You 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. Do not register or use "citomni" (or confusingly similar terms) in company names, domains, social handles, or top-level vendor/package names. For details, see NOTICE.

Author

CitOmni - low overhead, high performance, ready for anything.

citomni / cli

Maintainers

Package info

Fund package maintenance!

Statistics

Security