Skip to main content

CLI Layer

CLI Layer

Public Boundary

Understand how Custy turns shell input into resolved arguments and delegated core execution.

Commandapp/cli/

Category

Architecture

Quick Command

entrypoint -> callback -> command -> resolver -> core
TyperAppContextcommand registrationRich
Installed Entrypoint
app.cli.main:app
Module Entrypoint
app/__main__.py
Framework
Typer
Shared State
AppContext

Overview​

The CLI layer owns the public command tree and converts user input into the typed values consumed by core coordinators. It should describe behavior and assemble dependencies, while Git, changelog, release, backup, cleanup, and file mutation logic remain outside command callbacks.

Entrypoints and Registration

Public Command Tree

Package Script

pyproject.toml maps custy to app.cli.main:app.

Module Execution

python -m app imports the same Typer application and invokes it.

Direct Commands

init, validate, commit, tag, push, and run are registered directly on the root application.

Command Groups

changelog, workflow, version, backup, and cleanup are registered as Typer sub-applications.

Request Lifecycle

Workflow Timeline

1
Parse global options
The root callback receives banner, help, version, dry-run, debug, and log-level input.
completed
2
Resolve global defaults
resolve_main_args applies project configuration and built-in fallbacks.
completed
3
Create shared context
AppContext stores global execution flags on the Typer context.
completed
4
Configure presentation
Logging, Rich console behavior, banner, and help are initialized before the subcommand runs.
completed
5
Resolve command arguments
The selected command builds a typed effective model from options and config.toml.
current
6
Delegate execution
The callback invokes initialization, a specialized handler, or a pipeline-backed workflow.
pending

Command Module Contract

Input Modules

options.py→Typer callback

Declare public names, aliases, validation, completion, and help panels.

Typer values→CliArgs

Collect raw command inputs without deciding final defaults.

CliArgs and ConfigLoader→resolver.py

Apply CLI -> project configuration -> built-in priority.

resolver.py→models.py

Return one typed effective argument dataclass.

Execution Modules

Resolved model→WorkflowEngineBuilder

Transport supported values into WorkflowConfig.

AppContext→Combined arguments

Carry global dry-run, debug, and logging state.

Profile names→CommandResolver

Select the internal step configuration for a pipeline-backed command.

Pipeline→Core services

Execute registered adapters through a shared GitContext.

Execution Variants

  • Most validation, Git-operation, backup, cleanup, version, changelog, and Run callbacks assemble a workflow engine and a registered pipeline.
  • custy init enters the pipeline through a specialized initialization step, which delegates to InitMain and its builder and scaffold service.
  • Branch cleanup has a specialized handler and service behind the command boundary.
  • The workflow command group is experimental and currently has a documented step-registration mismatch.

Presentation Responsibilities

The CLI layer uses app/ui, app/theme, and app/utils/logging.py for the shared Rich console, panels, progress, exception rendering, banner, colors, and rotating logs. Core pipeline and initialization modules also call some of these presentation helpers, so terminal presentation is currently shared across the CLI and orchestration layers rather than isolated behind one interface.

Continue

Related Commands

Commands commonly used together with this command.

Core Layer

See where command callbacks delegate business behavior.