# CLI Internals `internal/cli` is the production composition root. [CLI Reference](../cli.md) owns syntax, reports, and outcome codes; [Configuration](../config.md) owns settings; [Operations](../operations.md) owns physical state and recovery. This guide explains declaration, loading, and orchestration owners, not another public command manual. ## Native Application Construction [NewApplication](../../internal/cli/application.go) returns a native `*commandkit.App` from application identity and injectable options. Construction declares commands without configuration discovery, engine creation, provider calls, or run-storage allocation. The executable supplies build identity; `RunWithOptions` is a convenience execution entry point, not a manual dispatcher. The constructor wires: - native help/version and installed shell completion; - application pipeline declarations and a native run alias; - ckconfig whole-application and focused PromptKit scopes, sharing one loader; - ckprompt resource/requirements inspection, concrete request validation, prepared preview, namespace selection, and explicit smoke testing. ckconfig adapters use the original application result and focused native subtree view. ckprompt uses an engine loader through its standard builders rather than application-owned copies of inspection DTOs. Ordinary resource inspection does not become request preparation or an implicit probe. The [native CLI reference][native-cli] owns parser/report mechanics. ## Invocation-Local Loading [nativeLoaders](../../internal/cli/configkit_load.go) belongs to one invocation. It selects the main source and assembles one layered ConfigKit application result. Engine construction calls `promptkit.NewFromConfig` on that result, with runtime-only client options; it does not load YAML again. The retained selection includes supplied-value state, overlay, and override values. Repeated identical selections share a result/engine, while distinct comparison selections cannot be memoized into one side. There is no process-global loader cache. The selected main's native context anchors companion imports; source edits do not mutate an existing captured engine. [Configuration Internals](configuration.md) owns definition, normalization, origins, and conversion. Shared loaders allocate no output/cache/debug data. ## Catalog And Preflight Boundaries [catalog.go](../../internal/cli/catalog.go) composes generic, Seriatim, and D&D registrars into typed registries, codecs, evidence projectors, and validator defaults. Registration does not build an asset/schema registry or an LLM service. Injected registries/catalogs are alternative sources, not implicitly augmented with production entries. [pipeline_commands.go](../../internal/cli/pipeline_commands.go) separates: - listing: enumerate captured configured IDs without a catalog/engine; - showing: domain resolution and composition description, without profile expansion; - validating: domain resolution plus known-resource preflight, supplying the same captured engine only when model roles require it. [Preflight](../../internal/preflight/preflight.go) accepts collaborators/data; it does not load configuration, register/construct modules, read execution inputs, render CLI reports, or allocate state. Partial profiles pass native inspection, with concrete request readiness deferred until preparation. ## Run Inputs And Native Overrides [run_input.go](../../internal/cli/run_input.go) binds typed application inputs and repeated literal selections. [execution_overrides.go](../../internal/cli/execution_overrides.go) uses reusable ckprompt resource/execution inputs, preserving omission versus explicit empty/false/zero. Only profile/session and execution controls needed by pipeline runs are selected; prompt inputs stay module-owned. The resolved run-wide profile selection reaches every LLM-backed role. Native execution overrides travel through operation requests to producers, validators, and continuation, without mutating loaded settings. The [public reference](../cli.md#run-wide-llm-overrides) owns exact spellings/semantics. Reference selectors are expanded at the CLI boundary using registered target specifications. Pipeline/lane actions become exact binding changes after specificity/conflict handling. Generic resolution receives exact reference bindings/unbinds, not CLI selector grammar. External/generated conflicts and required-slot/type checks remain with domain resolution; materialization follows. [session.go](../../internal/cli/session.go) resolves the effective session from explicit supplied input or the input-module/raw-byte policy before runner work. Framework/model code transports it rather than deriving another session. ## Run Orchestration [pipeline_run.go](../../internal/cli/pipeline_run.go) performs the ordered handoff: 1. Load/validate the selected application result and derive runtime configuration. 2. Generate a safe run identity and allocate requested capture. 3. Capture selected configuration, compose registries, expand reference actions, and resolve the effective pipeline. 4. Obtain the shared engine when needed and perform offline preflight. 5. Materialize references, construct prepared typed modules, read input bytes, and resolve the effective session. 6. Construct the accepted-result cache and optional recorder collaborator, create one native execution group, and invoke the runner with independent worker and execution selections. 7. Report process diagnostics, publish returned logical files only after runner success, finalize requested capture, then submit the native completion report. Modules receive the shared engine, operation data, and explicit collaborators, not physical roots or CommandKit reporters. Detailed worker, assessment, eligibility, and cache algorithms belong in [Pipeline Internals](pipeline.md); physical publication/capture collaborators belong in [Run State Internals](state.md). Requested capture allocates before engine/preflight and finalizes once. Primary operation causes and additional capture failures remain available. Later report delivery failure does not rerun model work, remove valid artifacts, or terminalize capture again. ## Native Reporting And Outcomes [run_result.go](../../internal/cli/run_result.go) submits one small application value with a native text template. Native serializers render that same value. Domain files, not a persisted report or ledger, are the deliverables. Fallback qualification is independent of optional diagnostic visibility. Warnings/advisories keep their domain classification and use the reporter's diagnostic channel. Outcome helpers retain native configuration/preflight causes and distinguish identifiable invalid input from operational/mixed failures. CommandKit retains rendering/output/diagnostic delivery evidence separately from the operation cause; quiet mode does not mask such failures. The [completion report](../cli.md#completion-report) owns fields and [stream/outcome contract](../cli.md#output-streams-and-exit-statuses) owns process behavior. There is no universal Notarius envelope or parallel serializer. ## Focused Verification - [Application tests](../../internal/cli/application_test.go) cover lazy built-ins, shared scopes, selection evidence, and native diff outcomes. - [Loader tests](../../internal/cli/native_load_test.go) and [schema tests](../../internal/cli/native_schema_load_test.go) cover native composition, captured contexts, and operator contracts. - [Pipeline command tests](../../internal/cli/pipeline_commands_test.go) cover listing/showing/preflight without execution inputs or state. - [Override tests](../../internal/cli/execution_overrides_test.go) and [run tests](../../internal/cli/pipeline_run_test.go) cover supplied values, routing, references, sessions, and run ordering. - [Reference tests](../../internal/cli/reference_contract_test.go) cover selector specificity, generated conflicts, and materialization boundaries. - [Native executable tests](../../internal/cli/native_process_test.go) cover the real command routes and fake-provider presentations. - [Completion tests](../../internal/cli/run_result_command_test.go) and [recovery contracts](../../internal/cli/recovery_contract_test.go) cover retained publication, capture/delivery failures, reuse, fallback, and native facts. Use focused CLI tests and pair with configuration/preflight tests when those boundaries change. [Development](../development.md#validation) owns wider checks. [native-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md