Don't rewrite your CLI for agents Microsoft for Developers
Microsoft's data shows agents handle complex CLIs with traditional args better than JSON payloads: higher correctness for smaller models, 4-11x lower cost, and fewer shell-escaping failures. The constraint of args compensates for model gaps.
Transcript
Onyx Okay, Microsoft just dropped a post that feels like it’s arguing with half the agent discourse.
Echo Right. The advice du jour is ‘just make your CLI take a --json blob so agents can speak JSON natively’.
Echo And Waldek’s like: we tested that. It’s worse.
Onyx Worse how?
Echo They built this synthetic CLI—podctl, multi-service deployments, nested config, the whole mess. Args version requires repeating --service-name to group blocks. JSON version is one clean object.
Echo Then they ran five models on both: args got five out of five correct every time, even Haiku 4.5.
Onyx And JSON?
Echo Top three models matched args. The two smaller ones—Haiku and MAI-Code-1-Flash—dropped to three and two out of five.
Onyx So smaller models can’t keep the nesting straight.
Echo Yes. But the bigger hit is cost: JSON was four to eleven times more expensive per task.
Onyx Eleven times? That’s… brutal.
Echo Retries. Every time the JSON payload fails—syntax error, wrong nesting, or the shell mangles the quotes—the agent spins up another attempt. Those retries burn output tokens, which are the priciest.
Onyx Shell escaping. Of course.
Echo PowerShell vs. Bash made it worse. Same model, same payload: nine times cost on PowerShell, one point five on Bash. The CLI args? Five cents vs. seven. Stable.
Onyx So the constraint of args actually the agents.
Echo Exactly. Args limit the input space to what --help says is valid. JSON hands the model a schema and says ‘good luck.’
Onyx And the smaller models just can’t pay the capability tax.
Echo Right. Strong models recover—eventually—but that ‘eventually’ is where the eleven-x cost comes from.
Onyx So the practical take is: don’t rewrite your CLI for agents.
Echo Unless you love paying for retries and debugging shell escaping.
Onyx But wait—what about the teams shipping agent-native tools? Like Instagui we talked about last episode.
Echo Different problem. Instagui wraps CLIs to auto-generate a GUI. It’s outside-in, no author blessing needed.
Onyx Right, and it’s self-hosted, no vendor lock-in. This is about the CLI’s format, not discovery.
Echo Yeah. Microsoft’s point is purely about the interface: args beat JSON for agent reliability and cost today.
Onyx And yet half the agent Twitter is still out here telling everyone to JSON-all-the-things.
Echo Classic.
Onyx So who care about this?
Echo Anyone building a CLI that agents will call repeatedly. The cost delta compounds fast.
Onyx And anyone using smaller models. If you’re on Haiku or Flash, args are the difference between ‘works’ and ‘maybe works if you’re lucky.’
Echo Mm-hm. And if you’re on Sonnet 5? Still four-x cheaper to stick with args.
Onyx Okay, but—what’s the angle here? If I’m selling an agent platform, am I supposed to tell customers ‘just use args’?
Echo You tell them the truth: JSON’s elegance is theoretical. Args are the boring answer that wins today.
Onyx The boring answer keeps winning. That’s such an Exploring Next take.
Echo It’s the tokenization episode all over again.
Onyx Alright. Build Next: the podctl test repo’s in the Microsoft DevBlog post—link’s below if anyone’s crazy enough to recreate it.
Onyx But the real next step is simpler: keep your args. And maybe stop giving agents so many ways to fail.