The Semantic Boundary: Native State, Real Backends, and Honest Control

CLI-Anything's most important architectural question is not how many commands a harness exposes, but what those commands actually control. This chapter examines the boundary among the agent-facing CLI, the project's state representation, the target application's backend, and the artifact returned to the agent. The comparison between Shotcut and Blender makes the judgment concrete: one harness edits a native XML project directly, while the other uses a JSON scene description to generate a script. Both can be faithful because both preserve the authority of the real software engine.

A harness is a chain of responsibility

A useful way to understand a generated CLI is to follow one operation through the layers it crosses. The agent expresses an intention in a command. The CLI validates the request and translates it into a change to project or session state. That state is represented in a format the harness can inspect and manipulate. When the operation requires processing or rendering, the harness invokes the target backend. The backend produces an artifact or a failure. The harness reports the result, and the agent decides whether the evidence is sufficient.

These layers have different responsibilities. The command layer owns vocabulary, arguments, output format, and error reporting. The project or scene model owns the structured state the agent can query and change. The native or intermediate representation carries that state across a boundary the target software understands. The real backend owns the target-specific semantics of rendering, conversion, or execution. The verifier owns the question of whether the resulting file or output has the properties the workflow requested.

A layer can report what it knows, but it should not claim what belongs to another layer. A CLI can say that it wrote an XML or JSON project. That does not by itself prove that the target backend will interpret every field correctly. A backend can exit without an error. That does not prove that a visual effect, transition, or output format is correct. A verifier can confirm a file signature or pixel property. That does not prove that the artifact satisfies every possible user intention. The point of the boundary is to make these claims distinguishable.

classDiagram class Agent class CLIHarness class ProjectState class Representation class RealBackend class VerifiedArtifact Agent --> CLIHarness : issues commands CLIHarness --> ProjectState : reads and changes ProjectState --> Representation : serializes CLIHarness --> RealBackend : invokes Representation --> RealBackend : supplies input RealBackend --> VerifiedArtifact : produces VerifiedArtifact --> Agent : returns feedback

This model also explains why CLI-Anything describes the harness as an interface to software rather than a replacement for it. The harness owns translation and control, but the target application remains the authority for the semantics that make the output meaningful.