/hey - HEY Email Workflow Command

CLI for HEY: mailboxes, labels, collections, email threads, contacts, replies, compose, calendars, todos, habits, time tracking, and journal entries.

Agent Invariants

MUST follow these rules:

Choose the right structured output — use --jq '<expression>' to filter or extract fields and --json for the full response. Never pipe to an external jq; --jq is built in and implies --json.
Reuse stored authentication — run the requested data command; it uses stored credentials and refreshes expiring OAuth tokens automatically. If it returns an auth error, follow the one-command macOS/Codex retry in Authentication before you report the task as blocked. Use hey auth status --json when an explicit authentication check is needed (it reports stored credentials and does not contact HEY). Never run hey auth login unattended; use it only for interactive recovery with the user present.
HTML output — --html writes the original HTML of hey thread read, hey journal read, and a contact's private note (hey contact show or hey contact note show) to a pipe or file; a terminal is refused
Linked mail accounts share one login — use hey account list --json, then --account <id|all> when a task must target one account
Local HEY configuration requires human trust — never run hey config trust-local without the user's explicit approval

Output Filtering

--jq filters the full JSON success envelope, so result data is under .data. String results print as plain text; objects and arrays print as formatted JSON. Use --quiet --jq when the expression should run against result data directly. Errors retain their complete structured envelope. Commands with dedicated raw output (auth token, shell-completion generate, setup, skill, tui, --version, and timetrack export without --output) reject --jq. hey watch writes one raw JSON event per line with no envelope and does not apply --jq.