CLI and runtime internals

This page explains how the public mere.run command tree maps to the package internals.

Top-level flow

1. Sources/MereRunCLI/MereRunCLI.swift defines the public modality-first tree.
2. Each command in Sources/MereRunCLI/Commands parses arguments and performs small amounts of orchestration.
3. Shared CLI helpers in Sources/MereRunCLI/Support bootstrap the model store, expose the managed model registry, and provide output helpers.
4. Runtime code in MereRunCore, AudioSTT, and AudioTTS performs the inference work.

The package is intentionally organized so public command concerns do not live in the deep model code.

Model resolution path

Almost every command eventually passes through the same model-resolution layer:

• MereRunModelKit/MereRunModelPaths.swift: configured storage paths
• MereRunModelKit/MereRunModelManifest.swift: metadata and provenance
• MereRunModelKit/InstalledModelResolver.swift: location policy and lookup
• MereRunCore/ModelResolver.swift: catalog and runtime-validation adapter

That shared path is what keeps the command surface coherent across image, text, speech, vision, music, SFX, and video.

Resource ownership

Inference admission separates a server's machine reservation from its request queue. MereRunAdmission owns these coordinators and their leases. Runtime residency owns model generations, model leases, and eviction mechanics. Runtime adapters retain model construction, cache, and batching policy.

The shared transcription operation extends the typed operation boundary to file transcription and translation. CLI and API adapters resolve equivalent inputs through the same service.

CLI design conventions

The public surface follows three rules:

1. Modality-first commands

Commands are grouped by user intent:

• image
• text
• speech
• vision
• music
• sfx
• video
• model
• status
• api

2. Canonical public model IDs

The runtime uses explicit public IDs such as:

• image-klein-max
• text-chat-gemma4
• text-chat-q36-nano
• text-chat-lfm25-a1b-8bit
• text-chat-lfm25-2.6b-4bit
• text-agent-deepseek-v4-flash
• speech-tts-qwen3-nano

Docs, tests, and examples should use the canonical IDs reported by mere.run model list.

3. Quiet default output

Normal success-path runs should emit only intended user-facing output. Internal bring-up logging belongs behind the shared debug helper, not in default stdout.

Runtime family pattern

The runtime families now follow a consistent reading pattern:

• root file owns the public type and high-level orchestration
• companion files own loading, generation, decoding, support, or diagnostics

That pattern is used heavily in:

• Qwen3TTSGenerator
• LightOnOCRGenerator
• ZImageTurboGenerator
• QwenImageEditGenerator
• ACEStepPipeline
• ImageValidateCommand

Choose the CLI or runtime starting point

Start in the CLI when

• you are changing flags, help text, or output shape
• you are changing which runtime family a command dispatches to
• you are debugging how user input becomes a runtime request

Start in the runtime when

• you are changing inference behavior
• you are debugging loading, decoding, or generation internals
• you are working inside one modality family already

Contributor reading sequence

1. Read the repository tour.
2. Read the architecture map.
3. Read one command file in Sources/MereRunCLI/Commands.
4. Read the matching runtime family entry point.
5. Read the related tests in Tests/.