basecamp/hey
| 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.
npx skills add https://github.com/basecamp/hey-cli --skill heyCLI for HEY email: mailboxes, email threads, replies, compose, calendars, todos, habits, time tracking, and journal entries.
MUST follow these rules:
--json for structured, predictable outputhey auth login first--html for commands that return HTML content| 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 |
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)
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
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>
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.
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).
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
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).
hey drafts --json # List drafts
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"].
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
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.
hey timetrack start # Start timer
hey timetrack stop # Stop timer
hey timetrack current --json # Show current timer
hey timetrack list --json # List time entries
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
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.
Take basecamp/hey from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.