CLIs for Humans, APIs for Programs — Now What for Agents?

Max — Sun, 09 Aug 2026 12:05:02 +0000

I've been thinking about a shift in software interfaces.

CLIs were designed for humans. APIs were designed for programs. Now we're designing interfaces for agents.

That framing is a simplification — CLIs were always partly machine-operated, since shell scripts have driven them non-interactively for decades, which is exactly why they're a natural substrate for agents in the first place. But the emphasis is changing. We're no longer just tolerating non-human callers; we're now deliberately designing for a specific one — the agent.

The first two we've had decades to figure out. The third is still open — and it's the question this piece keeps circling: what should an interface designed for agents actually be?

There's already a lot of useful work happening around making CLIs safer, more predictable, and easier for agents to operate. I've been applying many of those ideas while redesigning the CLI for an open-source project, and the more I worked through the details, the more I started wondering whether there's another layer to the problem.

Maybe we shouldn't just make existing CLIs easier for agents to use. Maybe we should also rethink what a command is supposed to represent in the first place.

Making a CLI agent-friendly isn't the same as designing it for agents

Recent work on agent-friendly CLIs covers a lot of important ground. Zbigniew Sobiecki's Building Agent-Friendly CLIs is a great example, and the following list summarises the kind of discipline that work advocates:

structured output
stable exit codes
predictable errors
clean stdout/stderr separation
non-interactive behaviour
dry runs
idempotency
progressive discovery
machine-readable help

(Agent-facing skills usually show up alongside this work as a companion layer rather than a CLI feature per se — more on that later.)

I've been applying many of these ideas while redesigning the CLI for loomloom, a compiler that turns AI work — an author's instructions and workflow — into executable systems. But the more I worked through the details, the more I suspected we're solving only part of the problem.

Here's the distinction I keep coming back to:

Agent-friendly design asks how an agent can reliably operate an interface. Intent-first design asks whether the interface exposes the right abstraction in the first place.

Most of the work above is about the first. This piece is about the second.

Resources vs. intent

Consider a traditional resource-oriented CLI. The system exposes its domain model directly:

work create
execution get
execution retry
template publish
listing update

This is a perfectly reasonable model. The resource hierarchy tells you what exists, and commands operate on those resources.

But an agent may know the resource model perfectly and still not want to start from it. Imagine the user says:

"Run this work."

Something does have to figure out what "this work" is — resolve the identifier, decide whether it's a template, a private spec, or a market item, and create the right execution. The real question is who does that, and when the agent has to think about it. In an intent-first design the agent issues one operation:

run <work>

and the system performs that resolution underneath, as part of translating the intent. The agent doesn't have to navigate Work → Execution → Artifact just to get started.

Those resource commands become the tool the agent reaches for when it needs to observe or recover — fetch results, inspect a failure, retry deliberately:

execution get
execution retry
artifact get

So the question isn't whether agents understand resources. They often need to. The question is whether they should have to start from the resource model to do a routine thing.

Knowing the resource model vs. wanting to operate through it

This is where agent-facing skills, MCP schemas, documentation, and machine-readable help earn their place. They can teach an agent what resources exist, how they relate, which commands operate on them, what inputs are required, what outputs to expect, and which operations are safe to retry. For a complex system, that knowledge can be essential.

But there's an important distinction between knowing the resource model and wanting to operate through the resource model.

Consider a deployment system whose resource model looks like:

Application
  └── Deployment
       └── Revision
            └── Instance

An agent can understand this entire hierarchy. But when the user says:

"Deploy the latest version."

the agent might reason through something like:

find application → find latest revision → create deployment → inspect deployment → verify instances

The resource model helps the agent reason about what is happening. The intent provides a more direct way to express what should happen, including the relevant parameters and constraints, without first navigating the hierarchy:

deploy <application> --version latest

while the system resolves which application, revision, and deployment are involved underneath. The intent isn't just the verb deploy — it represents the desired operation at a higher level, while the resource model describes the concrete objects and state involved in carrying it out.

That points at three conceptual layers:

        Agent
          │
          ▼
   Knowledge layer      what exists / how the system works
   (skills, MCP, schema)
          │
          ▼
   Intent layer         what the agent wants to accomplish
   (run / deploy / verify)
          │
          ▼
   State layer          what actually exists and what happened
   (application / revision / deployment / instance)

The intent usually traces back to a human goal, but the agent is the one expressing it at this boundary — and it adds operational intents of its own (quote, watch, retry) that the human never spelled out.

The interesting design question is how these layers should interact — and, in particular, which one the agent should enter from.

Resource-oriented interfaces are still valuable

It would be easy to dismiss resource-oriented design as legacy baggage — an artifact of software built before agents existed. It is older than agents; that part is true. But being old isn't the same as being obsolete, and two things keep it relevant.

