CLI Architecture

The CLI is organised as a package (src/zenzic/cli/) rather than a single module. Each file owns one domain of responsibility.

---

Module Map

Module	Responsibility
_shared.py	console singleton, _ui singleton, configure_console(), and all cross-command utilities (_build_exclusion_manager, _output_json_findings, _render_link_error, etc.)
_check.py	check_app Typer sub-app + seven check * commands; private helpers re-exported from _governance.py, _target_resolver.py, and _command_setup.py
_command_setup.py	setup_command() factory — consolidates repo-root discovery, config loading, target resolution, and exclusion-manager construction used by all check commands
_clean.py	clean_app Typer sub-app + clean assets command
_config_explain.py	explain command + config genealogy / rule introspection surface
_governance.py	config_app Typer sub-app + governance profile commands + per-file-ignore and directory-policy filter helpers (_apply_per_file_ignores, _apply_directory_policies)
_guard.py	guard_app Typer sub-app + scan / init commands for the fast secret guard
_inspect.py	inspect_app Typer sub-app + capabilities, codes, and routes commands
_lab.py	lab command + interactive scenario showcase
_metadata.py	Single source of truth for root help panels, command grouping, and short help text
_standalone.py	score, diff, and init commands + their private helpers
_target_resolver.py	_resolve_target() and _apply_target() — path lookup and config-patching helpers shared by check commands and the lab command
__init__.py	Public re-export surface consumed by main.py — do not add logic here

main.py is the unified Typer registration factory. New top-level commands and sub-apps must be registered there, and root help metadata must stay aligned with _metadata.py.

---

The Visual State Manager

_shared.py is the sole owner of all console and UI state. This is the most critical architectural rule in the CLI layer:

PROHIBITION: No command module may instantiate Console() or a custom UI class directly. All output must go through get_ui() and get_console() from _shared.py.

# ✅ Correct — in any _check.py / _clean.py / _standalone.py command
from . import _shared
_shared.get_ui().print_header(__version__)
_shared.get_console().print("output")

# ❌ FORBIDDEN — never do this in a command module
from rich.console import Console
from mypackage.ui import LegacyInterfaceV1
console = Console(...)          # breaks shared state
ui = LegacyInterfaceV1(console) # creates an orphaned instance

For the design rationale behind UI state sharing, see ADR 004 — Unified Console State.

UI output conventions:

• Always use ZenzicPalette.DIM for dim/secondary text — never the raw Rich tag [dim].
• Vertical spacing: compact (Ruff-style). No blank lines between individual footer lines. Use Rule() separators only to divide major report sections.
• New symbols must be added to _EMOJI in zenzic/core/ui.py before use — never inline Unicode literals.

---

Adding CLI Commands

For step-by-step instructions on how to add commands or new sub-apps to the CLI, see Writing a New Check — CLI Wiring.

---

Exit Codes

The CLI exits with one of four codes. These are frozen — do not add new exit codes without an explicit architecture decision:

Code	Meaning
0	All checks passed
1	Quality issues found
2	SECURITY — leaked credential detected
3	SECURITY — system-path traversal detected

PLUGIN_FORBIDDEN_EXITS enforces that third-party adapters cannot emit exit codes outside this set. See the Adapter API reference for the full contract.