March

What we shipped.

` wrapper HEY serves journal entries, snippets and notes in, so HTML read back can be written again without nesting. A fenced code block's language (` ```ruby `) survives the conversion for the languages HEY highlights — Ruby, Python, JavaScript, TypeScript, Go, Rust, Java, C#, C++, PHP, Swift, HTML and CSS; any other is dropped. ### Email - The Screener ```bash hey screener list --json # Who is waiting to be screened hey screener list --count # Just the number waiting (cheap) hey screener approve 91 # Let a sender through, into the Imbox hey screener approve 91 --box "The Feed" # Let them through, into another box hey screener approve 91 --seen # Deliver what they sent, marked read (see below) hey screener deny 91 92 # Turn several senders away hey screener deny 91 --spam # Turn away as spam hey screener history --json # Who has already been decided hey screener clear # Trash everything waiting, deciding no one ``` The Screener is where first-time senders wait. `hey screener list` returns **clearance IDs** — not contact IDs and not posting IDs — with the sender, what they sent, and a `topic_id` for reading the thread before deciding. `--count` is a far cheaper request than the queue and prints a bare number. Approving delivers everything that sender has waiting; denying hides it. Either is reversible with the opposite command. `--box` and `--seen` apply to one sender at a time; several IDs go through HEY's bulk endpoint, which takes neither. `--seen` reliably marks the mail read only when the sender has a single waiting thread; with several, HEY files them after answering and they can arrive unread. `--spam` marks what they sent as spam, and with a single ID also trains HEY's filter, which is harder to undo than a plain deny. **`hey screener clear` moves everything waiting to Trash** (a shared thread loses your access instead) without approving or denying anyone; those senders are screened again on their next email. It is queued, so `list` can lag briefly. Confirm with the user before running it. ### Email - Bulk reply ```bash hey bulk-reply preview 12345 67890 --json # Read-only: threads and exact recipients hey bulk-reply send 12345 67890 -m "Thanks for the update — noted." hey bulk-reply undo 98765 # Recall a delayed bulk reply ``` Takes box item IDs, which must be positive and unique. **Always run `preview` first** — it resolves each posting to the entry a reply would answer and shows the exact To/CC/BCC, so the blast radius is visible before anything sends. `send` resolves the selection again and skips threads with no replyable entry, then returns the reply count, delivery ID and delayed state, plus the undo URL and command when HEY delayed it (Undo Send on). `undo` works only within HEY's 15-second window. IDs that are not your box items are skipped: `preview` reports them in `meta.skipped_count`, and `send` with none left is a usage error. ### Email - Seen/Unseen ```bash hey seen 12345 # Mark a thread as seen hey seen 12345 67890 # Mark multiple threads as seen hey unseen 12345 # Mark a thread as unseen hey unseen 12345 67890 # Mark multiple threads as unseen ``` Takes box item IDs (the `id` field from `hey box view` output). ### Email - Moving Threads ```bash hey move 12345 --to feed # Move one thread hey move 12345 67890 --to "paper trail" # Move multiple threads hey move 12345 67890 --to imbox # Remove Reply Later from threads ``` Takes box item IDs (the `id` field from `hey box view --json`). `--to` accepts a box name, kind, or ID. Supported destinations are Imbox, The Feed, Set Aside, Reply Later, and Paper Trail. Moving to any of them but Imbox marks the threads seen, and a thread that cannot be replied to is silently not moved to Reply Later. Reply Later is a box, not an independent flag: moving a Reply Later thread to Imbox removes Reply Later, preserves its seen state, and leaves a seen thread in Previously Seen. It does not return the thread to the box it occupied before Reply Later. Bubble Up goes through `hey bubble` instead. A bundle row is refused — moving it would unbundle that sender's mail; use `hey contact bundle|unbundle `. ### Email - Bubble Up ```bash hey bubble up 12345 --now # Bubble a thread up to the top of the Imbox hey bubble up 12345 67890 --now # Bubble multiple threads up hey bubble up 12345 --on 2026-09-04 # Bubble a thread up on a date hey bubble up 12345 --tomorrow # Bubble a thread up tomorrow at 08:00 UTC hey bubble up 12345 --weekend # Bubble a thread up the next Saturday at 08:00 UTC hey bubble up 12345 --next-week # Bubble a thread up next Monday at 08:00 UTC hey bubble list # List bubbled-up and scheduled threads hey bubble pop 12345 # Cancel a bubble-up: the thread moves to the Imbox, seen ``` Takes box item IDs (the `id` field from `hey box view --json`). `hey bubble up` requires exactly one of `--now`, `--on`, `--tomorrow`, `--weekend`, and `--next-week`. `--on` takes a YYYY-MM-DD date; HEY bubbles the threads up at 08:00 UTC that day, or at 18:00 UTC when the date is today in UTC. HEY schedules in UTC, so for a reader far from UTC "morning" may be the night before or the afternoon. `hey bubble pop` does not return a thread to its original box; it moves it to the Imbox and marks it seen. `hey bubble list --json` answers two buckets: `bubbled_up`, the threads back in the Imbox after bubbling up, and `scheduled`, the threads waiting in Bubble Up — each scheduled row carries `bubble_up_schedule.bubble_up_at`, and `surprise_me` when HEY picked the time. Use `id` with `hey bubble pop`, `topic_id` with `hey thread read`. ### Email - Trash and Spam ```bash hey trash 12345 # Move one thread to Trash hey trash 12345 67890 # Move multiple threads to Trash hey spam 12345 # Mark one thread as spam hey spam 12345 67890 # Mark multiple threads as spam ``` Takes box item IDs (the `id` field from `hey box view --json`). Trashing a shared thread removes your access instead of deleting it for everyone. Marking a thread as spam moves it to Spam and trains HEY's filters. A bundle row is not a thread, so trashing or spamming one answers success and changes nothing; act on the threads from `hey bundle view` or `hey contact threads` instead. ### Email - Ignoring Threads ```bash hey ignore 12345 # Ignore one thread hey ignore 12345 67890 # Ignore multiple threads hey stop-ignoring 12345 # Stop ignoring one thread hey stop-ignoring 12345 67890 # Stop ignoring multiple threads ``` Takes box item IDs (the `id` field from `hey box view --json`). Ignoring marks a thread seen; it stays in its box, and new replies do not bring it back to your attention. While a thread is ignored, `hey unseen` has no effect on it. `hey stop-ignoring` resumes notifications but leaves the thread seen. ### Email - Watching for changes ```bash hey watch # Follow every box and calendar until interrupted hey watch --box imbox # Report one box's changes (repeatable, by name or ID); every box is followed hey watch --events added,deleted # Only these mail changes (added, updated, deleted, new, resync) hey watch --events recording_added,recording_updated # Only calendar recordings as they change hey watch --box imbox --events new # New mail only: unseen, unmuted, active since the watch began hey watch --box imbox --events new --exit-on-first # Block until new mail lands, print it, exit hey watch --exit-on-first # Wait for one change of any kind, print it, exit hey watch --timeout 30m # Give up waiting after a while hey watch --since 2026-03-15 # Report changes since then first, then follow hey watch --run-sync ./triage.sh # Run a command per change instead of printing ``` Long-running, and driven by a websocket rather than polling — never poll `hey box` in a loop when this will do. Piped or with `--json`, it writes one JSON object per change to stdout, one per line, instead of the usual envelope (at a terminal, one text line each): `{"change": "added", "at": ..., "box": {"id", "kind", "name"}, "posting_id": ..., "thread_id": ..., "new": true|false, "posting": {...}}`. Use `thread_id` with `hey thread read` (absent for a bundle row that names no single thread). `new` is on every `added` and `updated` line and says whether the posting is new mail — unseen, not muted, and active since the watch last saw the thread, or since the watch began for a thread it has not seen; the backlog `--since` reads is never new, nor is reading, muting or moving a thread, and a reply on a known thread is. Without `--since`, nothing from before the watch began is reported, save a change from up to a second before it plus however long reading HEY's clock took (that clock is read to the whole second, and taken back by the request's time); its `at` says when it happened. `--events new` selects the new ones, alone or in a union with the other three. A deleted posting carries no `posting`, `thread_id` or `new`. Three more lines describe the watch itself: `{"change": "ready"}` once every box and calendar is caught up and the subscription is live (again after every reconnect's catch-up), `{"change": "disconnected"}` when the connection drops, and `{"change": "resync", "box": {...}}` when a box changed more than the feed can list and the watch skipped ahead — re-read that box; one resync covers the whole catch-up, however many skips it takes, and comes once the box is followed again. A resync is an event of its own: reported by default (`--run-*` scripts run for it, `--exit-on-first` counts it) and left out by `--events new`, so a script for new mail never runs on one. `ready` and `disconnected` carry no `box`, are written only when no `--run-*` command is given, and never count for `--exit-on-first` — expect a `ready` line before the change it waits for. The calendars are followed too, unless `--box` or an `--events` list naming only mail changes scopes the watch to mail. A calendar line names its `calendar` (`id`, `name`) where a mail line names its box: `recording_added`, `recording_updated` and `recording_deleted` (any calendar recording — events, todos, habits and their completions, journal entries, time tracks, countdowns, day titles) carry `recording_id` and `recording_type`, and all but a deletion the `recording`; `calendar_added`, `calendar_updated` and `calendar_deleted` are calendars coming and going, and `calendar_resync` is a calendar's feed skipping ahead. To drive a command per change, choose one of two behaviours — passing both is an error. `--run-async` spawns the command and moves on, so a slow one never holds up the watch and two can overlap; `--run-sync` waits for each and runs them in order. Both get the JSON on stdin and the fields as `HEY_CHANGE`, `HEY_AT`, `HEY_BOX_ID`, `HEY_BOX_KIND`, `HEY_BOX_NAME`, `HEY_POSTING_ID` and `HEY_THREAD_ID` (or `HEY_CALENDAR_ID`, `HEY_CALENDAR_NAME`, `HEY_RECORDING_ID` and `HEY_RECORDING_TYPE` for a calendar change) — plus `HEY_NEW=1` for new mail, `HEY_NEW=0` otherwise — and both take over stdout. ### Drafts ```bash hey compose --subject "Board update" -m "Numbers to follow." --draft # save instead of sending; answers the draft id hey compose --to alice@example.com --subject "Sprint recap" -m "Shipped." --no-name-tag # leave the sender's HEY name tag off hey reply -m "Drafting this." --draft # save a reply draft, addressed like a real reply hey draft list --json # List drafts; --all and --page follow the next_page cursor hey draft show --json # The draft's editable state; body is Markdown hey draft edit --to alice@example.com # Each flag replaces its field; omitted flags keep the draft's hey draft send # Deliver now (through HEY's undo window) hey draft delete [...] # Trash drafts ``` This is the review-before-send lane: an agent prepares the email as a draft, a person reviews and sends it from any HEY app (or the agent sends it later with `hey draft send`). A draft needs no recipients until it is sent; `--draft` on `hey compose` lifts the recipient requirement. **An edit is a revision, not a patch.** The CLI reads the draft first and resends the whole of it, so an omitted flag keeps that field. `--to`/`--cc`/`--bcc` replace their entire recipient kind; an explicit empty value (`--cc ""`) clears it. Any scheduled delivery is preserved through edits. **Scheduled deliveries.** Scheduling is done in a HEY app for now; the CLI has no flag to set one (HEY's API schedules only to a whole hour). A draft scheduled in an app stays in `hey draft list` until it goes out, `hey draft show` reports `scheduled_delivery_at` in UTC like every HEY timestamp, an edit preserves the schedule untouched — refusing the rare schedule it could not keep exact rather than moving it — and `hey draft delete` trashes the draft, which stops the delivery while it stays trashed. ### Calendars ```bash hey calendar list --json # Each calendar's id and kind; name (absent on the personal calendar); owned, personal and external only when true ``` Everything a calendar holds is a recording, and each kind has its own command: `hey event`, `hey todo`, `hey journal`, `hey habit`, `hey timetrack`. Those that read a calendar's window — `hey event list`, `hey todo list`, `hey journal list` — share `--calendar`, `--starts-on`, `--ends-on`, `--limit` and `--all`. Both dates want `YYYY-MM-DD`; an unreadable one, or an `--ends-on` before `--starts-on`, is a usage error rather than an empty result. Naming only `--starts-on` moves the whole window rather than reading up to the default end. **Today is the HEY account's today.** Every command that defaults to today (`event day`/`week`/`list`, `habit list`/`complete`/`uncomplete`, `journal read`/`write`, `todo add`) works it out in the account's time zone and sends the date, so a UTC machine in the New York evening still gets the New York day. Name the date to skip the account read. With no account zone, a read uses the machine's date and says so on stderr; a write refuses — pass the date. ### Events ```bash hey event list --json # Every calendar, today through the next 30 days hey event list --calendar 123 --starts-on 2026-01-01 --ends-on 2026-01-31 --json hey event day --json # Today as HEY draws it, recurrences expanded hey event day 2026-09-02 --json # One day hey event week 2026-09-02 --json # The week that day falls in hey event add "Design review" --starts-on 2026-09-02 --start-time 14:00 --end-time 15:00 hey event add "Sarah's birthday" --starts-on 2026-09-02 # No time given, so all day hey event add "Standup" --calendar 123 --start-time 09:15 --repeat every_weekday --remind 10m hey event edit 4821 --title "Design review (moved)" hey event edit 4821 --occurrence 4821_2026-09-15 --apply-to current --start-time 15:00 --json # That day alone hey event edit 4821 --occurrence 4821_2026-09-15 --apply-to future --repeat every_week --repeat-times 8 --title "Design review (v2)" --allow-plain-notes --json hey event delete 4821 # The whole event, a series included hey event delete 4821 --occurrence 4821_2026-09-15 --apply-to current # That day alone ``` Without `--calendar`, `list` reads every calendar and `add` files on HEY's default: the first ordinary calendar the user owns that is not a subscription — never Maybe or the personal calendar. Pass `--calendar` to file anywhere else. A repeating event lists once as its series, plus a row for each day HEY has written out on its own. **"What's on my schedule today?" is `hey event day`, not `list`.** A day or a week is the span as HEY draws it: a repeating event is expanded into the occurrences inside it, each carrying that day's own times and an `occurrence_id`. A virtual occurrence has the series in `id` and `parent_id`; a day HEY has written out on its own keeps its own event ID in `id` and `recording_id`, with the series in `parent_id`. That own ID edits the day alone; deleting one day always goes through the series with `--occurrence` (below). Styled period tables that contain occurrences print `Series ID`, `Occurrence ID` and `Recording ID` beside `ID`. The period covers the calendars switched on in HEY, so `day` and `week` take no `--calendar` — only `--limit` and `--all`. **Response format:** a flat array of events. Each has `id`, `title`, `starts_at`, `ends_at` and `calendar`; `all_day` and `recurring` appear only when true, the zones only on timed events, and `description` (the notes, as plain text), `location`, `url`, `attached_entry` and `reminders` when set. Occurrences carry `parent_id` and `occurrence_id`, and in `day` and `week` a written-out day also carries `recording_id`. When HEY serves a countdown in a day or week, its event carries `countdown` with a label and start/end timestamps. A later recurring day may omit this field when HEY omits the countdown from that period. `event list` does not include countdowns. `--count` and `--ids-only` read the event array. **Editing is a replacement, not a patch.** `hey event edit` reads the event first and sends back the notes, location, link, attached email, reminders and time zones it is not changing, because HEY clears whatever a write omits. Two things still cannot survive it: notes come back as plain text, so their formatting is flattened, and a countdown is a recording of its own that the whole-event edit does not read back, so an edit removes one unless `--countdown` names it again. The event is looked for within a year either side of today and refused rather than written blind if it is not found — pass the day it starts (`hey event edit 4821 2026-09-02`) for one outside that. Every calendar is read, and `--calendar` moves the event there (`hey event edit 4821 --calendar 9102`) — a calendar you own or share, not the personal calendar or a subscription (HEY answers `not_found` otherwise). An event you cannot edit, such as an invitation, moves only onto a calendar nobody else is on, and an event on a subscription does not move at all; HEY keeps it where it is otherwise, and the edit fails with `forbidden` rather than reporting it updated (the circle, countdown and reminders it sent may still have been saved). **An id alone edits the whole series; one day of it is `--occurrence` plus `--apply-to`.** `--occurrence` takes the `occurrence_id` from `day` or `week` exactly as served (`_`, naming the series the positional id names) and `--apply-to` is required with it: `current` changes that day alone, `future` changes that day and every one after it — HEY's own two choices. `--apply-to` without `--occurrence`, any other value, a malformed or mismatched occurrence id, or `--repeat`/`--repeat-until`/`--repeat-times` with `current` are usage errors, refused before anything is read. The day is read on its own date, so leave `[date]` out or name that day. A `future` edit starts a new series and requires `--repeat` to state its complete schedule; combine a preset with `--repeat-times` or `--repeat-until` for a finite series, naming what remains from the edited day, or use `--repeat custom` without either limit to copy an existing opaque schedule. A custom rule with `COUNT` can restart its full count because HEY cannot expose how many occurrences remain. HEY accepts the new series' submitted start even when it overlaps an earlier occurrence, so choose its date and time deliberately; its last day cannot precede its first day. A virtual day of an opaque custom schedule takes its exact time from HEY's Day view and is refused if that view no longer serves it. A realized custom day is refused for `future`, because HEY does not serve the rule's authoritative occurrence boundary; split from a virtual occurrence, edit that day alone, or edit the whole series. A realized preset occurrence moved away from its series time is also refused: move it back with a `current` edit first. HEY cancels children from the moved time but truncates the parent at the occurrence identifier, so splitting directly can lose neighboring realized edits. A preset `--repeat` alone means forever. HEY gives the new series a new id, and the answer is still the day edited — read `day` or `week` again before editing it further. An occurrence edit keeps everything it is not told to change — that day's own schedule, zones, notes, location, link, attached email, reminders, circle and countdown, from the day itself where HEY has already written it out — and refuses what it cannot keep. A countdown owned by the day is read back and re-sent; an inherited series countdown stays inherited for `current` and is copied to the replacement series for `future`. Only `--countdown 0` removes it, and not from one day of a series that has one, since HEY shows the day the series' countdown regardless — use `future` or edit the series. Notes HEY serves only as plain text, so an edit that would send notes back as text is refused unless `--allow-plain-notes` accepts the loss or `--notes` replaces them; an event with no notes needs neither. A `future` edit builds the new series from the series' own guest list and sends invitations, so a day whose guests differ from the series' is refused until `--invite` names the new list. With `--occurrence`, `--calendar` is only the calendar the day moves to: the day is read over every calendar, and a day already moved elsewhere stays there. A day HEY has written out lists in `day`/`week` with its own event ID in `id` and `recording_id`, plus the series in `parent_id`; `edit ` changes that day alone. Use the series id as the positional id with `--occurrence`. **Deleting follows the same rule.** `hey event delete ` deletes the whole event, a series included. One day is `hey event delete --occurrence --apply-to current`; `future` deletes that day and every one after it, which from the series' first day is the whole series. A written-out day's own ID is refused with a usage error naming the occurrence command, because deleting that ID alone lets HEY draw the day again from the series. The check reads the event a year either side of today, so a written-out day further out than that is not caught — use the occurrence form for it. `future` is refused from a written-out day moved off its series time or on an opaque custom schedule, as for edits. An attached email you cannot read is not served and is detached by any edit, whole event or one day — nothing client-side can keep it. HEY answers not-found for a date that is not a day of the series and for a series you cannot edit alike. The JSON envelope is the one every mutation writes: `summary` (`Occurrence updated` or `Occurrence and the following updated`) and `data` holding the recording HEY answered. On `add`, no `--start-time` means all-day and a `--start-time` with no `--end-time` runs an hour — unless `--ends-on` names a later day, when it ends there at the start's clock time plus an hour; a default end that falls in the hour the clocks repeat is refused (pass `--end-time`). Clock times, and today when `--starts-on` is left out, are read in the user's HEY account time zone (the one the web app uses); pass `--time-zone America/New_York` to write in another. If a clock time or today needs the account's zone and it has none, the command refuses and asks for `--time-zone`. On `edit`, a timed event keeps the end and zone not named, and one saved without a zone stays without one; an all-day event given a time starts at 09:00 unless `--start-time` says otherwise and gets the default hour. ### Todos ```bash hey todo list --json # Todos on the personal calendar, 4 years back to 1 year ahead hey todo add "Draft the quarterly report" # Add a todo hey todo add "Book the venue" --date 2026-09-04 # With a due date hey todo complete 123 # Mark complete hey todo uncomplete 123 # Mark incomplete hey todo delete 123 # Delete a todo ``` Todo IDs must be positive; `hey todo complete 0` or a negative ID is a usage error rather than a request. `--date` wants `YYYY-MM-DD` and is validated before the request. ### Habits ```bash hey habit list --json # List habits and their IDs hey habit list --date 2026-09-02 --json # The habits in that date's week hey habit create "Morning strength training" # Create with weights, blue, every day hey habit create "Practice piano" --icon music --color green --days mon,wed,fri hey habit edit 123 --name "Evening walk" # Omitted fields remain unchanged hey habit edit 123 --days 0,6 # Sunday and Saturday hey habit delete 123 # Permanently delete habit and history hey habit complete 123 # Mark habit complete for today hey habit complete 123 --date 2026-03-15 # Mark complete for specific date hey habit uncomplete 123 # Unmark habit for today ``` Habit IDs come from `hey habit list --json`, which reads the week a date falls in. A week lists each habit once, whatever weekday it runs on; a week that has not started yet lists none. Days accept full weekday names, common abbreviations, or `0` (Sunday) through `6` (Saturday). ### Time Tracking ```bash hey timetrack start # Start timer hey timetrack stop # Stop timer hey timetrack stop --category "Client work" # Stop and file under a category (created if missing) hey timetrack current --json # Show current timer hey timetrack list --json # First page of completed tracks, most recently ended first (--all for every page) hey timetrack list --category 42 --json # Only one category, by ID hey timetrack edit 1042 --start 2026-08-22T09:00 --end 2026-08-22T11:15 hey timetrack edit 1042 --category "Client work" --notes "Invoice review" hey timetrack delete 1042 # Delete a time entry hey timetrack export > tracked-time.csv # Write the complete CSV export hey timetrack export -o tracked-time.csv --json # Save the CSV, return file metadata (--force to replace a file) hey timetrack categories --json # List categories hey timetrack category create "Client work" # Create a category hey timetrack category rename 123 "Planning" # Rename a category hey timetrack category delete 123 # Delete a category ``` `list` leaves out the running track; read it with `current`. `edit` changes only the fields it is given, takes `YYYY-MM-DDTHH:MM` in the local zone (or a full RFC 3339 instant), and completes the track, so it is for finished tracks. A category is a title: `--category` files under it and HEY creates it if missing. A blank `--category` is refused — once filed, a track can only be moved to another category. Without `--output`, `hey timetrack export` writes CSV to stdout — redirect it to a file. The output formatting flags cannot reshape a CSV, so they are refused with a usage error unless `--output` is given; with it, `--json`, `--quiet` and `--markdown` format the file's metadata (`--ids-only` and `--count` still fail, as it is not a list). `--html` is never accepted. An existing file needs `--force`. ### Journal ```bash hey journal list --json # Entries on the personal calendar, 4 years back to 1 year ahead hey journal read 2026-03-15 --json # Read entry by date hey journal read 2026-03-15 --jq '.data.content_markdown' # The entry as Markdown; write it back only if content_markdown_lossless is true (see below) hey journal write "Shipped the pagination fix and paired with Jane on the cover art." hey journal write 2026-03-15 "Retrospective: the migration took two days longer than planned." hey journal write # $EDITOR at a terminal; otherwise the entry is read from stdin ``` Content that trims to nothing — a whitespace-only argument, `--content` or stdin, or an emptied `$EDITOR` buffer — **removes** the day's entry, and the command says "removed" rather than "saved"; only do that when removal is the intent. (A literal `""` is treated as no content and falls through to stdin or `$EDITOR`.) A day with no entry is not an error: `--json` answers `ok` with the summary "No journal entry for " and no `data`. **A journal entry is written whole**, so to add to one, read it, change it and write all of it back. `hey journal read --json` answers `content` (the HTML as HEY serves it), `content_markdown` and `content_markdown_lossless`. When `content_markdown_lossless` is `true`, add to the Markdown. The read checks the flag itself and fails when it is `false` — or when the day has no entry, which answers no `data` — so nothing is written: ```bash entry=$(hey journal read 2026-03-15 --jq 'if .data.content_markdown_lossless then .data.content_markdown else error("content_markdown would drop part of this entry, or there is none: change content with --content-html") end') && printf '%s\n\nBooked the venue for the second day.\n' "$entry" | hey journal write 2026-03-15 ``` When it is `false`, the entry holds an attachment or other markup Markdown cannot carry, and writing Markdown would drop it — `hey journal write` refuses to open `$EDITOR` on such an entry for the same reason. Add to the HTML instead — `--content-html` takes off the wrapper HEY serves the entry in, so this does not nest: ```bash entry=$(hey journal read 2026-03-15 --jq '.data.content // error("no journal entry for this day")') && hey journal write 2026-03-15 --content-html "$entry

