/hey

name: hey
description: |
  Interact with HEY via the HEY CLI. Read and send emails, manage contacts,
  boxes, labels, collections, calendars, todos, habits, time tracking, and journal entries. Use for ANY
  HEY-related question or action.
triggers:
  # Direct invocations
  - hey
  - /hey
  # Email actions
  - hey account
  - hey box
  - hey label
  - hey collection
  - hey set-aside
  - hey workflow
  - hey clip
  - hey snippet
  - hey search
  - hey contact
  - hey bundle
  - hey thread read
  - hey thread update
  - rename a thread
  - hey attachment
  - hey share
  - hey unshare
  - hey reply
  - hey bulk-reply
  - hey forward
  - hey compose
  - hey draft list
  - hey draft show
  - hey draft edit
  - hey draft send
  - hey draft delete
  - hey screener
  - hey watch
  - screen a sender
  - approve a sender
  - deny a sender
  # Calendar actions
  - hey calendar list
  - hey event
  # Todos
  - hey todo
  # Seen/unseen
  - hey seen
  - hey unseen
  - hey move
  - hey bubble
  - hey trash
  - hey spam
  - hey ignore
  - hey stop-ignoring
  - move email
  - bubble a thread up
  - trash email
  - mark as spam
  - ignore email thread
  - stop ignoring email thread
  - mark as read
  - mark as seen
  - mark as unseen
  - mark as unread
  # Habits
  - hey habit
  # Time tracking
  - hey timetrack
  # Journal
  - hey journal
  # Auth
  - hey auth
  # Common actions
  - check my email
  - read email
  - send email
  - reply to email
  - forward email
  - share email thread
  - turn off sharing link
  - compose email
  - list mailboxes
  - search email
  - find email
  - list contacts
  - add contact
  - edit contact
  - hide contact
  - bundle contact mail
  - unbundle contact mail
  - contact note
  - contact photo
  - find a contact by email
  - check calendar
  - add todo
  - complete todo
  - track time
  - write journal
  # Questions
  - can I hey
  - how do I hey
  - what's in hey
  - what hey
  - does hey
  # My work
  - my emails
  - my inbox
  - my imbox
  - my todos
  - my calendar
  - my journal
  # URLs
  - hey.com
invocable: true
argument-hint: "[command] [args...]"

/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, follow the one-command macOS/Codex retry in [Authentication](#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. 3. **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 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`, `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`.

hey box list --jq '.data[] | {id, name}'
hey search "quarterly planning" --jq '.data[].topic_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 on stdout. Both answer for what was read, which is the first page unless `--all` (or `--limit`) reads more, and not every listing warns on stderr that more pages exist — `hey screener list --count` is the exception and counts the whole queue. Both need list data, so they work on the listings: every `list` command, the thread listings (`hey box view`, `hey label view`, `hey collection view`, `hey set-aside view`, `hey set-aside group view`, `hey bundle view`, `hey contact threads`, `hey bubble list`), `hey workflow view`, `hey search`, `hey screener history`, `hey event day`, `hey event week`, `hey timetrack categories`, `hey attachment list` and `hey thread read` (its entries, read from the index without fetching bodies). On the thread listings they count and list the postings, not the box, label or contact around them.

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 l