Hey

HEY CLI and Agent Skills

Install

npx -y skills add basecamp/hey-cli --skill hey

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its author says it does

Copied from the file, not written here

Interact with HEY email via the HEY CLI. Read and send emails, manage boxes, calendars, todos, habits, time tracking, and journal entries. Use for ANY HEY-related question or action.

SKILL.md

8.3 KB, as published. Nobody here has run it

/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:

Always use --json for structured, predictable output
Authentication required for all data commands — run hey auth login first
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 <topic_id> --json`
Reply to email	`hey reply <topic_id> -m "Thanks!"`
Compose email	`hey compose --to [email protected] --subject "Hello"`
Compose with CC/BCC	`hey compose --to [email protected] --cc [email protected] --bcc [email protected] --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 <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 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 <topic_id> --json                 # Read full email thread
hey threads <topic_id> --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 <topic_id> -m "Thanks!"             # Reply with inline message
hey reply <topic_id>                          # Reply via $EDITOR
hey compose --to [email protected] --subject "Hello"         # Compose new (opens $EDITOR)
hey compose --to [email protected] --subject "Hi" -m "Body"  # With inline body
hey compose --to [email protected] --cc [email protected] --bcc [email protected] --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 <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 to check, then hey auth login to re-authenticate.