Booked the venue for the second day.

" ``` Keep the `&&`: a failed read must not go on to write. A day with no entry answers no `data`, which a bare `--jq '.data.content'` prints as `null`; the `// error(...)` makes that read fail instead, so the entry never starts with the word null. ### Authentication Data commands use the credentials HEY already stores and refresh expiring OAuth tokens automatically. Run the requested data command without a login preflight. Use `hey auth status --json` when the user asks for authentication status or when an explicit authentication check helps diagnose a failure; it reports whether credentials are available without changing them. If a data command returns exit code 3 with `"code": "auth"`, or fails with `could not read stored credentials`, authentication is unavailable to that process. On macOS under Codex, the sandbox can hide credentials that the HEY CLI stores in Keychain. Before reporting the task as blocked, use the harness's normal approval flow to retry `hey auth status --json` once with elevated sandbox permission. Limit the escalation to this one read-only command. If the response's `data.authenticated` is `true`, rerun only the exact `hey` command the user requested through a separate one-command approval. If `data.authenticated` is `false` or the status command fails, report the task as blocked and tell the user to run `hey auth login`; do not run it for them unattended. Never run the macOS `security` command to read Keychain contents, print or copy credentials, or move credentials into a file; never disable the sandbox globally; never set `HEY_NO_KEYRING=1` as an authentication workaround. Piped, machine-output and non-TTY commands do not prompt for sign-in. When an agent harness runs commands under a PTY, set `HEY_NONINTERACTIVE=1` so a missing login returns the same actionable auth error instead of opening an interactive prompt. ```bash hey auth status --json # Inspect stored authentication without changing it HEY_NONINTERACTIVE=1 hey box list # Under a PTY, even styled output never prompts hey auth login # Interactive browser recovery, with the user present hey auth logout # Log out hey login / hey logout # Shortcuts for the two above hey setup omarchy # Omarchy only: put HEY in the bar. The interactive # sign-in offer never fires for agents (non-TTY, # machine output), so this command is the way hey setup # First-run wizard: sign in + connect coding agents HEY_NONINTERACTIVE=1 hey setup --json # No prompts and no OAuth wait — but still # installs shell completions, agent skills and # the Claude Code plugin, and records onboarding; # use `hey doctor` to inspect without changes. # (Without HEY_NONINTERACTIVE, a terminal on # stdin still starts browser sign-in.) ``` Run `hey auth login` only when the user is present and explicitly asks to authenticate. ### Sender selection `account senders` lists configured sender IDs and addresses within `--account`. `compose --from ` (new messages only, not with `--thread-id`) sends directly as that sender and applies its active Name Tag unless `--no-name-tag` is set; `--draft` saves without sending. `draft edit --from` stays in the draft's account and preserves the existing body, including signatures. Replace the body explicitly when needed. `draft show` includes From. These commands do not persist a default.