Don't rewrite your CLI for agents

Don't rewrite your CLI for agents - Microsoft for Developers

Dev Blogs

All .NET posts

.NET MAUI ASP.NET Core Blazor Entity Framework

C++ C# F# TypeScript

NuGet Servicing .NET Blog in Chinese

Microsoft for Developers Agent Framework Develop from the cloud Xcode ISE Developer TypeScript PowerShell Python Java Java Blog in Chinese Go Microsoft Edge Dev Microsoft 365 Developer Microsoft Entra Identity Developer Microsoft Entra PowerShell

Visual Studio Visual Studio Code Aspire

All things Azure Azure SDK Azure VM Runtime Team Microsoft Azure Azure Cosmos DB Azure DocumentDB Azure Data Studio Azure SQL DevOps DirectX Microsoft Foundry Power Platform

OData Unified Data Model (IDEAs)

Windows Command Line #ifdef Windows Inside MSIX MIDI and music React Native The Old New Thing Windows Developer

Waldek Mastykarz

Principal Developer Advocate

There’s advice making the rounds: replace your CLI args with a single --json payload so agents can use your tool more effectively. The thinking being, that agents already think in structured formats, and nested data maps cleanly to JSON. Flat args on the other hand, force awkward conventions like repeating --service-name to delimit multi-value groups, which is inherently ambiguous. Not to mention, that the agent needs to get the types of all values right.

It’s a reasonable hypothesis, and we wanted to know if it holds up under measurement. The data we collected, showed something interesting.

What we tested

We built a synthetic CLI called podctl that creates multi-service deployments. The scenario was deliberately complex: two services with independent configuration, three levels of nesting (services[].resources.cpu.request), arrays, mixed types, and cross-references between services. Over 30 distinct values across the deployment spec. Here’s what the args invocation looks like:

podctl create \ --name "api-gateway-prod" \ --env production \ --region us-east-1 \ --replicas 3 \ --service-name auth \ --service-image ghcr.io/acme/auth:v2.4.1 \ --service-port 8080 \ --service-protocol grpc \ --service-cpu-request 250m \ --service-cpu-limit 500m \ --service-mem-request 128Mi \ --service-mem-limit 256Mi \ --service-health-path /healthz \ --service-health-interval 10s \ --service-health-timeout 3s \ --service-health-retries 3 \ --service-env DB_HOST=db.internal \ --service-env DB_PORT=5432 \ --service-name gateway \ --service-image ghcr.io/acme/gateway:v1.8.0 \ --service-port 443 \ --service-protocol https \ --service-cpu-request 500m \ --service-cpu-limit 1000m \ --service-mem-request 256Mi \ --service-mem-limit 512Mi \ --service-health-path /ready \ --service-health-interval 15s \ --service-health-timeout 5s \ --service-health-retries 5 \ --service-env UPSTREAM=http://auth:8080 \ --service-depends-on auth \ --scaling-min 2 \ --scaling-max 10 \ --scaling-metric cpu \ --scaling-target 70 \ --rollout-strategy canary \ --rollout-canary-percent 10 \ --rollout-canary-pause 300

Notice how --service-name appears twice to start a new service block. The agent has to figure out that flags after the second --service-name belong to the gateway, not to auth. And here’s the same deployment as a JSON payload:

podctl create --json '{ "name": "api-gateway-prod", "environment": "production", "region": "us-east-1", "replicas": 3, "services": [ "name": "auth", "image": "ghcr.io/acme/auth:v2.4.1", "port": 8080, "protocol": "grpc", "resources": { "cpu": {"request": "250m", "limit": "500m"}, "memory": {"request": "128Mi", "limit": "256Mi"} }, "healthCheck": { "path": "/healthz", "interval": "10s", "timeout": "3s", "retries": 3 }, "env": {"DB_HOST": "db.internal", "DB_PORT": "5432"} }, "name": "gateway", "image": "ghcr.io/acme/gateway:v1.8.0", "port": 443, "protocol": "https", "resources": { "cpu": {"request": "500m", "limit": "1000m"}, "memory": {"request": "256Mi", "limit": "512Mi"} }, "healthCheck": { "path": "/ready", "interval": "15s", "timeout": "5s", "retries": 5 }, "env": {"UPSTREAM": "http://auth:8080"}, "dependsOn": ["auth"] ], "scaling": { "min": 2, "max": 10, "metric": "cpu", "targetPercent": 70 }, "rollout": { "strategy": "canary", "canaryPercent": 10, "canaryPauseSec": 300 }'

You can see the appeal. The JSON version makes the hierarchy explicit. Each service is a distinct object, resources nest naturally, and there’s no ambiguity about which field belongs where. On paper, this should be easier for an agent to get right.

We used two separate CLIs as the test subjects. One accepts only individual args, the other accepts only a --json payload. Both share the same validation backend and normalize to the same canonical structure. At test time, whichever variant is active gets renamed to podctl so the agent sees a consistent binary name. Since the CLI is unknown to the agent, it would have to discover the input model from scratch. For args, it means invoking the CLI’s help. For JSON, it also means invoking help but also calling an extra command that...

Don't rewrite your CLI for agents

Related Articles

(no title)

Scientists reverse brain aging, with a nasal spray

AI has torched the market for junior programmers

Al Vigier: Canada's AI strategy shouldn't include secret Palantir bills

The Anatomy of an AI-Native Org