CLIENT / PROCESS CONTRACT

Designed to be scripted

Human output can improve. Machine behavior is governed by a public process contract, versioned JSON Schema, compatibility fixtures, and explicit exit semantics.

Streams do not mix

stdout

In --json mode, exactly one UTF-8 JSON value followed by one newline. No ANSI sequences, banners, spinners, hints, or text before or after it.

stderr

Progress, loading state, deprecation warnings, human errors, and optional safe verbose diagnostics. Programs should not parse it as a data format.

heyfood item "pad thai" --restaurant "Pismo's" --json   | jq '.status'

heyfood --verbose doctor --json 1>result.json 2>diagnostics.log

Exit semantics

Code	Meaning
`0`	The requested operation completed successfully.
`1`	Authentication, service, diagnostic, or incomplete runtime result.
`2`	Invalid invocation, missing local input, or local validation error.

Versioned result families

The public Draft 2020-12 schema defines stable cores for five developer-facing result families while allowing additive service fields.

safetyVerdict for item checks and agent safety results
restaurantFit for restaurant search rows
menuEvaluation for menu and household evaluations
recommendationRanking for ranked recommendations
recipeCompatibility for recipe search

Additive fields remain compatible. Removing or renaming a field, changing its meaning, or changing an enum requires a new schema version, release notes, fixtures, and migration guidance.

Verbose without data leakage

Global --verbose reports generated request IDs, method/path, selected context, status, elapsed time, and named refresh or retry events. The reporter drops request bodies, query text, authorization material, keys, dietary profile contents, and phone numbers.

CLI process contract JSON Schema v1 Compatibility fixtures Security policy