--- 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 thread read - 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 - 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 - 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, 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` | | 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"` | | 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 thread

--- 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 thread read - 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 - 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 - 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, 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` | | 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"` | | 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 thread

--- 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 thread read - 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 - 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 - 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, 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` | | 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"` | | 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 thread

--- 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 thread read - 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 - 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 - 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, 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` | | 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"` | | 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 thread