Disclosure: This article was generated with AI and reviewed against the source transcript and the primary documentation linked below.
A command finishes with exit code zero. Somewhere on disk, a file may have changed. The next step in the workflow still needs to know which file, what operation occurred, and whether the result can be opened.
That missing information becomes especially costly when software agents operate the commands. A successful invocation can be mistaken for a successfully completed task unless the interface makes the distinction visible.
A Signal Coders video about CLI-Anything explores command-line interfaces for applications and emphasizes inspectable results, operating guidance, and tests. The project’s primary repository also publishes harness and testing documentation. This article draws a design lesson from those sources; it does not certify any particular harness as installed, supported, or reliable in your environment.
Define the result as an artifact
Imagine a hypothetical command that exports a diagram from a desktop application. Reporting only “export complete” leaves several questions unanswered. Which project was open? Which export settings were used? Where is the output? Did the application produce an empty file?
A useful result record would identify the input project, requested operation, output path, observed file size, and checks that actually ran. The record should also distinguish a newly produced file from one that already existed before the command.
That is a proposed interface design, not evidence that every application can provide all those fields. When a field cannot be established, the command should say so rather than manufacture it.
The goal is to give the next operator enough information to locate the artifact and understand the limits of the result.
Separate execution from verification
Exit status can report whether a command completed its own defined procedure. A separate inspection can determine whether its output satisfies the user’s request.
For the diagram export, finding a nonempty file is one observation. Opening it and inspecting the expected page is another. Checking that the labels remain readable at the intended delivery size is another still.
The tool should report each observation at the level it actually supports. It should not call a diagram “approved” because the export process returned successfully.
Keep the verification proportionate to the task. A quick preview may resolve a layout concern, while a change to the application’s underlying data could require a different check. The interface should help the operator choose the appropriate evidence.
Make interruption a defined outcome
Suppose the application accepts the export request but the connection closes before the tool receives confirmation. Automatically submitting the same request again could create a second output or overwrite a result that already exists.
A better design records the attempt before execution and preserves enough identity to inspect what happened afterward. The next action is reconciliation: check the actual application or output location and decide whether the original attempt completed.
This is particularly relevant to commands that mutate existing documents. They should identify their target and the intended effect before acting, then retain a concise result afterward. Any supported recovery procedure needs the same specificity.
An uncertain result should remain uncertain until an observation resolves it. Restarting a client is not evidence that the previous operation failed.
Document a complete workflow
Help output explains available arguments. An operating guide explains how those arguments fit into a real task: discover the target, inspect current state, perform the bounded action, verify the result, and preserve the handoff.
The guide should explain what the tool cannot currently observe. If an operator must inspect the application’s preview, make that dependency explicit. If a command requires a particular application version, record the version that was actually tested.
Tests are useful evidence about the cases they cover. A published test count by itself does not establish that a new environment, document, or operation behaves correctly.
Before exposing another command to an agent, write its expected result record and its uncertain-outcome behavior. An interface becomes easier to trust when it helps an operator determine what happened after the command was issued.