First, resources expose state, and agents need state. Second, the model has been refined across generations of API and CLI design, which makes it flexible enough to carry into the agent era.

An agent recovering from a failed operation may need to know what was created, what state it's in, which execution failed, which inputs were used, what artifacts exist, what version actually ran, and whether a retry is safe. Those are resource-level questions.

A high-level command such as retry is convenient, but eventually the agent needs to understand what exactly is being retried and why. Resources are also how the agent sees state during normal operation — fetching results and checking status are resource reads too, not just break-glass moves. That combination — routine observation plus a lower-level control surface for when automation goes wrong — is why I don't want to throw them away.

Why intent-oriented interfaces are attractive

The real problem isn't resources — it's leaky resources. Exposing every internal object directly tends to expose the system's implementation model rather than its domain. Resource-oriented interfaces can even offer high-level operations — kubectl apply deploys an app without making you hand-create a ReplicaSet, then a Pod. So the enemy was never resource orientation. It's when the interface leaks internal distinctions the caller shouldn't have to resolve.

That's exactly what I ran into with the existing loomloom CLI. A walk of the built binary counted 17 top-level command groups and 67 leaf commands — but the count isn't really the problem. The problem is semantic fragmentation: running a single AI work was spread across six different commands, depending on the resource —

template submit-file
run execute
template-spec submit-workbook
template-spec run
market run
market workbook run

— and lifecycle verbs were renamed per group (validating a work is validate-file / validate / validate-workbook; estimating its cost is precheck-file / precheck / precheck-workbook / quote). A large CLI isn't necessarily bad. A CLI that makes one user intent choose among several internal execution paths is. Those are internal distinctions the caller shouldn't have to care about.

For a human, that's a learning problem. For an agent, it's a decision problem. The agent doesn't just need to know "how do I execute this?" — it also has to figure out "which of these execution paths corresponds to what I want?" That's unnecessary decision-making — every extra branch is another chance to pick the wrong path, read more documentation, or recover from a failed attempt.

Neither is acceptable for a project as ambitious as loomloom. It's built to run large, parallel batches rather than one task at a time, and at that scale both costs compound — the learning friction across every new user, and the per-task decision overhead across every task in a run — so a small cost per task becomes a large one across the workload.

The loomloom intent-first CLI RFC (RFC-0001) proposes organising the surface around intent rather than internal resources, and the command-model RFC (RFC-0002) makes that concrete:

loom run quote <work> ...
loom run start <work> ...
loom run watch <run-id>
loom run results <run-id>

Instead of requiring the user or agent to first know whether something is a template, template-spec, or market object, the CLI resolves the appropriate underlying type when it can do so safely. The user or agent says what they want to do; the CLI handles more of the translation. For example, loom run start <work> will resolve the work's type and validate its input on its own, but it won't cross the paid boundary without an explicit --yes.

This isn't about hiding those distinctions forever. An experienced user or agent will eventually care whether something is a template, a spec, or a market item — and will want that control when they need precision. It's about deferring the distinction. Someone trying loomloom for the first time should be able to run a work and see a result before they've learned the taxonomy. For a young project, that gap — between "installed it" and "got something to happen" — is often what decides whether anyone comes back.

That sounds attractive — and within limits, it is. But push that same helpfulness too far and it starts to create a new problem of its own.

The danger of being too helpful

If we're designing for agents, why not go further? Why not let loom run <work> automatically identify the work, select the version, estimate the cost, start the execution, watch it, retry failures, optimise model selection, and converge on the desired result?

At that point it looks less like a CLI and more like an intent interface. There's interesting prior art here in Intent-Based Networking: express a desired outcome, translate it into concrete operations, activate it, continuously verify the result, and remediate when the system drifts. That model is surprisingly relevant to agent-operated software.

But there's a catch. In networking, autonomous remediation is often exactly what you want. In a CLI that an AI agent controls, autonomous remediation might mean spending more money than the user intended — a very different failure mode, especially in production workflows where many tasks run in parallel:

100 tasks running
      ↓
20 fail
      ↓
automatic retry
      ↓
some failures were actually permanent
      ↓
20 additional executions / API calls

A retry policy that looks harmless for a single task can become surprisingly expensive when multiplied across a batch. That matters particularly for loomloom, which is optimised to run AI work as potentially large, parallel workloads rather than completing one task and stopping. It gets there by compiling each workflow into a fixed execution graph ahead of time — buying structural determinism (a predictable execution shape, plus the parallelism and cost optimisation the runtime can schedule for you) rather than leaving control flow for an agent to improvise. The graph is fixed; the model steps inside it stay semantically stochastic. That's a deliberate trade — structural determinism for performance and reliability, without pretending the outputs are deterministic too — and it's exactly why retry policy has to be handled carefully at batch scale.

