This file provides guidance to AI coding agents working with this repository.
hey-cli is a CLI and TUI interface for HEY. It allows users to read and send emails, manage their boxes, manage their calendars and journal entries. The TUI is primarily intended for human use, while the CLI is primarily intended for use by AI agents and for scripting.
This project uses make. make help covers most targets -- though not all of them:
install, check-toolchain and help itself are defined but unlisted.
make build # Builds ./bin/hey
make test # Runs the tests
make lint # Lints the code
make install # Installs the binary to /usr/local/bin/hey (not shown by make help)History is linear: merge commits are disallowed in this repository. Bring a branch up to date by rebasing it onto main, never by merging main into it.
This is a Go project that uses:
- spf13/cobra for the CLI interface
- [charm.land/bubbletea/v2] for the TUI interface along with bubbles/v2 and lipgloss/v2 (these are new versions that recently came out and differ from the v1 versions!)
All API interactions go through the HEY SDK (hey-sdk/go), with typed service methods accessed via internal/cmd/sdk.go (e.g., sdk.Boxes().List, sdk.Messages().Create, sdk.Calendars().GetRecordings). Authentication and token refresh are handled via internal/auth/.
internal/auth/ manages three methods: browser OAuth with PKCE (hey auth login, the
primary one), a stored bearer token (--token), and the HEY_TOKEN environment variable.
The Manager refreshes tokens with a 5-minute buffer, and the SDK reaches it through the
bridge in internal/cmd/sdk.go.
Every data-access command calls requireAuth() before it makes an API call. Logged out,
it exits 3 with Run: hey auth login, or offers to sign in at an interactive terminal with
styled output. HEY_NONINTERACTIVE=1 turns the offer off. The auth subcommands, hey login/hey logout, hey setup and hey doctor work without authentication.
Coding-agent setup lives in internal/harness and internal/cmd/setup_agent*.go. Every
skill write goes through claimSkillDir, which marks a directory it creates
(.managed-by-hey-cli) and refuses a populated one without the marker. Do not add a write
path that bypasses the gate.
The setup wizard, the Omarchy bar plugin and the skill refresh hook are in docs/architecture/auth-and-setup.md.
Configuration (the base URL, the default linked account, the Imbox's cover, and the onboarded flag) is stored in ~/.config/hey-cli/config.json; onboarded is read from the global file only, never from a repository's .hey/config.json. Credentials are stored in the system keyring (service name: hey) with automatic fallback to ~/.config/hey-cli/credentials.json when the keyring is unavailable. Set HEY_NO_KEYRING=1 to force file storage.
Named profiles (profiles and default_profile in the global config, chosen by -P/--profile, HEY_PROFILE or default_profile) are ported from basecamp-cli and live in internal/config/profiles.go and internal/cmd/profile*.go. The CLI's credential is keyed by its origin with no profile active and by profile:<name> with one; hey mcp's by mcp::<origin> and mcp:profile:<name>. A profile's credential goes only to its own server: an override naming another is refused, and a stored sign-in issued by another server is refused too. With no profiles configured nothing reads differently; keep it that way. A repository's .hey/config.json sets the profile keys only once hey config trust-local trusts them.
A profile's endpoint is server (the default) or app: the HEY app on this computer, reached through internal/localapp at the door it opens ($XDG_RUNTIME_DIR/hey/agent.sock, or HEY_LOCAL_SOCKET). It is experimental: only HEY_EXPERIMENTAL=app honours it, and without it an app profile is refused, never answered from HEY's server, and nothing about it shows in help, .surface or the docs. On an app profile the commands in appRoutes (internal/cmd/endpoint.go) answer from the app, every other command that reads a server is refused, and nothing reads a credential; a new route branches on appEndpoint() first in its RunE. Answers keep the server's field names, and an experimental build names meta.endpoint. The app sends nothing without the person: a verb that would send now is refused there (appSendsNow), and hey draft send answers pending, exit 9 (output.ErrPending), which only an app profile produces.
The README is the front door, not the manual: install, first run, a dozen examples, and
links. Keep it that way. When you change, add or remove a command, the behaviour goes in
the command's --help text and its section of docs/cli.md (docs/tui.md for the TUI,
docs/agents.md for the skill and MCP, docs/install.md for installing and upgrading).
Touch the README only if one of its examples no longer runs or a command it names is gone.
New top-level commands and subcommands need the .surface snapshot updated
(go test ./internal/cmd -run TestSurfaceSnapshot -update-surface), and anything listed in
root help needs the byte-exact literal in help_test.go updated.
HEY grew JSON for every endpoint the CLI reads,
the SDK dropped its own scrapers, and the last three scrapes here are gone. Do not answer
"the JSON looks incomplete" by parsing a web page — check whether the SDK already has a
typed operation, and if HEY does not serve JSON for what you need, add it to the SDK
rather than working around it here. sdk.GetHTML has no callers left; if you find yourself
reaching for it, that is the signal to stop.
Every command that writes something confirms it through writeMutation (or
writeMutationLine, where the line carries an id or a name the summary does not).
It prints the sanitized line under --styled and hands writeOK the data and the
summary otherwise. Do not hand-roll the if writer.IsStyled() branch again: it was
copy-pasted about forty times, and three of the copies had drifted.
The TUI uses the sectionView interface pattern. Each top-level section (Mail, Contacts, Calendar, Journal) implements sectionView and owns its data, fetch commands, key handling, rendering, and help bindings. The main model delegates to the active view.
Four files implement sectionView -- mail.go, contacts.go, calendar.go and
journal.go, one per section. screener.go implements it too, but The Screener is not a
section: ctrl+s from the mail list swaps it in as the active view, it captures every key
while it is open, and it asks to be closed again with screenerClosedMsg.
The rest of internal/tui/ is shared infrastructure, starting with tui.go (model and
router) and section_view.go (the interface).
To add a new section: implement the sectionView interface in a new file, add a field and constructor call in newModel, and add a case in switchSection.
Each subsystem below has a design doc in docs/architecture/. The rules here are the ones
a change is most likely to break. Read the doc before you change the subsystem.
Topics.Get carries no bodies. internal/threadload reads them, within literal limits,
and reports per entry whether each body was read. A reply starts from
mail.ReplyPrefillFromServer and answers mail.ReplyTarget. Extend those two rather than
reimplement HEY's rules in a caller. Compose forms filter recipient suggestions in memory,
so a keystroke never waits on the network.
Details: docs/architecture/threads-and-replies.md.
Nothing HEY serves reaches a terminal raw. Metadata goes through
terminal.Sanitize/SanitizeLine. A body is an htmlutil.Markdown, which only
htmlutil.ToMarkdown makes and only markdown.Render accepts. JSON goes through
output.MarshalJSON. TestSinksAreSanitized catches a direct write of a listed field to a
listed sink, and a new exemption in its manifest needs a reason. sdkContactToModel and
sdkRecordingToModel are deliberately left unsanitized, because their fields go back
through edit forms. Sanitize where they are shown.
Details: docs/architecture/terminal-safety.md.
htmlutil.ToMarkdown converts a body once, at the edge, and everything downstream carries
Markdown. Entry.BodyHTML keeps the original HTML for --html. An inbound HTML email
hides its whole body in a Trix attachment with no filename. Do not treat that as a file.
Details: docs/architecture/email-bodies.md.
mail.ReadPage is the one read for a box, a label, a collection, a bundle and a contact's
threads. A source knows its kind from BoxKind, never from its name. Page.Cursor is
opaque and differs by kind. A box pages by HEY's next_history_url on its own route,
dispatched on BoxKind. A label and a collection page by the geared_pagination cursor in
the Link header, which only the SDK's *Page methods keep. Search and contacts number
their pages instead. A live
re-read splices the top page in through refreshHead.
Details: docs/architecture/mail-sources-and-paging.md.
Both hey watch and the TUI take an Action Cable broadcast as a doorbell, not as the
change. hey watch then reads the change from the posting sync feed, whose cursor is the
source of truth, and its start, resync and "new mail" rules are subtle. The TUI just
re-reads the box's top page, and re-reads the box on screen after a reconnect. Read the
doc before you change watch*.go or tui_watch.go.
Details: docs/architecture/watch.md.
A selection is a Recording.key(), not an id, because HEY serves a repeating event's virtual days with id 0.
Delete a repeating day through its occurrence. Tracked time is readable only through
TimeTracks().ListPage. An event update is not a partial, so send every field back.
Details: docs/architecture/calendar.md.
Covers use the ANSI-16 slots, never hex, with one palette per preset. Only the Imbox is
coverable, as mail.Source.Coverable() decides. The choice is stored locally on purpose.
Details: docs/architecture/cover-art.md.
The TUI draws images with Kitty's Unicode placeholders. Uploads are PNG, and image ids
come from nextImageID and are never reused.
Details: docs/architecture/inline-images.md.
hey upgrade hands Homebrew and Scoop installs to their package manager. On its own path
it trusts nothing it downloaded until sigstore verifies the release's checksums.
Its tests go through seam variables and never talk to GitHub or run a package manager.
Details: docs/architecture/upgrade.md.
If you are unsure what the API endpoints are, what they expect or what they respond to you can read through the server implementation to understand how the API works.
The server is the basecamp/haystack repo. If you have it checked out (conventionally
~/Work/basecamp/haystack/), read it whenever you need to know how the API behaves.
If you don't understand how the routes are laid out you can call rails routes in that directory to get a list of all the routes and their corresponding controller actions.
All API interactions must go through the HEY SDK (hey-sdk/go). There is no legacy client — the SDK is the only HTTP client.
If you need to call an endpoint that the SDK doesn't support yet, add it to the SDK.
The SDK is the basecamp/hey-sdk repo, conventionally checked out at
~/Work/basecamp/hey-sdk. To use your local changes:
-
Add a
replacedirective ingo.modpointing at your checkout. Give it a real path. The shell does not expand~in the middle of an argument, so...hey-sdk/go=~/Work/...reaches Go as a literal tilde and the command fails withunversioned new path must be local directory:go mod edit -replace github.com/basecamp/hey-sdk/go="$HOME/Work/basecamp/hey-sdk/go" -
Implement and test your changes
-
Call out that you made changes to the SDK when you're done — your operator will review those changes and publish a new SDK release, then you can remove the
replacedirective and pin to the released version
Those paths are in the SDK repo, not this one. There, the hand-written service wrappers
in go/pkg/hey/ (e.g. messages.go, journal.go, postings.go) are safe to edit
directly. The Smithy-generated code in go/pkg/generated/ is not — update the Smithy
model and run make smithy-build then make go-generate from the SDK root. hey-cli has
neither target.
When you add any kind of example make it realistic.
For emails, always use @example.com or @example.org domains to avoid accidentally sending emails to real people. For names, use common names or fictional characters. For calendar events, use plausible titles and times. The goal is to make the examples feel authentic without risking privacy or confusion. Never use abbreviations or placeholders like "Test Event", "User1", "a@ex.com". Instead, use full names and descriptive titles that reflect real-world usage.
For before/after bug proof or PR runtime checks, read
.agents/skills/verify-hey-cli/SKILL.md and its user-facing feature recipe.
Use the existing smoke harness for live CLI checks, the isolated binary for local
settings, and an authorized PTY for live TUI checks. Unit tests or a neighboring
green smoke case do not prove the reported behavior; keep these surfaces separate.
Whenever you add, remove or change any functionality add/remove/change tests as well. Tests are located in the same package as the code they test, with filenames ending in _test.go. Run make test to run all tests.
Smoke tests verify all CLI commands against a real HEY server. They live in tests/smoke/ as a separate Go module and use a pre-compiled binary built by make build.
What they test: Every CLI command and its flags — boxes, box, compose, reply, threads, drafts, calendars, recordings, todo, journal, habit, timetrack, seen/unseen, config, auth, and all output format flags (--json, --quiet, --ids-only, --count, --markdown, --styled, --verbose, --stats). Browser-based cross-verification tests confirm CLI actions are visible in the browser and vice versa.
Running:
make test-smoke # Builds binary then runs tests (requires dev server)The dev server must be running at http://app.hey.localhost:3003 (override with HEY_SMOKE_BASE_URL). Default login: david@basecamp.com / secret123456 (override with HEY_SMOKE_EMAIL and HEY_SMOKE_PASSWORD).
How they work:
TestMaininhelpers_test.goorchestrates setup: finds the binary, checks server reachability, launches headless Chrome via chromedp to sign in, then completes the CLI’s actualhey auth login --no-browserOAuth/PKCE consent and callback flow. Browser sessions stay in browser helpers; the CLI receives only OAuth tokens.- All CLI invocations run in an isolated environment: temp
XDG_CONFIG_HOME,HEY_NO_KEYRING=1,HEY_BASE_URLpointing to the dev server. - Helper functions (
hey(),heyOK(),heyJSON(),heyFail()) run the binary and parse output.dataAs[T]()generically unmarshals response data. - Tests that depend on write operations (compose, todo add, journal write, reply, timetrack start) skip gracefully when the server returns errors, since the SDK's parameter format may not match the server's expectations. Set
HEY_SMOKE_STRICT=1to turn every such skip into a failure — that is the release gate, where a skipped check is not a passed one. - Test data uses
uniqueID()(nanosecond timestamps) to avoid collisions. Cleanup happens viat.Cleanup(). hey upgradeis covered only as far as a dev build'supgrade_requiredrefusal (andhey version --json). The live self-update against a real release runs in.github/workflows/upgrade-smoke.yml, never against the dev server.
How to add a new test:
- Create or edit a
*_test.gofile intests/smoke/(packagesmoke_test). - Use
heyJSON(t, "command", "args...")for commands that should succeed and return JSON. - Use
heyFail(t, "command", "args...")for commands that should fail. - For write operations that may fail server-side, use
hey(t, ...)directly and skip on non-zero exit through the strict-aware helper:if code != 0 { skipf(t, "... (exit %d): %s", code, stderr) }. Never callt.Skipdirectly —skipfis what turns a skip into a failure underHEY_SMOKE_STRICT=1. - Use
dataAs[T](t, resp)to unmarshal response data into typed structs. - For browser cross-verification, use
browserPageText(t, url)to get page content.
To run the CLI use make build and then ./bin/hey. This ensures that you and I are running the same version of the program.
See STYLE.md for the Go conventions used here. Read it when writing or reviewing Go in
this repo -- it is not imported, so it does not sit in context for sessions that never
touch Go.