Designed to be scripted
Human-readable output can change. JSON formats and exit codes are versioned, tested, and documented so scripts do not have to guess.
heyfood ask "Plan a high-protein lunch" --json | jq .Keep stdout and stderr separate
stdout
In --json mode, exactly one UTF-8 JSON value followed by one newline. No ANSI, banner, spinner, hint, or prose surrounds it.
stderr
Progress, warnings, human errors, and redacted verbose diagnostics. Programs should not parse stderr as a data format.
stdout is for data. stderr is for everything else. Your parser will thank us.
heyfood --verbose item "pad thai at Pismo's" --json 1>result.json 2>diagnostics.logJSON follows the command
| Command | JSON output |
|---|---|
ask, reply, log, item | The validated agent result, without an extra CLI wrapper. |
grocery | The list, a proposed change, a confirmation result, an export, or conflict details. |
diet list, diet show | The evidence-graded catalog or one grounded diet guide. |
agent describe, agent guide, agent schema, agent doctor | The exact self-description, guidance, schemas, and diagnostics included with the installed version. |
register | A versioned authorization result. |
| Failure | {"ok":false,"error":{"type":"...","message":"..."}}, with an optional hint and a flag when the final outcome is unknown. |
Automation does not bypass confirmation
heyfood grocery add --list-id UUID --version 7 "oats" --json > proposal.json
heyfood grocery confirm --decision accept --proposal-stdin < proposal.jsonCreating the proposal does not change the list. The signed proposal returns over stdin. If the confirmation response is lost, check the list before trying again.
Exit codes
| Code | Meaning |
|---|---|
0 | The operation completed, or the interactive TUI exited normally. |
1 | Authentication, authorization, service, cancellation, unavailable-command, or other runtime failure. |
2 | Parsing or local argument validation failed before execution. |
What is stable
- Additive JSON fields are compatible; consumers must tolerate them.
- Removing or renaming active commands, fields, enums, or exit meanings requires migration guidance.
- Human spacing, ANSI styling, and prose are not machine interfaces.
- Hidden commands from the old Python client are not guaranteed.
- Verbose diagnostics exclude authorization material, request bodies, queries, profiles, and other sensitive account data.