/hey - HEY Email Workflow Command

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

Agent Invariants

MUST follow these rules:

1. Always use

   --json

   for structured, predictable output
2. Authentication required for all data commands — run

   hey auth login

   first
3. HTML output is available via

   --html

   for commands that return HTML content

Quick Reference

hey boxes --json

hey box imbox --json

hey threads <topic_id> --json

hey reply <topic_id> -m "Thanks!"

hey compose --to user@example.com --subject "Hello"

hey compose --to alice@example.com --cc bob@example.com --bcc carol@example.org --subject "Hello"

hey drafts --json

hey calendars --json

hey recordings 123 --json

hey todo list --json

hey todo add "Buy milk"

hey todo complete 123

hey todo uncomplete 123

hey todo delete 123

hey seen 12345

hey unseen 12345

hey habit complete 123

hey habit uncomplete 123

hey timetrack start

hey timetrack stop

hey timetrack current --json

hey timetrack list --json

hey journal list --json

hey journal read 2024-03-15 --json

hey journal write "Today was great"

hey auth status

hey auth token

hey

Decision Trees

Reading Email

Want to read email?
├── Which mailbox? → hey boxes --json
├── List emails in box? → hey box <name|id> --json
├── Read full thread? → hey threads <topic_id> --json
├── Mark as seen? → hey seen <posting-id>
├── Mark as unseen? → hey unseen <posting-id>
└── Launch interactive UI? → hey (no args, launches 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)
├── Compose new? → hey compose --to <email> --subject "Subject"
│   ├── With body? → hey compose --to <email> --subject "Subject" -m "Body"
│   ├── With CC? → add --cc <email>
│   └── With BCC? → add --bcc <email>
└── Check drafts? → hey drafts --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

hey boxes --json                              # List all mailboxes
hey box imbox --json                          # List emails in Imbox (by name)
hey box 123 --json                            # List emails in box (by ID)

Box names:

imbox

feedbox

trailbox

asidebox

laterbox

bubblebox

Response format:

hey box

{"box": {...}, "postings": [...]}

id

topic_id

name

seen

created_at

contacts

summary

app_url

topic_id

hey threads

hey reply

Email - Threads

hey threads <topic_id> --json                 # Read full email thread
hey threads <topic_id> --html                 # Read with raw HTML content

ID note:

hey box

id

topic_id

hey threads

hey reply

topic_id

app_url

https://app.hey.com/topics/123

123

Email - Reply & Compose

hey reply <topic_id> -m "Thanks!"             # Reply with inline message
hey reply <topic_id>                          # Reply via $EDITOR
hey compose --to user@example.com --subject "Hello"         # Compose new (opens $EDITOR)
hey compose --to user@example.com --subject "Hi" -m "Body"  # With inline body
hey compose --to alice@example.com --cc bob@example.com --bcc carol@example.org --subject "Project update" -m "Body"  # With CC/BCC
hey compose --subject "Update" --thread-id 12345 -m "msg"   # Post to existing thread

Email - Seen/Unseen

hey seen 12345                                # Mark posting as seen
hey seen 12345 67890                          # Mark multiple postings as seen
hey unseen 12345                              # Mark posting as unseen
hey unseen 12345 67890                        # Mark multiple postings as unseen

Takes posting IDs (the

id

hey box

Drafts

hey drafts --json                             # List drafts

Calendars

hey calendars --json                          # List calendars (returns array of {id, name, kind})
hey recordings 123 --json                     # List events in calendar

Response format:

hey recordings

{"Calendar::Event": [...], "Calendar::Habit": [...], "Calendar::Todo": [...]}

id

title

starts_at

ends_at

all_day

recurring

starts_at_time_zone

.["Calendar::Event"]

Todos

hey todo list --json                          # List all todos
hey todo add "Task description"                        # Add a todo
hey todo complete 123                         # Mark complete
hey todo uncomplete 123                       # Mark incomplete
hey todo delete 123                           # Delete a todo

Habits

hey habit complete 123                        # Mark habit complete for today
hey habit complete 123 --date 2024-01-15      # Mark complete for specific date
hey habit uncomplete 123                      # Unmark habit for today

Habit IDs can be found via

hey recordings <calendar-id> --json

Time Tracking

hey timetrack start                           # Start timer
hey timetrack stop                            # Stop timer
hey timetrack current --json                  # Show current timer
hey timetrack list --json                     # List time entries

Journal

hey journal list --json                       # List journal entries
hey journal read 2024-03-15 --json            # Read entry by date
hey journal write "Today's entry"                     # Write entry inline
hey journal write                             # Write entry via $EDITOR

Authentication

hey auth login                                # Log in (browser-based OAuth)
hey auth status                               # Check if authenticated
hey auth logout                               # Log out

If a command fails with an auth error, run

hey auth status

hey auth login