hey

# /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:** 1. **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`. 2. **Reuse stored authentication** — run the requested data command; it uses stored credentials and refreshes expiring OAuth tokens automatically. If it returns an auth error, report the task as blocked. Use `hey auth status --json` when an explicit authentication check is needed. Never run `hey auth login` unattended; use it only for interactive recovery with the user present. 3. **HTML output** is available via `--html` for commands that return HTML content 4. **Linked mail accounts share one login** — use `hey account list --json`, then `--account <id|all>` when a task must target one account 5. **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`, `completion`, `skill`, `tui`, and `--version`) reject `--jq`. ```bash hey box list --jq '.data[] | {id, name}' hey search "quarterly planning" --jq '.data[].id' hey box list --quiet --jq '.[].name' ``` An empty result is an empty array rather than `null`, so `.data[]` is safe to run against a listing that found nothing. For the two commonest shapes there is no need for an expression at all: `--ids-only` prints one ID per line and `--count` prints a bare number, both on stdout with any pagination notice on stderr. Both need list data, so they work on `hey box list`, `hey box view`, `hey label list`, `hey label view`, `hey collection list`, `hey collection view`, `hey workflow list`, `hey workflow view`, `hey clip list`, `hey snippet list`, `hey draft list`, `hey search`, `hey contact list`, `hey screener list`, `hey screener history`, `hey calendar list`, `hey event list`, `hey event day`, `hey event week`, `hey todo list`, `hey habit list`, `hey timetrack list`, `hey journal list` and `hey attachment list`. On `hey box view` they count and list its postings, not the box itself. ## Quick Reference | Task | Command | |------|---------| | List linked mail accounts | `hey account list --json` | | List sender addresses and IDs | `hey account senders --json` | | Set default mail account | `hey account use <id\|all>` | | Run once for one account | `hey --account <id> box list --json` | | Review trusted local settings | `hey config trusted-locals --json` | | Trust this repository's settings | `hey config trust-local` (requires explicit user approval) | | List mailboxes | `hey box list --json` | | List emails in a box | `hey box view imbox --json` | | List labels | `hey label list --json` | | List emails with a label | `hey label view <label_id> --all --json` | | Add a label to a thread | `hey label add <id> --to <label_id>` | | Create and add a label | `hey label create "Travel receipts" <id>` | | Remove labels | `hey label remove <id> --from <label_id\|all>` | | List collections | `hey collection list --json` | | List collection threads | `hey collection view <collection_id> --all --json` | | Create a collection | `hey collection create "Kitchen remodel"` | | Update a collection | `hey collection update <collection_id> --name "Kitchen renovation"` | | Add a thread to a collection | `hey collection add <topic_id> --to <collection_id>` | | Remove a thread from a collection | `hey collection remove <topic_id> --from <collection_id>` | | List Set Aside threads with their group | `hey set-aside view --all --json` | | List Set Aside groups | `hey set-aside group list --json` | | List a group's threads | `hey set-aside group view <group_id> --json` | | Gather threads into a new group | `hey set-aside group create <id> <id>` | | File threads into a group | `hey set-aside group add <id> --to <group_id>` | | Take threads out of their group | `hey set-aside group remove <id>` | | Break a group up | `hey set-aside group delete <group_id>` | | List workflows | `hey workflow list --json` | | View workflow stages | `hey workflow view <workflow_id> --json` | | List clips | `hey clip list --json` | | List snippets | `hey snippet list --json` | | Search email | `hey search "quarterly planning" --json` | | List search filters | `hey search filters --json` | | List contacts | `hey contact list --json` | | View contact | `hey contact show <id> --json` | | Add contact | `hey contact add --name "Jane Doe" --email jane@example.com` | | Edit contact | `hey contact update <id> --name "Jane Dawson"` | | Hide contact | `hey contact hide <id>` | | Show contact again | `hey contact show-again <id>` | | Bundle a contact's mail | `hey contact bundle <id>` | | List a contact's mail separately | `hey contact unbundle <id>` | | Read private contact note | `hey contact note show <id> --json` | | Set private contact note | `hey contact note set <id> "Prefers email"` | | Delete private contact note | `hey contact note delete <id>` | | Read email thread | `hey thread read <topic_id> --json` | | Get a sharing link | `hey share <thread_id>` | | Turn off a sharing link | `hey unshare <thread_id>` | | Reply to email | `hey reply <topic_id> -m "Friday works for me."` | | Forward email | `hey forward <topic_id> --to alice@example.com -m "For your review"` | | Compose email | `hey compose --to alice@example.com --subject "Lunch plans" -m "Are you free Friday?"` | | Compose with CC/BCC | `hey compose --to alice@example.com --cc bob@example.com --bcc carol@example.org --subject "Kitchen remodel timeline"` | | List drafts | `hey draft list --json` (`--all`/`--page` follow the cursor) | | Draft an email for human review | `hey compose --to alice@example.com --subject "Lunch plans" -m "Free Friday?" --draft` | | Draft a reply for human review | `hey reply <topic_id> -m "Drafting this." --draft` | | Read a draft back | `hey draft show <draft_id> --json` | | Change a draft | `hey draft edit <draft_id> --to alice@example.com --subject "New subject"` | | Change a draft sender | `hey draft edit <draft_id> --from billing@example.org` | | Compose from a selected address | `hey compose --from billing@example.org --to alice@example.com --subject "Board update" -m "Numbers to follow." --draft` | | Send a draft | `hey draft send <draft_id>` | | Trash drafts | `hey draft delete <draft_id>...` | | Who is waiting in The Screener | `hey screener list --json` (clearance IDs) | | Number waiting | `hey screener list --count` | | Let a sender through | `hey screener approve <clearance_id>` | | Turn a sender away | `hey screener deny <clearance_id>` | | Who was already screened | `hey screener history --json` | | Preview a bulk reply | `hey bulk-reply preview <id> <id> --json` | | Send a bulk reply | `hey bulk-reply send <id> <id> -m "Thanks for the update."` | | Recall a bulk reply | `hey bulk-reply undo <delivery_id>` | | List calendars | `hey calendar list --json` | | List calendar events | `hey event list --json` | | Today's schedule, recurrences expanded | `hey event day --json` | | Add a calendar event | `hey event add "Design review" --starts-on 2026-09-02 --start-time 14:00` | | List todos | `hey todo list --json` | | Add todo | `hey todo add "Draft the quarterly report"` | | Complete todo | `hey todo complete 123` | | Uncomplete todo | `hey todo uncomplete 123` | | Delete todo | `hey todo delete 123` | | Wait for new mail | `hey watch --box imbox --exit-on-first` | | Follow every change | `hey watch` | | Mark as seen | `hey seen 12345` | | Mark as unseen | `hey unseen 12345` | | Move email threads | `hey move 12345 --to feed` | | Remove Reply Later | `hey move 12345 --to imbox` | | Bubble a thread up now | `hey bubble up 12345 --now` | | Bubble a thread up on a date | `hey bubble up 12345 --on 2026-09-04` | | Bubble a thread up this weekend | `hey bubble up 12345 --weekend` | | List bubbled-up and scheduled threads | `hey bubble list --json` | | Cancel a bubble-up | `hey bubble pop 12345` | | Move email threads to Trash | `hey trash 12345` | | Mark email threads as spam | `hey spam 12345` | | Ignore email threads | `hey ignore 12345` | | Stop ignoring email threads | `hey stop-ignoring 12345` | | List habits | `hey habit list --json` | | Create habit | `hey habit create "Morning strength training"` | | Edit habit | `hey habit edit 123 --days mon,wed,fri` | | Delete habit | `hey habit delete 123` | | Complete habit | `hey habit complete 123` | | Uncomplete habit | `hey habit uncomplete 123` | | Start time tracking | `hey timetrack start` | | Stop time tracking | `hey timetrack stop` | | Current timer | `hey timetrack current --json` | | List time entries | `hey timetrack list --json` | | Export completed time entries | `hey timetrack export > tracked-time.csv` (`--json` etc. need `--output`) | | Save a time tracking export | `hey timetrack export --output tracked-time.csv --json` | | List time track categories | `hey timetrack categories --json` | | Create time track category | `hey timetrack category create "Client work"` | | List journal entries | `hey journal list --json` | | Read journal entry | `hey journal read 2024-03-15 --json` | | Write journal entry | `hey journal write "Shipped the pagination fix."` (empty content removes the entry) | | Check auth status | `hey auth status --json` | | Print bearer token | `hey auth token` (refuses a `--cookie` login) | | Launch TUI | `hey tui` (Ctrl+A switches linked mail accounts) | ## Decision Trees ### Reading Email ``` Want to read email? ├── Which mailbox? → hey box list --json ├── List emails in box? → hey box view <name|id> --json ├── List labels or labeled email? → hey label list --json / hey label view <label_id> --json ├── Add, create, or remove a label? → hey label add|create|remove ├── List collections or collection threads? → hey collection list --json / hey collection view <collection_id> --json ├── Create, update, add to, or remove from a collection? → hey collection create|update|add|remove ├── See Set Aside with its groups? → hey set-aside view --all --json / hey set-aside group list --json ├── Group, regroup, or ungroup Set Aside threads? → hey set-aside group create|add|remove|delete ├── Search threads and messages? → hey search <query> --json ├── Need available refinements? → hey search filters --json ├── List or view contacts? → hey contact list --json / hey contact show <id> --json ├── Read full thread? → hey thread read <topic_id> --json ├── Get a sharing link? → hey share <thread_id> ├── Turn off the sharing link? → hey unshare <thread_id> ├── Mark as seen? → hey seen <id> ├── Mark as unseen? → hey unseen <id> ├── Move to another box? → hey move <id> --to <box> ├── Remove or unmark Reply Later? → hey move <id> --to imbox ├── Move to Trash? → hey trash <id> ├── Mark as spam? → hey spam <id> ├── Ignore future activity? → hey ignore <id> ├── Stop ignoring? → hey stop-ignoring <id> ├── Who is waiting to be screened? → hey screener list --json ├── Screen a sender in or out? → hey screener approve|deny <clearance_id> └── Launch interactive UI? → hey tui ``` ### Sending Email ``` Want to send email? ├── Reply to thread? → hey reply <topic_id> -m "message" │ ├── Open editor? → hey reply <topic_id> (omit -m to open $EDITOR) │ └── Attach files? → add --attach ./report.pdf (repeatable) ├── Reply to many threads at once? → hey bulk-reply preview <id>... first, then send │ └── Sent by mistake? → hey bulk-reply undo <delivery_id> (while the window is open) ├── Forward latest message? → hey forward <topic_id> --to <email> │ └── Add a note? → add -m "note" ├── Compose new? → hey compose --to <email> --subject "Subject" │ ├── With body? → hey compose --to <email> --subject "Subject" -m "Body" │ ├── With files? → add --attach ./report.pdf (repeatable; body is optional) │ ├── With CC? → add --cc <email> │ └── With BCC? → add --bcc <email> ├── List files in a thread? → hey attachment list <topic_id> --json │ └── Save one? → hey attachment save <attachment_id> [--output <path>] ├── Draft instead of sending (human reviews in HEY)? → add --draft to compose or reply; the answer carries the draft id │ ├── Read it back? → hey draft show <draft_id> --json │ ├── Change it? → hey draft edit <draft_id> --subject/--to/--cc/--bcc/-m (flags replace; omitted fields are kept) │ ├── Deliver it? → hey draft send <draft_id> (recipients required) │ └── Discard it? → hey draft delete <draft_id> └── Check drafts? → hey draft list --json ``` ### Managing Todos ``` Want to manage todos? ├── List todos? → hey todo list --json ├── Add todo? → hey todo add "Task description" ├── Complete? → hey todo complete <id> ├── Uncomplete? → hey todo uncomplete <id> └── Delete? → hey todo delete <id> ``` ## Resource Reference ### Email - Boxes ```bash hey box list --json # List all mailboxes hey box view imbox --json # List emails in Imbox (by name) hey box view 123 --json # List emails in box (by ID) hey box view imbox --page next-cursor --json # Continue from an earlier listing ``` Box names: `imbox`, `feedbox`, `trailbox`, `asidebox`, `laterbox`, `bubblebox`