hey-axi 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TangentialSolutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# hey-axi
+
+An agent-friendly wrapper for [HEY CLI](https://github.com/basecamp/hey-cli) (`hey`), Basecamp's command line for HEY email, calendars, todos, habits, time tracking and journals.
+
+hey-axi runs `hey`, asks for its JSON response envelope, and prints it as [TOON](https://github.com/toon-format/toon). It follows the [AXI](https://axi.md) principles: a live home view, minimal default fields, truncated long text, definitive empty states, and unknown flags rejected up front. On our synthetic benchmark that's **~89% fewer tokens than `hey --json`** ([docs/benchmarks.md](docs/benchmarks.md)). It also adds a few safety rails. It covers **every command in HEY CLI v1.7.0** (144 commands, plus the `login`/`logout` aliases and the `box <id>`-style shortcuts) by routing from HEY's own `hey commands --json` catalog.
+
+## Install
+
+Requirements: Node 20+ and an authenticated HEY CLI (`curl -fsSL https://hey.com/install-cli | bash`, then `hey auth login`).
+
+```bash
+npm i -g hey-axi    # puts `hey-axi` on your PATH
+# or run it without installing:
+npx -y hey-axi box view imbox
+
+# agent skill (see "Agent integrations" below)
+npx skills add TangentialSolutions/hey-axi
+```
+
+From source: `git clone https://github.com/TangentialSolutions/hey-axi && cd hey-axi && npm ci && npm link`.
+
+hey-axi uses `$HEY_BIN` if it's set, and otherwise finds `hey` on `PATH`. launchd/cron jobs usually have a minimal PATH, so set `HEY_BIN=$HOME/.local/bin/hey` there.
+
+## Usage
+
+```bash
+hey-axi                                    # home view: who/what, the Imbox (10 threads), next commands
+hey-axi box view imbox                     # TOON: summary, a few columns per thread, notice, help
+hey-axi box imbox                          # HEY's shortcut forms work too
+hey-axi --account 2 search --from a@b.com  # global flags anywhere
+hey-axi thread read 123                    # bodies cut at 1000 chars with "(truncated, N chars total)"
+hey-axi thread read 123 --full             # HEY's complete, untouched result
+hey-axi box view imbox --fields id,subject,creator.email_address   # choose columns (--fields all = every field)
+hey-axi thread read 123 --json             # the same shaped output as compact JSON
+hey-axi box view imbox --quiet             # data only, no envelope
+hey-axi --version                          # bare hey-axi version (fast path); `hey-axi version` adds HEY's
+hey-axi box view imbox --ids-only          # raw HEY output (also --count/--markdown/--html/--styled/--jq)
+hey-axi set-aside group view 4 --limit 5   # three-word commands
+hey-axi move --help                        # usage, flags, examples, notes (no HEY call)
+```
+
+### Output shaping
+
+- **Home view.** `hey-axi` with no arguments prints `bin`, `description`, the Imbox summary and its 10 newest threads, and `help` lines with next commands. If HEY is missing, signed out or failing, it prints `status` with the fix and still exits 0.
+- **Minimal fields.** List commands show a few columns. The defaults per command are in `src/shape.js` and in each command's `--help`. `--fields a,b,c` picks columns, using default aliases (`from`, `subject`, `at`) or dotted paths (`creator.email_address`, `messages.0.summary`); `--fields all` keeps everything. An unknown field exits 2 and lists what's available.
+- **Truncation.** Strings longer than 1000 characters (120 in list cells) are cut and marked `… (truncated, N chars total)`, and a `help` line suggests `--full`.
+- **Aggregates and empty states.** `count: N of T total` when HEY reports a total; ``empty: 0 results for `…` `` when a list is empty.
+- **Help lines.** HEY's breadcrumbs become ``help: Run `hey-axi …` to …``, and HEY's hints are rewritten to name `hey-axi`.
+- **Fail loud.** Unknown flags and missing required flags (`move` without `--to`) exit 2 before HEY runs, listing the valid flags.
+- `--full` turns all of this off, and `--json` prints the same shaped result as compact JSON.
+
+### How each kind of command runs
+
+| Kind | Commands | Behavior |
+|---|---|---|
+| JSON (default) | almost everything | `hey … --json` → TOON (or compact JSON with `--json`) |
+| Raw output | `--ids-only`, `--count`, `--markdown`, `--html`, `--styled`, `--jq`; `shell-completion generate`; `timetrack export` without `--output` | HEY's output is printed as-is |
+| Stream | `watch` | NDJSON relayed line by line as events arrive; Ctrl-C/SIGTERM forwarded to HEY |
+| Interactive | `tui`, `auth login`/`login`, `setup …`, `mcp`, `upgrade` | HEY gets the terminal (inherited stdio). `tui` refuses to start without a TTY |
+
+### Safety rails
+
+- **Nothing is sent without an opt-in** (`--allow-send` or `HEY_AXI_ALLOW_SEND=1`):
+  - `compose` and `reply` are **saved as drafts**. hey-axi adds `--draft`, and the output starts with `sent: false`, `saved_as: draft` and an `axi_notice` (also printed to stderr).
+  - `forward`, `draft send` and `bulk-reply send` have no draft mode in HEY, so they're refused (exit 2) with the safe alternative (`reply … --to`, `draft show`, `bulk-reply preview`).
+  - If you pass `--draft` or `--dry-run` yourself, hey-axi adds and marks nothing.
+- **Credentials stay out of agent context.** `auth token` needs `--allow-secret` or `HEY_AXI_ALLOW_SECRETS=1`.
+- hey-axi's own flags (`--allow-send`, `--allow-secret`, `--fields`, `--full`) are never forwarded to HEY.
+
+### Errors and exit codes
+
+Errors are printed as structured TOON: `ok: false`, `error`, and, when HEY gave them, `code`, `hint`, `meta`, plus a `help` next step (when HEY gave no hint) and `exit_code`. hey-axi passes HEY's exit code through: 1 usage, 2 not found, 3 auth, 4 forbidden, 5 rate limit, 6 network, 7 API, 8 ambiguous (`hey help exit-codes`). hey-axi's own refusals (unknown/incomplete command, unknown flag or field, missing required flag, blocked send, missing TTY) exit **2**. If `hey` can't be found, hey-axi exits **127**.
+
+## Agent integrations: session hook or skill
+
+There are two ways to give an agent hey-axi. You only need one:
+
+1. **Session hook (recommended where supported):** `hey-axi setup hooks` registers the home view as session-start context for **Claude Code** (`~/.claude/settings.json`), **Codex** (`~/.codex/hooks.json`, and it turns on `[features].hooks` in `~/.codex/config.toml`) and **OpenCode** (a managed plugin in `~/.config/opencode/plugins/`). Every new session then starts with your Imbox summary and the next commands, and no tool call is needed.
+   - `--project` writes to the current directory's `.claude/`, `.codex/` and `.opencode/` instead.
+   - `--status` reports what's installed, and `--remove` removes only hey-axi's entries.
+   - Re-running is a no-op, or repairs the path if hey-axi moved. It uses [axi-sdk-js](https://www.npmjs.com/package/axi-sdk-js)'s installer.
+   - Note that the hook puts Imbox senders and subjects into every session's context.
+2. **Agent skill (broader support, loads on demand):** see below.
+
+### Agent skill
+
+[`skills/hey-axi/SKILL.md`](skills/hey-axi/SKILL.md) is an [Agent Skills](https://agentskills.io/specification) package. It tells coding agents (Claude Code, Codex, Cursor, Gemini CLI, Copilot, …) when and how to use hey-axi: setup checks, triage commands, which id goes where, drafts-by-default, output modes, `watch` and exit codes. [`references/commands.md`](skills/hey-axi/references/commands.md) lists every command and is generated from the manifest (`npm run skill:gen`).
+
+Installing the skill doesn't install the CLI. Install `hey` and `hey-axi` first (see [Install](#install)).
+
+```bash
+# with the skills CLI (https://skills.sh), from GitHub
+npx skills add TangentialSolutions/hey-axi            # this project
+npx skills add TangentialSolutions/hey-axi -g -a claude-code   # user-wide, Claude Code only
+
+# with GitHub CLI (gh skill, preview)
+gh skill install TangentialSolutions/hey-axi hey-axi --agent claude-code --scope user
+
+# manually
+cp -r skills/hey-axi ~/.claude/skills/               # or ~/.agents/skills/, ~/.codex/skills/, …
+```
+
+See [docs/listing.md](docs/listing.md) for how hey-axi gets listed on skills.sh and axi.md.
+
+## Keeping up with HEY releases
+
+`src/manifest.json` is a snapshot of `hey commands --json`. To regenerate it from whichever `hey` you have installed:
+
+```bash
+npm run refresh-manifest     # runs only `hey version` and `hey commands`
+```
+
+If the snapshot doesn't know a command, hey-axi asks the installed `hey commands --json` at runtime before reporting `unknown command`. So newer HEY releases work even before the snapshot is refreshed. A weekly GitHub Action (`manifest-drift`) fails when the snapshot falls behind the latest HEY release.
+
+## Development
+
+```bash
+npm test     # node:test; every test uses a fake `hey` (test/helpers.js), never the real CLI
+```
+
+Token benchmark (HEY CLI vs hey-axi output): [docs/benchmarks.md](docs/benchmarks.md), with `npm run bench:tokens`.
+
+See [AGENTS.md](AGENTS.md) for the code map and conventions, and [SCHEDULED_HEY_CLI.md](SCHEDULED_HEY_CLI.md) for running triage on a schedule.
+
+## License
+
+[MIT](LICENSE) © 2026 TangentialSolutions. hey-axi is an independent project. It isn't affiliated with or endorsed by Basecamp or HEY.

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "hey-axi",
+  "version": "0.2.0",
+  "description": "Agent-ergonomic AXI wrapper for Basecamp's HEY CLI: TOON output, send-to-draft safety, and a shareable agent skill",
+  "keywords": [
+    "axi",
+    "agent",
+    "ai-agent",
+    "agent-skills",
+    "skill",
+    "cli",
+    "hey",
+    "hey.com",
+    "email",
+    "basecamp",
+    "toon",
+    "llm",
+    "claude-code",
+    "codex"
+  ],
+  "homepage": "https://github.com/TangentialSolutions/hey-axi#readme",
+  "bugs": {
+    "url": "https://github.com/TangentialSolutions/hey-axi/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TangentialSolutions/hey-axi.git"
+  },
+  "author": "Trevor Broaddus",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "hey-axi": "src/hey-axi.js"
+  },
+  "files": [
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "refresh-manifest": "node scripts/refresh-manifest.js",
+    "bench:tokens": "node bench/tokens.mjs",
+    "bench:capture": "node bench/capture.mjs",
+    "bench:fixtures": "node bench/generate-api-fixtures.mjs",
+    "skill:gen": "node scripts/gen-skill.js",
+    "skill:check": "node scripts/gen-skill.js --check"
+  },
+  "dependencies": {
+    "@toon-format/toon": "^4.1.1",
+    "axi-sdk-js": "^0.1.12"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "js-tiktoken": "^1.0.21"
+  }
+}

package/skills/hey-axi/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: hey-axi
+description: Read, triage and draft HEY email (and HEY calendars, todos, habits, journal, time tracking) from the shell through hey-axi, a token-efficient TOON wrapper around Basecamp's HEY CLI that saves outgoing mail as drafts unless sending is explicitly allowed. Use when the user asks you to check, search, read, summarize, sort, label, screen, archive or reply to their HEY (hey.com) email, watch for new mail, or manage HEY todos, events, habits, journal entries or time tracks.
+license: MIT
+compatibility: Requires Node.js 20+, the HEY CLI (`hey`, v1.7.0 or newer) signed in to a HEY account, and network access to app.hey.com.
+metadata:
+  author: TangentialSolutions
+  repository: https://github.com/TangentialSolutions/hey-axi
+---
+
+# hey-axi: HEY email for agents
+
+`hey-axi` runs Basecamp's HEY CLI (`hey`) and prints compact TOON. Lists show a few columns, long text is cut (the total size is shown), and suggestions name `hey-axi` commands. Every `hey` command works: `hey-axi <same args as hey>`.
+
+## 1. Start here
+
+Run `hey-axi` with no arguments. It shows the Imbox and what to do next. If HEY is missing or signed out, it prints a `status` line and the fix instead.
+
+<!-- generated:home:start -->
+<!-- Generated by scripts/gen-skill.js from src/guide.js, the same text the home view prints. Do not edit by hand. -->
+What hey-axi is: HEY email, calendars and todos for agents: compact TOON over Basecamp's HEY CLI; outgoing mail is saved as a draft unless --allow-send
+
+Next steps the home view suggests:
+- Run `hey-axi thread read <topic_id>` to read a thread
+- Run `hey-axi box view imbox --limit 50` for more (also feed, papertrail, aside, later)
+- Run `hey-axi search "<query>"` to search mail
+- Run `hey-axi screener list` for senders waiting to be screened
+- Run `hey-axi reply <topic_id> --message "..."` to draft a reply (not sent without --allow-send)
+- Run `hey-axi --help` for all commands; lists take --fields a,b / --fields all, long text --full
+<!-- generated:home:end -->
+
+Problems:
+- `hey-axi: command not found`: run it as `npx -y hey-axi …`, or install it (see "Install" below).
+- `status: HEY CLI not found` / exit **127**: install `hey`, or set `HEY_BIN=/path/to/hey` (cron/launchd jobs usually need `HEY_BIN=$HOME/.local/bin/hey`).
+- `status: not signed in` / exit **3**: ask the **user** to run `hey auth login` in their own terminal. It opens a browser. Don't try to sign in for them, and never print tokens (`auth token` is blocked unless `--allow-secret` is passed).
+- `hey-axi doctor` finds other login and config problems. `hey-axi version` shows both versions.
+
+## 2. Read and triage
+
+```bash
+hey-axi box list                          # boxes and their ids
+hey-axi box view imbox --limit 25         # rows in a box (imbox, feed, papertrail, aside, later, …)
+hey-axi thread read <topic_id>            # the thread (long bodies cut; --full for all)
+hey-axi search "invoice" --from a@b.com --date last_30_days
+hey-axi screener list                     # senders waiting to be screened
+hey-axi set-aside view   |   hey-axi bubble list   |   hey-axi draft list
+```
+
+**Which id to use.** Each `box view` row has an `id` (the box item) and a `topic_id` (the thread):
+- `topic_id` goes to `thread read`, `reply` and `forward`.
+- `id` goes to `seen`, `unseen`, `move`, `label`, `bubble`, `trash`, `spam` and `ignore`.
+- A row with kind `bundle` has no `topic_id`. Open it with `hey-axi bundle view <id>`.
+- Screener commands take the clearance `id` from `screener list`. These aren't contact ids.
+
+```bash
+hey-axi seen <id>...           hey-axi unseen <id>...
+hey-axi move <id>... --to feed          # imbox | feed | aside | later | papertrail
+hey-axi label add <id>... --to "Receipts"
+hey-axi bubble up <id>... --tomorrow    # or --now | --on <date> | --weekend | --next-week
+hey-axi screener approve <clearance-id> hey-axi screener deny <clearance-id>
+hey-axi trash <id>...          hey-axi spam <id>...      hey-axi ignore <id>...
+```
+
+`trash`, `spam`, `ignore`, `screener deny --spam` and `screener clear` (which clears the whole queue) run without any confirmation. Confirm with the user before you run them in bulk.
+
+Output includes HEY's `next`/breadcrumb hints. Follow them for paging (`--page N`, `--all`) and follow-up commands instead of guessing. `hey <command> --help` explains a command in depth.
+
+## 3. Writing mail: drafts by default
+
+- `compose` and `reply` are **saved as drafts** automatically. The output starts with `sent: false`, `saved_as: draft` and an `axi_notice`. Tell the user that a draft is waiting in HEY. Don't claim it was sent.
+  ```bash
+  hey-axi reply <topic_id> --message "Thanks, Thursday works."
+  hey-axi compose --to a@b.com --subject "Hi" --message "…"
+  hey-axi draft list   |   hey-axi draft show <draft-id>
+  ```
+- `forward`, `draft send` and `bulk-reply send` are **refused** (exit 2) because HEY has no draft mode for them. The error names the safe alternative.
+- To actually send, the user must explicitly ask you to, and you add `--allow-send` (or they set `HEY_AXI_ALLOW_SEND=1`). Don't add it on your own initiative.
+
+## 4. Output: fields, truncation, modes
+
+- **Lists show a few columns** (for example `box view`: `id, topic_id, from, subject, seen, at`). Pick others with `--fields id,subject,creator.email_address`; aliases and dotted paths both work. `--fields all` keeps every field. An unknown field fails with exit 2 and lists the ones available. `hey-axi <command> --help` shows the defaults.
+- **Long text is cut** at 1000 characters in detail views (thread bodies, drafts) and 120 in list cells, marked `… (truncated, N chars total)`. The output then includes a `Run … --full` help line. Use `--full` only when you need the whole text.
+- Lists say `empty: 0 results for …` when nothing matched, and `count: N of T total` when HEY knows the total. Follow `notice`/`help` for paging (`--page`, `--all`).
+
+| Want | Use |
+|---|---|
+| Default: summary, data, help lines, as TOON | (nothing) |
+| The same as compact JSON | `--json` |
+| Data only | `--quiet` |
+| HEY's complete, untouched result | `--full` (combine with `--json` for raw JSON) |
+| Raw HEY output | `--ids-only`, `--count`, `--markdown`, `--html`, `--styled`, `--jq '<expr>'` |
+| Help for one command: usage, flags, examples, notes (no network) | `hey-axi <command> --help` |
+
+Unknown flags are rejected before anything runs (exit 2, with the valid flags listed), and so are missing required flags such as `move --to`. Global flags like `--account <id|all>` can go anywhere.
+
+## 5. Watching for changes
+
+`hey-axi watch` streams HEY's NDJSON one line at a time until it's interrupted. Use bounded forms in agent sessions:
+
+```bash
+hey-axi watch --box imbox --events new --exit-on-first --timeout 10m
+```
+
+Lines also include `ready`, `disconnected` and `resync`. On `resync`, re-read that box.
+
+## 6. Errors and exit codes
+
+Errors are TOON on stdout: `ok: false`, `error`, plus `code`/`hint`/`meta` when HEY provided them, a `help` line with the next step, and `exit_code`. Exit codes: 0 ok · 1 usage · 2 not found, or a hey-axi refusal (unknown flag or field, blocked send) · 3 auth · 4 forbidden · 5 rate limit · 6 network · 7 API · 8 ambiguous · 127 `hey` missing. Read `hint`/`help` before you retry.
+
+## Install
+
+```bash
+# HEY CLI (macOS/Linux)
+curl -fsSL https://hey.com/install-cli | bash        # or: brew install --cask basecamp/tap/hey
+hey auth login                                      # the user runs this once, interactively
+
+# hey-axi
+npm i -g hey-axi                                    # puts `hey-axi` on PATH
+```
+
+No global install? Prefix any command with `npx -y`, e.g. `npx -y hey-axi box view imbox`. It's slower on the first run, so install it if you'll run many commands.
+
+Optional: `hey-axi setup hooks` (user-invoked) shows the home view at the start of every Claude Code, Codex and OpenCode session. `--project` limits it to one directory, and `--remove` undoes it.
+
+More commands (calendar, todos, habits, journal, time tracking, contacts, collections), with their default fields: [references/commands.md](references/commands.md).

package/skills/hey-axi/references/commands.md

@@ -0,0 +1,161 @@
+# hey-axi command reference
+
+<!-- Generated by scripts/gen-skill.js from src/manifest.json (hey 1.7.0). Do not edit by hand. -->
+
+Every command from HEY CLI 1.7.0 (151 runnable paths, including the `login`/`logout` aliases and shortcut forms such as `box <name>`). Run each as `hey-axi <command> [args] [flags]`.
+`hey-axi <command> --help` shows usage, flag descriptions, examples and notes, offline.
+Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--fields <a,b|all>`, `--full`, `--ids-only`, `--count`, `--markdown`, `--html`, `--styled`, `--jq <expr>`. Anything else unknown is rejected (exit 2).
+
+| Command | What it does | Flags | hey-axi behavior |
+|---|---|---|---|
+| `account list` | List linked mail accounts |  | fields: id, email, name, active |
+| `account senders` | List configured sender addresses |  |  |
+| `account use` | Set the default linked mail account |  |  |
+| `attachment list` | List a thread's attachments | `--allow-partial` | fields: id, filename, content_type, byte_size |
+| `attachment save` | Save an attachment to disk | `--force` `--output <v>` |  |
+| `auth login` | Authenticate with the HEY server | `--cookie <v>` `--no-browser` `--token <v>` | interactive (user runs it) |
+| `auth logout` | Clear stored credentials |  |  |
+| `auth refresh` | Force token refresh |  |  |
+| `auth status` | Show authentication status |  |  |
+| `auth token` | Print access token to stdout | `--stored` | refused unless `--allow-secret` |
+| `box` | List HEY boxes and their email threads | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
+| `box list` | List your HEY boxes | `--all` `--limit <v>` | fields: id, kind, name |
+| `box view` | List email threads in a box | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
+| `bubble list` | List bubbled-up and scheduled email threads | `--all` `--limit <v>` | fields: id, topic_id, from, subject, seen, at, bubbles_up |
+| `bubble pop` | Cancel bubble-ups |  |  |
+| `bubble up` | Bubble email threads up | `--next-week` `--now` `--on <v>` `--tomorrow` `--weekend` |  |
+| `bulk-reply preview` | Preview threads and recipients without sending |  |  |
+| `bulk-reply send` | Send one reply to multiple threads | `--attach <v>` `--message <v>` `--message-html <v>` | refused unless `--allow-send` |
+| `bulk-reply undo` | Recall a delayed bulk reply |  |  |
+| `bundle` | List the unseen threads a bundle groups | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
+| `bundle view` | List the unseen threads a bundle groups | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
+| `calendar list` | List calendars |  | fields: id, name, kind, owned |
+| `clip create` | Save text from an email entry | `--content <v>` |  |
+| `clip delete` | Delete a saved clip |  |  |
+| `clip list` | List the newest page of passages clipped from email |  | fields: id, content, topic_id, at |
+| `collection` | List and manage email collections | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
+| `collection add` | Add email threads to a collection | `--to <v>` |  |
+| `collection create` | Create a collection | `--summary <v>` |  |
+| `collection list` | List your email collections | `--all` `--limit <v>` | fields: id, name |
+| `collection remove` | Remove email threads from a collection | `--from <v>` |  |
+| `collection update` | Update a collection | `--name <v>` `--summary <v>` |  |
+| `collection view` | List email threads in a collection | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
+| `commands` | List all available commands |  |  |
+| `compose` | Write and send a new email | `--attach <v>` `--bcc <v>` `--cc <v>` `--draft` `--from <v>` `--message <v>` `--message-html <v>` `--no-name-tag` `--subject <v>` `--thread-id <v>` `--to <v>` | saved as a draft unless `--allow-send` |
+| `config set` | Set a configuration value in the global config |  |  |
+| `config show` | Show current configuration with sources |  |  |
+| `config trust-local` | Trust this repository's local HEY settings |  |  |
+| `config trusted-locals` | List trusted repository-local HEY settings |  |  |
+| `config untrust-local` | Remove trust for this repository's local HEY settings |  |  |
+| `contact add` | Add a contact | `--account-user-id <v>` `--alias <v>` `--email <v>` `--name <v>` |  |
+| `contact bundle` | Bundle a contact's mail |  |  |
+| `contact hide` | Hide a contact |  |  |
+| `contact list` | List contacts | `--all` `--page <v>` | fields: id, name, email_address |
+| `contact note delete` | Delete a private contact note |  |  |
+| `contact note set` | Write or edit a private contact note | `--note <v>` `--note-html <v>` |  |
+| `contact note show` | Read a private contact note |  |  |
+| `contact show` | View a contact |  |  |
+| `contact show-again` | Show a hidden contact again |  |  |
+| `contact threads` | List every thread with a contact | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
+| `contact unbundle` | List a contact's mail separately |  |  |
+| `contact update` | Edit a contact | `--alias <v>` `--email <v>` `--name <v>` |  |
+| `doctor` | Find login and configuration problems |  |  |
+| `draft delete` | Trash drafts |  |  |
+| `draft edit` | Change a draft | `--bcc <v>` `--cc <v>` `--from <v>` `--message <v>` `--message-html <v>` `--subject <v>` `--to <v>` |  |
+| `draft list` | List draft emails | `--all` `--limit <v>` `--page <v>` | fields: id, subject, summary, at |
+| `draft send` | Deliver a draft |  | refused unless `--allow-send` |
+| `draft show` | Read a draft back |  |  |
+| `event add` | Create an event | `--all-day` `--calendar <v>` `--circle` `--countdown <v>` `--countdown-unit <v>` `--end-time <v>` `--ends-on <v>` `--invite <v>` `--link <v>` `--location <v>` `--notes <v>` `--remind <v>` `--repeat <v>` `--repeat-times <v>` `--repeat-until <v>` `--start-time <v>` `--starts-on <v>` `--time-zone <v>` `--title <v>` |  |
+| `event day` | List the events of one day, as HEY draws it | `--all` `--limit <v>` | fields: id, title, starts_at, ends_at, calendar |
+| `event delete` | Delete an event |  |  |
+| `event edit` | Change an event | `--all-day` `--allow-plain-notes` `--apply-to <v>` `--calendar <v>` `--circle` `--countdown <v>` `--countdown-unit <v>` `--end-time <v>` `--ends-on <v>` `--invite <v>` `--link <v>` `--location <v>` `--notes <v>` `--occurrence <v>` `--remind <v>` `--repeat <v>` `--repeat-times <v>` `--repeat-until <v>` `--start-time <v>` `--starts-on <v>` `--time-zone <v>` `--title <v>` |  |
+| `event list` | List calendar events | `--all` `--calendar <v>` `--ends-on <v>` `--limit <v>` `--starts-on <v>` | fields: id, title, starts_at, ends_at, calendar |
+| `event week` | List the events of one week, as HEY draws it | `--all` `--limit <v>` | fields: id, title, starts_at, ends_at, calendar |
+| `forward` | Forward the latest message in a thread | `--bcc <v>` `--cc <v>` `--message <v>` `--message-html <v>` `--to <v>` | refused unless `--allow-send` |
+| `habit complete` | Mark a habit as complete for a date | `--date <v>` |  |
+| `habit create` | Create a habit | `--color <v>` `--days <v>` `--icon <v>` `--name <v>` |  |
+| `habit delete` | Delete a habit and its history |  |  |
+| `habit edit` | Edit a habit | `--color <v>` `--days <v>` `--icon <v>` `--name <v>` |  |
+| `habit list` | List habits | `--all` `--date <v>` `--limit <v>` | fields: id, title, days |
+| `habit uncomplete` | Remove a habit completion for a date | `--date <v>` |  |
+| `ignore` | Ignore email threads |  |  |
+| `journal list` | List journal entries | `--all` `--calendar <v>` `--ends-on <v>` `--limit <v>` `--starts-on <v>` | fields: id, starts_at, content |
+| `journal read` | Read a journal entry (default: today) |  |  |
+| `journal write` | Write or edit a journal entry (default: today) | `--content <v>` `--content-html <v>` |  |
+| `label` | List and manage email labels | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
+| `label add` | Add a label to email threads | `--to <v>` |  |
+| `label create` | Create a label and add it to email threads |  |  |
+| `label list` | List your email labels | `--all` `--limit <v>` | fields: id, name |
+| `label remove` | Remove labels from email threads | `--from <v>` |  |
+| `label view` | List email threads with a label | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
+| `login` | Authenticate with the HEY server | `--cookie <v>` `--no-browser` `--token <v>` | interactive (user runs it) |
+| `logout` | Clear stored credentials |  |  |
+| `mcp` | Serve HEY to MCP clients over stdio | `--domains <v>` `--read-only` | interactive (user runs it) |
+| `move` | Move email threads to another box | `--to <v>` |  |
+| `reply` | Reply to a thread | `--attach <v>` `--bcc <v>` `--cc <v>` `--draft` `--dry-run` `--message <v>` `--message-html <v>` `--replace-recipients` `--to <v>` | saved as a draft unless `--allow-send` |
+| `screener approve` | Let a sender through | `--box <v>` `--seen` |  |
+| `screener clear` | Empty the Screener without deciding |  |  |
+| `screener deny` | Turn a sender away | `--spam` |  |
+| `screener history` | List the senders already screened | `--all` `--page <v>` | fields: id, status, name, email_address, decided |
+| `screener list` | List the senders waiting to be screened | `--all` `--page <v>` | fields: id, name, email_address, subject, topic_id |
+| `search` | Search email threads and messages | `--all` `--any <v>` `--attachment <v>` `--date <v>` `--exact <v>` `--from <v>` `--in <v>` `--label <v>` `--none <v>` `--page <v>` `--required <v>` `--subject <v>` `--to <v>` | fields: id, topic_id, subject, from, at |
+| `search filters` | List available search refinement values |  |  |
+| `seen` | Mark email threads as seen |  |  |
+| `set-aside group add` | Add email threads to a Set Aside group | `--to <v>` |  |
+| `set-aside group create` | Gather email threads into a new Set Aside group |  |  |
+| `set-aside group delete` | Break up a Set Aside group |  |  |
+| `set-aside group list` | List the groups in Set Aside |  | fields: id, thread_count |
+| `set-aside group remove` | Take email threads out of their Set Aside group |  |  |
+| `set-aside group view` | List email threads in a Set Aside group | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
+| `set-aside view` | List email threads in Set Aside | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
+| `setup` | Set up HEY for first use | `--silent-success` `--skip-agents` `--skip-omarchy` | interactive (user runs it) |
+| `setup agents` | Install or remove HEY coding-agent integrations | `--remove` | interactive (user runs it) |
+| `setup claude` | Connect Claude Code to HEY |  | interactive (user runs it) |
+| `setup codex` | Connect Codex to HEY |  | interactive (user runs it) |
+| `setup omarchy` | Install hey into the Omarchy desktop | `--no-notify` `--notify` `--remove` | interactive (user runs it) |
+| `share` | Get a sharing link for an email thread |  |  |
+| `shell-completion generate` | Print a completion script to stdout |  | raw output |
+| `shell-completion install` | Install shell completions where your shell will find them | `--force` |  |
+| `skill install` | Install the hey skill globally for your coding agents |  |  |
+| `snippet create` | Create a reusable email snippet | `--content <v>` `--content-html <v>` `--name <v>` |  |
+| `snippet delete` | Delete a reusable email snippet |  |  |
+| `snippet list` | List reusable email snippets |  | fields: id, name, content |
+| `snippet update` | Update a reusable email snippet | `--content <v>` `--content-html <v>` `--name <v>` |  |
+| `spam` | Mark email threads as spam |  |  |
+| `stop-ignoring` | Stop ignoring email threads |  |  |
+| `thread read` | Read a thread | `--allow-partial` | fields: id, at, from, email, to, cc, body |
+| `timetrack categories` | List time track categories |  | fields: id, title |
+| `timetrack category create` | Create a time track category |  |  |
+| `timetrack category delete` | Delete a time track category |  |  |
+| `timetrack category rename` | Rename a time track category |  |  |
+| `timetrack current` | Show current time tracking status |  |  |
+| `timetrack delete` | Delete a time track |  |  |
+| `timetrack edit` | Edit a completed time track | `--category <v>` `--end <v>` `--notes <v>` `--start <v>` |  |
+| `timetrack export` | Export completed time tracks as CSV | `--force` `--output <v>` | raw CSV unless `--output <file>` |
+| `timetrack list` | List completed time tracks | `--all` `--category <v>` `--limit <v>` | fields: id, starts_at, ends_at, category, notes |
+| `timetrack start` | Start time tracking |  |  |
+| `timetrack stop` | Stop time tracking | `--category <v>` |  |
+| `todo add` | Create a new todo | `--date <v>` `--title <v>` |  |
+| `todo complete` | Mark a todo as complete |  |  |
+| `todo delete` | Delete a todo |  |  |
+| `todo list` | List todos | `--all` `--calendar <v>` `--ends-on <v>` `--limit <v>` `--starts-on <v>` | fields: id, title, starts_at, completed_at |
+| `todo uncomplete` | Mark a todo as incomplete |  |  |
+| `trash` | Move email threads to Trash |  |  |
+| `tui` | Launch the interactive terminal UI | `--instance <v>` `--remote` `--screener` `--topic <v>` `--topic-title <v>` | interactive, needs a TTY (user runs it) |
+| `unseen` | Mark email threads as unseen |  |  |
+| `unshare` | Turn off an email thread's sharing link |  |  |
+| `upgrade` | Upgrade hey to the latest release |  | interactive (user runs it) |
+| `version` | Show the installed hey version |  |  |
+| `watch` | Follow email threads and calendars as they change | `--box <v>` `--events <v>` `--exit-on-first` `--run-async <v>` `--run-sync <v>` `--since <v>` `--timeout <v>` | streams NDJSON |
+| `workflow` | List and manage email workflows |  |  |
+| `workflow add` | Add email threads to a workflow stage | `--stage <v>` `--to <v>` |  |
+| `workflow create` | Create an email workflow |  |  |
+| `workflow delete` | Delete an email workflow |  |  |
+| `workflow list` | List your email workflows | `--all` `--limit <v>` | fields: id, name |
+| `workflow move` | Move email threads to another workflow stage | `--to <v>` `--workflow <v>` |  |
+| `workflow remove` | Remove email threads from a workflow | `--from <v>` |  |
+| `workflow stage create` | Add an Untitled stage to a workflow |  |  |
+| `workflow stage delete` | Delete a workflow stage |  |  |
+| `workflow stage update` | Rename a workflow stage | `--name <v>` |  |
+| `workflow update` | Rename an email workflow | `--name <v>` |  |
+| `workflow view` | View a workflow and its stages |  |  |

package/src/args.js

@@ -0,0 +1,117 @@
+// Command-line parsing that knows which HEY flags take a value, so global flags such as
+// `--account 5` can appear anywhere (before, between, or after the command words)
+// without their values being mistaken for command words.
+
+// HEY's persistent (global) flags, from `hey --help`. Only these three take a value.
+export const GLOBAL_VALUE_FLAGS = ["account", "jq", "base-url"];
+export const GLOBAL_BOOLEAN_FLAGS = ["json", "quiet", "ids-only", "count", "markdown", "styled", "html", "stats", "verbose", "help"];
+export const GLOBAL_SHORTHANDS = ["-v", "-h"];
+
+// hey-axi's own flags. Never forwarded to HEY.
+export const AXI_BOOLEAN_FLAGS = ["allow-send", "allow-secret", "full"];
+export const AXI_VALUE_FLAGS = ["fields"];
+
+// Output selectors that make HEY print something other than a JSON envelope. When any is
+// present, hey-axi hands the command to HEY untouched and prints HEY's output as-is.
+export const RAW_OUTPUT_FLAGS = ["ids-only", "count", "markdown", "html", "styled", "jq"];
+
+export function valueFlagSet(commands) {
+  const names = new Set([...GLOBAL_VALUE_FLAGS, ...AXI_VALUE_FLAGS].map((name) => `--${name}`));
+  const walk = (nodes) => {
+    for (const node of nodes || []) {
+      for (const flag of node.flags || []) {
+        if (!flag.value) continue;
+        names.add(`--${flag.name}`);
+        if (flag.shorthand) names.add(`-${flag.shorthand}`);
+      }
+      walk(node.subcommands);
+    }
+  };
+  walk(commands);
+  return names;
+}
+
+// Split argv into positional words (for routing) and flag names (for mode selection).
+// The argv itself is never reordered: HEY (cobra) accepts flags anywhere.
+export function scanArgs(argv, valueFlags) {
+  const words = [];
+  const flags = new Set();
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--") {
+      words.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith("-") && arg !== "-") {
+      const [name] = arg.split("=", 1);
+      flags.add(name);
+      if (!arg.includes("=") && valueFlags.has(name)) i += 1;
+      continue;
+    }
+    words.push(arg);
+  }
+  return { words, flags };
+}
+
+export function hasAny(flags, names) {
+  return names.some((name) => flags.has(`--${name}`));
+}
+
+// Remove hey-axi's own flags (and the value of --fields) from argv, keeping order.
+export function stripAxiFlags(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--") {
+      out.push(...argv.slice(i));
+      break;
+    }
+    const [name] = arg.split("=", 1);
+    if (AXI_BOOLEAN_FLAGS.some((flag) => name === `--${flag}`)) continue;
+    if (AXI_VALUE_FLAGS.some((flag) => name === `--${flag}`)) {
+      if (!arg.includes("=")) i += 1;
+      continue;
+    }
+    out.push(arg);
+  }
+  return out;
+}
+
+// Value of a value flag (`--fields a,b` or `--fields=a,b`); the last one wins.
+export function flagValue(argv, name) {
+  let value;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--") break;
+    if (argv[i] === `--${name}`) value = argv[i + 1];
+    else if (argv[i].startsWith(`--${name}=`)) value = argv[i].slice(name.length + 3);
+  }
+  return value;
+}
+
+const flagName = (flag) => (flag.startsWith("--") ? flag : flag.slice(0, 2));
+
+export function flagLabel(flag) {
+  const short = flag.shorthand ? `, -${flag.shorthand}` : "";
+  return `--${flag.name}${short}${flag.value ? " <value>" : ""}`;
+}
+
+// AXI: reject unknown flags (and missing required ones) before HEY is ever called.
+// Returns null, or { unknown: [...] } / { missing: [...] }.
+export function validateFlags(node, flags) {
+  const allowed = new Set([
+    ...[...GLOBAL_VALUE_FLAGS, ...GLOBAL_BOOLEAN_FLAGS, ...AXI_BOOLEAN_FLAGS, ...AXI_VALUE_FLAGS].map((name) => `--${name}`),
+    ...GLOBAL_SHORTHANDS,
+  ]);
+  for (const flag of node.flags || []) {
+    allowed.add(`--${flag.name}`);
+    if (flag.shorthand) allowed.add(`-${flag.shorthand}`);
+  }
+  const unknown = [...flags].map(flagName).filter((flag) => !allowed.has(flag));
+  if (unknown.length) return { unknown: [...new Set(unknown)] };
+  if (flags.has("--help") || flags.has("-h")) return null;
+  const missing = (node.flags || [])
+    .filter((flag) => /\(required\)$/.test(flag.desc || ""))
+    .filter((flag) => !flags.has(`--${flag.name}`) && !(flag.shorthand && flags.has(`-${flag.shorthand}`)))
+    .map((flag) => `--${flag.name}`);
+  return missing.length ? { missing } : null;
+}