Where I currently draw the line

The interesting part of this design isn't "intent-first wins." It's figuring out where intent should stop and explicit control should begin.

I'm experimenting with a simple principle:

Assisted intent, gated at the wallet.

Let the system do as much safe inference as possible before an operation becomes consequential, but make meaningful cost or mutation boundaries explicit:

intent → check / quote → explicit approval → start → watch → results

The system can infer things that are safe to infer: what type of work an ID refers to, the input format, configuration from the normal resolution chain, and a stable identity for the logical operation so a retry can be recognised as the same request. But it should not silently infer things that spend money or mutate remote state.

It's worth being honest about what this costs. Intent-first doesn't delete the resource model — it relocates responsibility for it. The caller stops navigating types; the system takes over resolution — ambiguity, precedence, version selection, defaults, authorisation. A good intent interface doesn't so much hide the resource model as take responsibility for resolving it, which is why resolve safely or fail loudly matters more than resolve cleverly.

So loom run quote ... can calculate what will happen, while loom run start ... --yes is an explicit activation boundary. An ambiguous work type should fail rather than silently pick one. And a failed paid operation should not automatically retry itself and potentially charge the user again.

This is where the design became concrete for me. For long-running or parallel workloads, an agent may not know whether a previous request actually reached the backend — a timeout can happen after the server has already accepted the work. If the agent simply resends, it could create a second execution. The standard fix is idempotency: associate the request with a stable identifier so the backend can recognise repeated submissions of the same logical operation and handle them consistently instead of blindly creating another one. The key distinction:

The system can make a retry safe without deciding that a retry should happen.

The agent or user still decides whether to retry. This is where intent-first and agent-native design start pulling in different directions: intent-first leans towards doing more for the caller — infer, automate, converge — while agent-native leans towards determinism and explicit control, so the agent can see what happened and decide the consequential steps itself. Auto-retry is exactly the "helpful" automation the first favours and the second resists.

Agent-native doesn't mean fully autonomous

Much of the recent thinking about agent-friendly CLIs focuses on making operations predictable, scriptable, and safe to retry. That makes sense — agents need deterministic interfaces and clear mutation boundaries, especially when they operate software without a human watching every command.

But it raises a question: if we're making software easier for agents to operate, how much autonomy should we actually give the agent? There's a tempting direction — agent-native = hide complexity + let the agent do everything — and I'm not sure that's the right endpoint. An agent needs abstraction, but it also needs to know what will happen, what happened, what failed, what it can safely retry, what requires approval, and how to recover.

That's why RFC-0002 deliberately keeps the individual stages available:

run check
run quote
run start
run watch
run results

while still making the higher-level intent obvious. Note that this is more commands, not fewer — intent-first doesn't mean command-minimal, it means decision-minimal: the agent faces one obvious path per goal rather than a menu of internal execution routes. The agent can take the convenient path when appropriate without losing access to the underlying control surface. In other words:

Hide the implementation model, not the operational state.

One clarification on "deterministic," since it's easy to overclaim: an intent like run start isn't deterministic across time — --version latest may resolve differently tomorrow. What matters is that it's deterministic given the same inputs and system state, and that the agent can always inspect exactly what the intent resolved to. And that time-sensitivity is the intent being honoured, not a bug: --version latest is a request to track the latest version, so resolving it freshly each run is exactly right. Pinning it to yesterday's version would be more deterministic across time — and wrong, because it would no longer match what was asked for. The result should always follow the intent, not a frozen snapshot of it.

Two operational layers, one loop

Putting it together: the knowledge layer tells the agent what exists and how the system works, the intent layer expresses what the agent wants to accomplish, and the state layer reports what actually exists and what happened. The two things that sit between those layers — translation on the way down, observation on the way back up — are where most of the real design work lives:

              Agent
                │
                ▼
        Knowledge / skills
                │
                ▼
            Intent            run / deploy / verify
                │
                ▼
         Translation          resolve types, gate cost
                │
                ▼
              State           execution / artifact / …
                │
                ▼
    Observation / recovery    inspect, decide, retry

The important part is that the agent doesn't have to start at the bottom. For common operations it can start with intent; when it needs to reason about state, recovery, debugging, or precise control, it descends into the state layer.

This resembles how people actually learn unfamiliar systems: start with the goal, then learn the underlying structure as needed. Agents work the same way — they don't just execute commands, they plan → act → observe → reason → recover → act again. The interface has to support both goal expression and state inspection. The point isn't to hide the system from the agent; it's to let the agent start at the level of abstraction it needs and go deeper when the task requires it. It's the same principle that lets a newcomer run their first work before learning the taxonomy — start where you are, go deeper only when you must — now serving the agent mid-task rather than the human on day one.

