hey
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.
basecamp · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add basecamp/hey-cli --skill heyAbout this skill
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:
- Choose the right structured output — use
--jq '<expression>'to filter or extract fields and--jsonfor the full response. Never pipe to an externaljq;--jqis built in and implies--json. - 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 --jsonwhen an explicit authentication check is needed. Never runhey auth loginunattended; use it only for interactive recovery with the user present. - HTML output is available via
--htmlfor commands that return HTML content - Linked mail accounts share one login — use
hey account list --json, then--account <id|all>when a task must target one account - Local HEY configuration requires human trust — never run
hey config trust-localwithout 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.
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 |