Use when reading or managing HEY email, HEY boxes, threads, drafts, calendars, todos, habits, time tracking, or journal data with the official `hey` CLI. Covers safe read-only exploration, structured output, live ID/schema quirks, Bubble Up mail, authentication, and guarded write actions.
Use when reading or managing HEY email, HEY boxes, threads, drafts, calendars, todos, habits, time tracking, or journal data with the official `hey` CLI. Covers safe read-only exploration, structured output, live ID/schema quirks, Bubble Up mail, authentication, and guarded write actions.
Use the official basecamp/hey-cli to work with HEY mail, calendars, todos, habits, timers, and journal entries. Prefer structured CLI output over the TUI for agent work.
This skill reflects behavior verified against hey version 4a35066. If a newer binary differs, treat hey <command> --help, hey commands, and live read-only output as authoritative.
Safety Boundary
Run freely: read-only
hey auth status, hey doctor, hey config show
hey boxes, hey box, hey threads, hey drafts
hey calendars, hey recordings
hey todo list, hey timetrack current, hey timetrack list
hey journal list, hey journal read
Any --help, --version, or hey commands inspection
Read-only exploration may expose private mail or journal content. Return only what is relevant; do not dump signed stream names, private URLs, raw API objects, or unrelated content.
Require an explicit user request: state-changing
Sending: hey compose, hey reply
Mail state: hey seen, hey unseen
Todos: add, complete, uncomplete, delete
Habits: complete, uncomplete
Timers: start, stop
Journal: write
Auth/config: auth login, auth logout, auth refresh, config set
For email, show or restate recipients, subject/thread, and body before sending unless the user already supplied all fields unambiguously and directly asked to send. Never print hey auth token unless explicitly requested; it is a secret.
Installation and Embedded Agent Skill
# Source installation (Go 1.26+)
mise install
make install
# Install the official SKILL.md embedded in the binary
hey skill install
hey skill install copies the embedded skill to ~/.agents/skills/hey/SKILL.md and creates ~/.claude/skills/hey -> ../../.agents/skills/hey. It does not install a Hermes skill; this Hermes-native skill exists separately.
make install uses sudo install into /usr/local/bin. Do not run it without consent. Before rebuilding or changing PATH, check the live binary with command -v hey, hey --version, and $PATH.
Credentials normally live in the system keyring under service hey; the CLI falls back to ~/.config/hey-cli/credentials.json. HEY_TOKEN supplies a token without storing it. HEY_NO_KEYRING=1 forces file storage.
Before diagnosing data failures:
hey auth status --quiet
hey doctor --quiet
hey config show --quiet
Completion criterion: auth reports authenticated: true, expired: false, and the requested data command exits 0.
Output Modes
Mode
Behavior
Use
default / --json
JSON envelope: ok, data, summary
Human-visible status and error context
--quiet
Raw data only
Agent parsing, jq, scripts
--markdown
Markdown-ish rendering
Avoid for nested data; it may render Go map literals
--html
Raw HTML where supported
Preserve message formatting when needed
Use --quiet for parsing. Do not combine it with parsing paths that start at .data: the envelope has already been removed. Empty successful results vary: some commands return JSON null, recordings may return {}, and a box can omit .postings.
If app_url is not /topics/<id> (Paper Trail may return contact objects), do not pass it to hey threads.
Reading Mail
Discover the box with hey boxes --quiet.
List a bounded number with hey box <kind> --quiet --limit N.
Choose by sender, subject, and summary.
Derive the thread ID from app_url.
Read the full thread with hey threads <thread-id> --quiet.
hey threads <topic-id> --quiet
Verified hey threads output is an array of entries, not {entries: [...]}. Typical fields include id, created_at, creator, alternative_sender_name, summary, kind, app_url, and body.
Summaries are previews, not proof of full content. Read the thread before answering detailed questions.
Keyword search across all boxes
HEY has no full-text search CLI. Receipts, newsletters, and process mail often land in Paper Trail or The Feed, not Imbox.
Scan every box kind with --all.
Match keywords on subject + summary (+ full posting JSON if needed).
Separate process mail (for example LinkedIn InMail copies) from system mail (ATS, receipts, noreply@ domains).
"No hit in HEY" means mailbox silence only. Many automated systems never send confirmation.
for box in imbox feedbox asidebox laterbox trailbox bubblebox; doecho"=== $box ==="
hey box "$box" --quiet --all | python3 -c "
import sys,json,re
d=json.load(sys.stdin)
posts=d.get('postings') or []
keys=('thanks for applying','application received','invoice','receipt')
for p in posts:
blob=' '.join([str(p.get('name') or ''), str(p.get('summary') or ''), str(p.get('app_url') or '')]).lower()
if any(k in blob for k in keys):
app=p.get('app_url') or ''
tid=re.search(r'/topics/(\d+)', app)
print(p.get('id'), tid.group(1) if tid else None, (p.get('name') or '')[:120])
"done
Then hey threads <topic-id> --quiet for full bodies. Strip HTML lightly when summarizing.
More jq shapes: references/jq-pipeline.md.
Sending and Mail State
hey reply <thread-id> -m "Thanks — I'll review this today."
hey reply <thread-id> # opens $EDITOR
hey compose --to alex@example.com \
--subject "Project update" \
-m "The deployment is complete."
hey compose --to alex@example.com --cc sam@example.org \
--subject "Planning notes" -m "Attached are the agreed next steps."
hey seen <posting-id>
hey unseen <posting-id>
There is no verified --draft flag on compose; composing sends. Use @example.com / @example.org in examples and never send test messages to real addresses.
