What should an agent-native CLI expose: resources, intent, or both?

[maxaibuilds]

What should an agent-native CLI expose: resources, intent, or both?

As agents increasingly become the primary operators of software, I’ve been wondering whether making existing CLIs more agent-friendly is enough — or whether we should also rethink the command model itself.

There’s already a lot of convergence around the execution contract:

• structured JSON output
• clean stdout/stderr separation
• meaningful exit codes
• dry-run
• progressive discovery
• agent-facing skills
• side-effect declarations
• idempotency
• predictable errors and state

But there may be another question underneath all of this:

What should the command surface itself represent?

For example, an agent's goal might be:

Run this work.
Inspect what happened.
Retry the failed part.
Verify the result.

A resource-oriented CLI might expose:

work create
execution get
execution retry

An intent/operation-oriented CLI might expose:

run
inspect
retry
verify

I don't think one is necessarily better. My current hypothesis is that agents may need both.

The resource layer provides precise control, observability, and state-level reasoning. A higher-level intent/operation layer may make planning and accomplishing goals easier without requiring the agent to understand the system's internal resource model first.

This is the question I'm exploring in RFC-0002: CLI Command Model

The question

If agents are increasingly becoming the primary operators of software, should a CLI expose the system's resources, the user's intent, or both?

And perhaps the more useful question is:

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

I'm particularly interested in real-world experience rather than theoretical preference.

If you've built an agent that operates a CLI:

• What command model did you use?
• Where did it work well?
• Where did the agent get confused?
• Did you end up needing both high-level operations and low-level resource commands?
• What information did the agent need for debugging and recovery?

Please share concrete examples, even if they contradict the assumptions above.

The goal here isn't to settle on a design immediately. I'd like to collect enough real-world experience to understand what an agent-native command model should actually look like.

[cogbob]

Really interesting discussion. We’re deliberately keeping this design open while we learn from developers actually building agents.

My current instinct is that agents may need both higher-level intent/operations and lower-level resources/state — across CLI, API, and MCP — but I’d love to see that challenged by real-world experience.

If you’ve built agents that operate software through CLI, API, or MCP, what worked, what broke, and what did you end up exposing to the agent that you didn’t expect?

Concrete examples would be especially valuable.

[maxaibuilds]

I’ve been exploring the CLI redesign questions from this discussion further and wrote up a longer version of the thinking here:

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

The main question I’m trying to work through is whether an agent-facing CLI should primarily expose the underlying resource model, higher-level operational intent, or both.

For loomloom, I’m increasingly leaning toward intent as the entry point, with resources remaining important for state, observation, and recovery.

I’d be interested in feedback here, especially on whether this distinction makes sense for the command model proposed in RFC-0002.