Designing a CLI that agents can safely drive

An AI agent is only as useful as the tools it can operate. If the CLI is vague, surprising, or inconsistent, the agent starts doing the same thing a tired human does: guessing.

That is the design bar for exc. It has to be comfortable for a person at a terminal, but also structured enough that a coding agent can read the surface, make a plan, and stop when the next step is risky.

The CLI is generated from the API

The first rule is that the CLI should not drift away from the platform. exc is generated from the live API surface, so commands, flags, and help text track the backend instead of becoming a second product with its own stale contract.

That matters for agents because exc <command> --help becomes a source of truth. A model can inspect the current installed CLI before it creates anything, and it does not need to rely on a remembered flag from an old blog post.

Flags should be explicit

Agent-safe commands should not hide major decisions behind defaults.

For VM creation, that means flags like:

exc compute create \
  --name api-1 \
  --subnet_id 1 \
  --allocate_public_ipv4=true \
  --image_id 1 \
  --instance_type t1a.micro \
  --root_volume_size_gib 20 \
  --wait

The agent can show the exact command before running it. A human can read it and catch the important parts: public IP or not, which image, which type, how large the root volume is, and whether the command waits for the result.

Output should be boring

Pretty output is less important than predictable output. The agent needs to extract a VM ID, private IP, public IP, state, subnet, and zone from command results without scraping prose.

Tables are fine when they are stable and readable. JSON is better where the command is meant for automation. The important part is that output should not bury IDs inside sentences or change column meaning depending on mood.

--wait removes sleep guesses

Infrastructure is asynchronous. A VM create request returns before the machine is actually useful. Without a wait primitive, agents end up doing brittle things like sleep 30.

--wait gives the CLI ownership of the polling loop:

exc compute create ... --wait

When an older CLI or custom workflow needs manual polling, the fallback should still key off the resource state, not a fixed delay.

Dangerous verbs need confirmation

Agents should be able to inspect freely. They should not be able to destroy freely.

The Excloud skill policy treats operations like terminate, delete, release, and security group rule deletion as confirmation-gated. That is not a UI detail. It is the difference between “help me clean this up” and “quietly delete the wrong database because the prompt was ambiguous.”

The shape we want

The ideal agent flow is boring:

1. Read account state with list and get.
2. Inspect help for any command it plans to use.
3. Produce a plan with resource names, IDs, costs, and risks.
4. Ask before spending money or destroying anything.
5. Run explicit commands.
6. Report the final resource IDs and cleanup path.

That is not magic. It is just a CLI designed with enough structure that an agent does not need magic.