Hey

/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

| Task | Command | |------|---------| | List mailboxes | hey boxes --json | | List emails in a box | hey box imbox --json | | Read email thread | hey threads --json | | Reply to email | hey reply -m "Thanks!" | | Compose email | hey compose --to user@example.com --subject "Hello" | | Compose with CC/BCC | hey compose --to alice@example.com --cc bob@example.com --bcc carol@example.org --subject "Hello" | | List drafts | hey drafts --json | | List calendars | hey calendars --json | | List calendar events | hey recordings 123 --json | | List todos | hey todo list --json | | Add todo | hey todo add "Buy milk" | | Complete todo | hey todo complete 123 | | Uncomplete todo | hey todo uncomplete 123 | | Delete todo | hey todo delete 123 | | Mark as seen | hey seen 12345 | | Mark as unseen | hey unseen 12345 | | 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 | | List journal entries | hey journal list --json | | Read journal entry | hey journal read 2024-03-15 --json | | Write journal entry | hey journal write "Today was great" | | Check auth status | hey auth status | | Print access token | hey auth token | | Launch TUI | hey |

Decision Trees

Reading Email

Want to read email?
├── Which mailbox? → hey boxes --json
├── List emails in box? → hey box  --json
├── Read full thread? → hey threads  --json
├── Mark as seen? → hey seen 
├── Mark as unseen? → hey unseen 
└── Launch interactive UI? → hey (no args, launches TUI)

Sending Email

Want to send email?
├── Reply to thread? → hey reply  -m "message"
│   └── Open editor? → hey reply  (omit -m to open $EDITOR)
├── Compose new? → hey compose --to  --subject "Subject"
│   ├── With body? → hey compose --to  --subject "Subject" -m "Body"
│   ├── With CC? → add --cc 
│   └── With BCC? → add --bcc 
└── 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 
├── Uncomplete? → hey todo uncomplete 
└── Delete? → hey todo delete 

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 returns {"box": {...}, "postings": [...]}. Each posting has: id (posting ID), topic_id (topic ID), name (subject), seen (read status), created_at, contacts, summary, app_url. Use topic_id for hey threads and hey reply.

Email - Threads

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

ID note: hey box returns postings with an id (posting ID) and a topic_id (topic ID). hey threads and hey reply expect the topic ID — use topic_id directly. The app_url field also contains the topic ID as a fallback (e.g. https://app.hey.com/topics/123 → 123).

Email - Reply & Compose

hey reply  -m "Thanks!"             # Reply with inline message
hey reply                           # 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 field from hey box output).

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 returns recordings grouped by type (e.g. {"Calendar::Event": [...], "Calendar::Habit": [...], "Calendar::Todo": [...]}). Each recording has: id, title, starts_at, ends_at, all_day, recurring, starts_at_time_zone. Access by type key in jq, e.g. .["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 --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 to check, then hey auth login to re-authenticate.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: basecamp
• Source: basecamp/hey-cli
• License: MIT
• Homepage: https://www.hey.com

Install and usage instructions live in the source repository linked above.