---
title: "You're Holding It Wrong: CLIs in the Age of Agentic Harnesses"
description: "Every company is shipping a CLI for agents to drive. Almost none of them are shaped for what's about to drive them."
doc_version: "1.0"
last_updated: "2026-06-03"
canonical: "https://modiqo.ai/blog/youre-holding-it-wrong.txt"
---

# You're Holding It Wrong: CLIs in the Age of Agentic Harnesses

Every company is shipping a CLI for agents to drive. Almost none of them are shaped for what's about to drive them.

By Chetan Conikee · 2026

## The CLI gold rush

Look at what shipped in the last eighteen months. Stripe, Vercel, Cloudflare, Supabase, Neon, Turso, Railway, GitHub, PlanetScale — nearly every developer-facing company now has a CLI, and the ones that had a clunky old one are rewriting it. The polite reason is developer experience. The real one is agents.

A CLI is the lowest-friction way to let a model act on the world. Text in, text out. No SDK to import, no client object to construct, no auth ceremony the model can't perform.

Most of these tools are assembled in a weekend over an existing API. The flag grammar drifts between subcommands. The help is prose written for a human skimming a terminal. The errors are sentences, not codes. And there is no machine-readable model of how the commands relate to one another. The order you must call them in, the things that must exist first, the operations that can't run at the same time: all of it lives in the author's head and nowhere else.

## The harness evolved underneath them

The current generation of agent harnesses doesn't just plan-and-execute in one context window — it writes its own harness on the fly. Fan-out-and-synthesize, classify-and-act, generate-and-filter. Brilliant about agents. Almost nothing about the tool it is about to call.

Orchestration intelligence is compounding, and tool-shape awareness is flat at zero.

## The collision

Picture an agent migrating a customer onto a new billing provider:

    pay tx begin
    pay customer create     --email alex@acme.com
    pay subscription create --customer <id> --plan pro
    pay charge              --customer <id> --amount 4999
    pay tx commit

To a harness running fan-out-and-synthesize, this looks beautifully parallelizable. A sequential mistake is self-correcting. A parallel mistake on a stateful tool produces a race — a partial write, a silently wrong result. Some of those calls moved money. The "learn from the error and retry" reflex already did the irreversible thing.

## The hidden tax

When a CLI publishes no shape, the harness learns it by trial and error at runtime. Every guess is tokens. Every failed call is a round trip. Every re-read of `--help` is a context-window tax. And the agent does it again next session.

Discovery-by-collision is a recurring tax, and it's paid to whoever sells the tokens.

## MCP got one thing right — and one thing still wrong

MCP's tool catalog solved discovery: structured shape, up front. But the catalog is flat. It describes shape, never sequence. The thing that actually breaks transactions — ordering and parallel-safety — is unowned on both sides.

## Two ways out

Option A — publish pre-tool operational awareness over the CLI you already have. A retrofit. Describes the hazard. Fails open. Works on CLIs you don't own. This is what rote is building.

Option B — bake agent-safety into the framework CLIs are built with: machine-readable shape, idempotency keys, optimistic versioning, transactional boundaries, declarative desired-state. Removes the hazard. Fails closed. Only helps CLIs whose authors adopt it.

For state the CLI owns, Option B wins outright. For state a downstream system owns, Option B is impossible and Option A is all you've got. Description for what you can't fix; safe-by-design for what you can.

## Where I land

Both, in sequence. Description is the bridge, the framework is the destination. The published-shape standard is how you survive the messy present and the long tail you'll never get to rewrite. The agent-aware framework is how you stop generating the problem at the source.

Where do you come down — describe the tools, or rebuild the foundation they're cut from?

— Chetan