Designing What an Agent Sees After a CLI Command

CLI stands for command-line interface: a way to operate software by typing commands. A graphical interface gives people buttons to click; a CLI lets someone ask software to retrieve information, change files, or perform an operation from a terminal.

In traditional development, its clearest value is execution. Commands are direct and repeatable, can be scripted, and work well with other tools. As agents have entered the terminal, the CLI has also become an efficient way for them to call software capabilities.

There are already many discussions about agents and CLIs: efficient tool calls, the token cost of output formats, machine-readable help, and structured errors. Recently I have seen agent-engineering discussions focus more on Harness Engineering and Loop Engineering—the execution environment and the cycle of action. Context Engineering appears less often as a separate topic.

I want to approach CLI design through context. Once an agent uses a command, what it sees after that command finishes is itself something we can design.

A command’s influence does not end when it finishes

CLI design normally begins with whether a command can be called correctly: clear help, unambiguous parameters, accurate results, and appropriate exit codes.

When designing for agents, I now look one step further. The same output serves different callers in different ways. A person reads and interprets it. A script parses it according to predetermined logic. In a common agent workflow, a harness receives the CLI output, then passes the portion it retains into the next round of reasoning as an observation. The harness may filter, truncate, or reorganize it, but the CLI has already determined what information can enter that chain in the first place. To the agent, the output is both the result of the present command and the input to its next action.

When an agent calls a command, the response is helping form the next context. The current object, execution state, reason for failure, and available follow-up actions may not be known until the command runs. The CLI designer can choose which status, errors, completeness signals, and next-step entry points to return—and how to arrange them so the agent can judge what to do.

Traditional CLI output is designed primarily for the first two callers: readable for a person and parseable for a script. AWS CLI, for example, returns JSON by default and also supports YAML, Text, and Table.

An AWS CLI list-users result might look like this:

{
  "Users": [
    {
      "Path": "/",
      "UserName": "Admin",
      "UserId": "AIDA...",
      "Arn": "arn:aws:iam::...:user/Admin"
    }
  ]
}

This is good machine output. The fields are stable and can be passed to --query, jq, or another script. It prioritizes reliable, parseable data.

But returning a result in a stable structure is not the same design goal as organizing the context an agent needs next. JSON tells the agent what fields and data exist. It usually leaves the agent to decide anew which parts matter to the task, whether the result is sufficient, and what actions make sense afterward.

That difference changed the question I ask when designing a CLI. Besides “What should this command return?” I ask, “What will the agent need in order to complete its next step after seeing this result?”

In my CLI designs, if a workflow has one natural follow-up, a Next field can identify it. If several directions are reasonable, Recommendations can list them and explain when each fits. The next step need not be another command; it might be how the agent should reply to the user.

One recent case involved having an agent deliver a result using a particular template. Usually the template lives in a separate file, with AGENTS.md or another durable instruction telling the agent to read it before replying. The instruction appears at the start of a task, but the need to read the template arises many reasoning and tool steps later. The file has existed throughout; its contents only enter the current context when the agent actually reads it.

After many turns of reasoning and tool use, adherence to a persistent instruction can weaken. Long-context experiments and agent-task traces have observed such behavior; research also finds that repeating a continuing instruction in later turns can improve adherence.

Most general-purpose language models used by agents today are autoregressive Transformers: at each generation step, they predict the next token from those that came before. All tokens in context can matter, but they do not necessarily have equal influence. In 2026, researchers directly measured the influence of earlier tokens on next-token prediction scores in Pythia and Qwen2.5. Across many text positions, the median influence declined as the distance increased.

That offers a possible mechanism behind the observed behavior. Reintroducing a rule just before an agent decides what to do is often more likely to affect the next output than mentioning it only at the beginning. A command, tool call, or final answer contains multiple tokens, but generation of each starts with its first token; tokens already generated then become fresh context for those that follow.

I therefore had a relevant CLI action return Suggestions after it completed:

Suggestions:
- Before responding, read templates/task-result.md.
- Format the final response using that template.

The CLI need not repeat the whole template. It only needs to point, at the moment the agent is about to reply, to the file it should read. The agent reads it, and the template’s content enters the immediate context before the response is generated. If an output format is an inviolable machine contract, schema validation or another programmatic constraint is still needed. Suggestions address a different problem: bringing a rule the agent must understand and act on back into view at the relevant moment.

Suggestions improve the chance of a rule being used at that point, but they do not change system state. Some steps cannot be left to a hint. A program may need to bind an explicit confirmation to a state transition. Another design is to withhold a critical parameter from the initial help display and reveal the requirement when the agent actually reaches the decision point.

Suppose an agent must review a document before completing a task. The system uses task finish to end the task, but its help text does not present the --verify-docs parameter in advance.

On the first call:

task finish

The command refuses to complete and returns:

Task not finished: documentation review required.

Review:
- docs/final-check.md
- Update the document if the current task changed its contents.

Retry after review:
- task finish --verify-docs=true

The agent now has a new step: open the document, inspect it, update it if necessary, and call task finish --verify-docs=true afterward.

That failure is intentional. It is not treating an omitted parameter as a routine input mistake. It uses the blocked call to place the review requirement, target document, and retry instruction into the agent’s newest context. At the same time, the program refuses to finish the task without an explicit confirmation.

--verify-docs=true is not proof of verification; it is an explicit acknowledgment. The program ensures that the requirement is shown again and that the agent must confirm before finishing. Whether the document needs a change, and what that change should be, remains for the agent to judge from the task.

The system requires an explicit confirmation before completion without deciding the outcome of the agent’s review.

Ordinary, stable, predictable parameters should still be documented clearly in help. But a critical step that requires explicit judgment at a specific point should be discoverable through help while a runtime refusal binds its confirmation to the transition to “finished.” I call this revealing a requirement at the decision point.

Next identifies a natural follow-up. Recommendations presents several directions worth considering. Suggestions triggers the reading of a persistent rule at the relevant moment. Revealing a requirement at the decision point goes further, binding explicit confirmation to a state transition. These mechanisms have different strengths and constraints, but answer the same question: after an agent executes a command, what else should the CLI deliver to help it take the next step?

A CLI is not only an execution tool. It is a context surface for what comes next.

Turning the experience into a Skill

These ideas emerged from concrete problems I encountered while designing help text, output, errors, and next-step guidance. I eventually put them into a Skill called ai-friendly-cli-design.

Its central principle is:

A CLI command is not only an execution surface. It is a context delivery surface for the next Agent step.

Karpathy has described three coexisting software paradigms. Software 1.0 consists of explicit instructions written by people. Software 2.0 is represented by neural-network weights learned from data and training. In Software 3.0, programs begin to be written in natural language, and a large language model becomes a new kind of computer programmable through language.

Taking that Software 3.0 idea one step into runtime, natural language shapes an agent not just in its initial prompt. The context it receives while working continually shapes what it does next. CLI help, results, errors, and follow-up guidance are no longer merely software documentation or output; they participate in the design of software behavior.

When I ask Codex or another agent to help design a CLI now, I use this Skill to make it design two things together: what the command should accomplish, and what the agent calling it should see after it ends.

I once thought of the CLI as an entry point through which an agent operated software. It is also an entry point through which the software world informs the agent’s next judgment.

Translation: Codex prepared this English version from Biaoo’s published Chinese article. Biaoo developed the original CLI designs and argument.