Agent-Native CLI Design

Most CLI tools are designed for humans. Colorful output, spinners, interactive prompts, progress bars. This makes sense. Humans need visual feedback to know something is happening.

AI agents don’t.

I’ve been building CLI tools that Claude Code uses as “skills.” Small scripts it can invoke to interact with external services. After a few months of this, patterns emerged. Here’s what I’ve learned about designing CLIs that agents actually want to use.

Structured Over Pretty

Human-friendly:

✓ Found 3 podcasts matching "machine learning"
  1. Lex Fridman Podcast (847 episodes)
  2. Machine Learning Street Talk (312 episodes)
  ...

Agent-friendly:

1[
2  {"uuid": "abc123", "name": "Lex Fridman Podcast", "episodes": 847},
3  {"uuid": "def456", "name": "Machine Learning Street Talk", "episodes": 312}
4]

The agent doesn’t need checkmarks or numbered lists. It needs data it can parse, filter, and act on. Every script gets a --json flag. Tab-separated output for the default case. Still parseable, but readable in logs.

Composable Atoms

Don’t build one command that does everything. Build small pieces that chain together.

1# Bad: one god command
2podcast-tool search-and-subscribe-and-notify "Huberman Lab"
3
4# Good: composable atoms
5search.js "Huberman Lab" --json |
6  # agent decides what to do with results
7feeds.js add <uuid>
8feeds.js check

The agent is smart enough to combine primitives. It doesn’t need hand-holding. Small scripts that do one thing mean the agent can improvise.

State That Accumulates

Traditional CLIs are stateless. You pass everything as arguments every time.

Agent-native CLIs remember things:

1# Build up context over time
2guests.js add "Luke Leaman"
3guests.js add "Andrew Huberman"
4feeds.js add "Huberman Lab"
5
6# Later: "what's new for me?"
7digest.js

The agent learns what you care about. Next time you ask “any new podcast episodes?”, it already knows which guests and shows to check. No need to re-specify everything.

This is huge for reducing round-trips. One command returns everything relevant because the tool already has context.

Proactive Over Reactive

Don’t just answer the literal query. Anticipate what the agent needs next.

If someone searches for a guest’s podcast appearances, they probably want:

• Results sorted by date (newest first)
• Dates included in the output
• The podcast name, not just the episode
• Enough results to be useful (25, not 10)

Bake these assumptions in. The agent shouldn’t have to ask for sensible defaults.

The Cost Function Changed

Human CLI design optimizes for:

• Readability
• Discoverability (help text, examples)
• Visual feedback

Agent CLI design optimizes for:

• Parseable output
• Minimal round-trips
• Information density per call

Tokens are cheap. API calls are cheap. Round-trips are expensive. Each one adds latency and potential for the agent to lose context. Front-load information. Return more than asked for if it’s cheap to compute.

Practical Example

I built a podcast discovery skill. The agent can:

1. Search for episodes mentioning a person
2. Follow guests and get notified of new appearances
3. Follow shows and get new episodes
4. Digest everything into “what’s new?”

1# Agent's daily briefing
2digest.js --json --days 7

One call. Everything relevant. The agent can summarize, filter, or dive deeper as needed.

The Takeaway

If you’re building tools that AI agents will use:

• Add --json to everything
• Make small, chainable scripts
• Let state accumulate across calls
• Return more than the minimum
• Optimize for parsing, not pretty-printing

The agent is your user now. Design accordingly.