Agent-First Data v0.6: The CLI Contract Got Actionable

A naming convention is useful. A working CLI pattern is better.

Agent-First Data v0.6 focused on the shape of tools agents actually run: command line programs with flags, modes, validation failures, preview paths, progress, and final results. The update made the example CLIs less like formatting demos and more like contracts an agent can copy.

The problem: agents need the next step, not just the error

A classic CLI failure gives a sentence:

unknown action: foo

That is not enough. The agent needs to know whether the command failed before work started, whether retrying makes sense, and what change would fix the call.

AFDATA errors can include a hint:

{"code":"error","error":"unknown action: foo","hint":"valid actions: echo, ping"}

The message says what happened. The hint says what to do next.

The change: examples became canonical CLI flows

The v0.6 examples across Rust, Go, Python, and TypeScript were expanded around a full CLI lifecycle:

• parse --output json|yaml|plain
• parse --log startup,query,error
• validate the requested action before doing work
• emit JSON errors to stdout
• support --dry-run as a structured preview
• return final ok or error events with the same formatter

That sounds small, but it matters for agents. It gives tool authors a copyable shape where every branch is still machine-readable.

The dry-run path: preview is an event too

Agents often need to ask, “what would this command do?” A human CLI might print a paragraph. An agent-safe CLI should emit a preview event:

{"code":"dry_run","action":"echo","log":["startup"],"trace":{"duration_ms":0}}

The preview uses the same output rules as the real result. It can be JSON for a script, YAML for a person, or plain logfmt for local scanning.

The validation path: errors stay inside the protocol

The v0.6 CLI pattern also avoids the common failure mode where argument parsing or validation escapes into terminal text.

A bad output format, unknown action, or missing configuration should become:

{"code":"error","error":"ping target not configured","hint":"set PING_HOST or pass --host","trace":{"duration_ms":0}}

That means the agent can keep reading one stream and decide whether to fix flags, set an environment variable, or ask the user.

Where this fits: every AFDATA CLI should feel predictable

The update did not add a large framework. It gave a small behavioral pattern: parse early, validate before side effects, return hints, and keep every runtime branch in the same output contract.

For agents, predictability is more important than cleverness. A CLI that fails with structured, actionable data is easier to use safely than a CLI that only prints beautiful success output.