This changes what "agent-friendly" means

A CLI being agent-friendly isn't only about whether an LLM can parse its output. It's about whether the interface offers the right abstraction at the right moment:

Planning — high-level operations: search, run, publish, install
Execution — predictable, explicit transitions: quote, start, watch
Observation — structured state: get, results, status
Recovery — precise control over what happened: get run, inspect error, retry

Which suggests that "should the CLI be resource-oriented or intent-oriented?" is the wrong question. The more interesting one is:

Which abstraction should an agent use at each stage of planning, execution, observation, and recovery?

Protocol doesn't determine abstraction

You might be thinking: why not just stand up an MCP server and be done with it? But MCP — like function calling, a REST API, or an SDK — defines how an agent discovers and calls a capability. It doesn't decide what the capability should be. You can expose template submit-file, run execute, and market run over MCP just as faithfully as you can expose a single run <work>; both are valid MCP. Protocol doesn't determine abstraction.

Which is why none of this is really about the CLI. The CLI is just the concrete surface I happened to be redesigning. The real question — should an agent-facing interface hand the agent the resource model, or an intent-oriented operational surface? — sits above the protocol. Whatever the transport, something still has to decide what the agent operates on.

What I think I've settled — challenge it

Before the open questions, it's worth stating the positions this piece does commit to — plainly, so they can be argued with. I'm reasonably confident about these, which is exactly why I'd like them stress-tested:

Agent-friendly isn't the same as designed-for-agents. Parseable output is table stakes; the real question is whether the interface offers the right abstraction at each stage.
Agents shouldn't have to start from the resource model for routine work. Start from intent; descend to resources to observe and recover.
The problem was never resources — it was leaky resources that expose the implementation model instead of the domain.
Resource-oriented interfaces are still worth keeping. They're how an agent sees state, both routinely and during recovery.
Expose operational state, hide implementation. What the agent can see and act on should be the system's real state — what exists, what happened — never the internal plumbing that produced it.
Safe isn't the same as automatic. Idempotency can make a retry safe without deciding that a retry should happen — the decision stays with the agent or user.
Agent-native doesn't mean fully autonomous. Agents need determinism and explicit control as much as they need abstraction.
"Resource- or intent-oriented?" is the wrong question. The useful one is which abstraction fits each stage — planning, execution, observation, recovery.

If any of these is obviously wrong — or obviously already solved — that's among the most useful things you could tell me.

This is still an open question

I'm not presenting this as solved. The loomloom RFCs are deliberately proposals for discussion. Working through them, though, I've realised these aren't all the same kind of open question.

Some I've taken a working position on — at least for loomloom — even if I'm not sure the answer generalises:

How much inference is too much? For loomloom, as much as is safe, stopping at cost or mutation boundaries — "gated at the wallet." Whether that's the right general rule, I don't know.
When should an agent be allowed to choose between resources? My current answer is not silently: an ambiguous type should fail rather than guess. But that may be too strict for lower-stakes systems.
Should intent-level commands always expose lower-level resource operations for precise control? I've argued yes, but "always" is a strong word, and I'd like to know where it breaks.
How much state should be exposed directly? My rule of thumb is operational state yes, implementation model no; the line in between is still fuzzy.
Can a CLI stay predictable while still being high-level? I think so — as long as it's deterministic given the same inputs and state, and the agent can inspect exactly what an intent resolved to. I'm less sure that holds under drift or adversarial use.

Others I genuinely don't have an answer for:

Where should CLI, API, and MCP share the same intent model?
Should an agent-facing skill count as part of the interface contract?
How do we test whether a CLI is actually easier for agents rather than merely easier to describe?
At batch scale, what's the right remediation policy when many parallel tasks fail — one where each per-task retry decision accounts for the total cost, not just per-task safety?

And an honest caveat under all of this: I'm relatively new to CLI design, and the CLI has decades of accumulated practice behind it. It's entirely possible that some of these were settled long ago and I just haven't found the answer yet. If you've built CLIs and one of these is a solved problem — or a famously hard one — I'd genuinely like to know which is which. Part of why I'm writing this is to reach the people who've been doing this far longer than I have.

And most importantly: what have people actually observed when agents operate real software?

If you've built an agent that operates a CLI, API, MCP server, or other developer tool — what abstraction worked better in practice? Did the agent benefit from higher-level intent? Did exposing resources make recovery and debugging easier? Where did abstraction help, and where did it get in the way?

I'm still working this out, and I'd love to hear what you've seen.

Disclosure: Drafted with a multi-agent assistant; direction and review are mine.

DEV Community: Max