hey-axi 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (21) hide show
  1. package/README.md +29 -15
  2. package/package.json +1 -1
  3. package/skills/hey-axi/SKILL.md +48 -45
  4. package/skills/hey-axi/references/commands.md +36 -33
  5. package/src/activity.js +160 -0
  6. package/src/args.js +75 -10
  7. package/src/arity.js +94 -0
  8. package/src/cli.js +373 -136
  9. package/src/errors.js +111 -31
  10. package/src/examples.js +57 -0
  11. package/src/guide.js +21 -2
  12. package/src/home-path.js +12 -0
  13. package/src/home.js +48 -16
  14. package/src/hooks.js +176 -23
  15. package/src/manifest.json +699 -251
  16. package/src/policy.js +154 -11
  17. package/src/router.js +45 -11
  18. package/src/scope.js +177 -0
  19. package/src/shape.js +184 -53
  20. package/src/text.js +3 -3
  21. package/src/version.js +1 -1
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  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.
4
4
 
5
- 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.
5
+ 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** (154 runnable command paths, including the `login`/`logout` aliases, plus the `box <id>`-style shortcuts) by routing from a snapshot of HEY's own `hey commands --json` catalog. See [CHANGELOG.md](CHANGELOG.md) for what changed in each release.
6
6
 
7
7
  ## Install
8
8
 
@@ -24,7 +24,7 @@ hey-axi uses `$HEY_BIN` if it's set, and otherwise finds `hey` on `PATH`. launch
24
24
  ## Usage
25
25
 
26
26
  ```bash
27
- hey-axi # home view: who/what, the Imbox (10 threads), next commands
27
+ hey-axi # home view: scope, last session, Imbox count + 10 threads, next commands
28
28
  hey-axi box view imbox # TOON: summary, a few columns per thread, notice, help
29
29
  hey-axi box imbox # HEY's shortcut forms work too
30
30
  hey-axi --account 2 search --from a@b.com # global flags anywhere
@@ -32,7 +32,9 @@ hey-axi thread read 123 # bodies cut at 1000 chars with "(tru
32
32
  hey-axi thread read 123 --full # HEY's complete, untouched result
33
33
  hey-axi box view imbox --fields id,subject,creator.email_address # choose columns (--fields all = every field)
34
34
  hey-axi thread read 123 --json # the same shaped output as compact JSON
35
- hey-axi box view imbox --quiet # data only, no envelope
35
+ hey-axi box view imbox --quiet # drop HEY's summary/notice/breadcrumbs; keep data, count and hints
36
+ hey-axi reply 123 --message - < note.txt # message body from stdin (saved as a draft)
37
+ hey-axi setup scope --label Acme # per-directory home view (.hey-axi.json)
36
38
  hey-axi --version # bare hey-axi version (fast path); `hey-axi version` adds HEY's
37
39
  hey-axi box view imbox --ids-only # raw HEY output (also --count/--markdown/--html/--styled/--jq)
38
40
  hey-axi set-aside group view 4 --limit 5 # three-word commands
@@ -41,12 +43,15 @@ hey-axi move --help # usage, flags, examples, notes (no H
41
43
 
42
44
  ### Output shaping
43
45
 
44
- - **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.
45
- - **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.
46
+ - **Home view.** `hey-axi` with no arguments prints `bin`, `description`, the `scope`, a one-line `last_session` summary (when session capture is on), a `count` of threads, the 10 newest threads, and `help` lines with next commands (including how to see the rest). If HEY is missing, signed out or failing, it prints `status` with the fix and still exits 0.
47
+ - **Directory scope.** `hey-axi setup scope --label Acme` (or `--box`, `--search`, `--account`, `--limit`) writes `.hey-axi.json` in the current directory. The home view in that directory (or any subdirectory) then shows that label, box or search instead of the Imbox, and carries `--account` into every suggested command. `--status` shows it, `--remove` deletes it, and re-running with the same values is a no-op.
48
+ - **Minimal fields.** List commands show at most 4 columns (usually an id, the thread id, sender and subject). 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.
46
49
  - **Truncation.** Strings longer than 1000 characters (120 in list cells) are cut and marked `… (truncated, N chars total)`, and a `help` line suggests `--full`.
47
- - **Aggregates and empty states.** `count: N of T total` when HEY reports a total; ``empty: 0 results for `…` `` when a list is empty.
48
- - **Help lines.** HEY's breadcrumbs become ``help: Run `hey-axi …` to …``, and HEY's hints are rewritten to name `hey-axi`.
49
- - **Fail loud.** Unknown flags and missing required flags (`move` without `--to`) exit 2 before HEY runs, listing the valid flags.
50
+ - **Aggregates and empty states.** Every list gets a `count`: `N of T total` when HEY reports a total (in `meta` or next to the list), `N total` when HEY says the list is complete, `N shown; more available` with a `help` line naming `--all`/`--page`/`--limit` when HEY says there's more, and `N shown; no more pages reported` when HEY says neither. Lists of plain values and results holding several lists (`2 todos, 1 habits`) are counted too. An empty list prints ``empty: 0 results for `…` ``, and a command with no data prints `result: no data returned`. Non-JSON success output is wrapped as `ok: true` + `output`.
51
+ - **Help lines.** A list always ends with a next step: HEY's own, or (when HEY gives none) the matching `view`/`show` command. HEY's breadcrumbs (next-command hints) become ``help: Run `hey-axi …` to …``, HEY's hints are rewritten to name `hey-axi`, and `--account`/`--base-url` are carried into them.
52
+ - **Fail loud.** Unknown commands (with "did you mean"), unknown flags, flags with a missing or wrongly typed value (`--limit abc`), missing or extra arguments (`thread read` without an id), and missing required flags (`move` without `--to`) all exit 2 before HEY runs, with the valid usage.
53
+ - **Idempotent mutations.** For state-setting commands (`seen`, `todo complete`, `label add`, `move`, `screener approve`, `timetrack stop`, name-based `create`s, …), when HEY's failure says that command's own end state already holds ("already seen", "already completed", "already exists", …), and for deletes whose target is already gone, hey-axi prints `ok: true`, `noop: true` and exits 0. The patterns are per command (`END_STATES` in `src/policy.js`); a generic conflict, any read, any send or reply, a `move` whose failure names a different box than `--to`, "already exists" on a create, and a delete whose not-found names something other than the target stay errors.
54
+ - **Complete per-command help.** `hey-axi <command> --help` lists arguments, every flag with its type and default, global flags, and 2-3 examples, with no HEY call.
50
55
  - `--full` turns all of this off, and `--json` prints the same shaped result as compact JSON.
51
56
 
52
57
  ### How each kind of command runs
@@ -54,9 +59,10 @@ hey-axi move --help # usage, flags, examples, notes (no H
54
59
  | Kind | Commands | Behavior |
55
60
  |---|---|---|
56
61
  | JSON (default) | almost everything | `hey … --json` → TOON (or compact JSON with `--json`) |
57
- | Raw output | `--ids-only`, `--count`, `--markdown`, `--html`, `--styled`, `--jq`; `shell-completion generate`; `timetrack export` without `--output` | HEY's output is printed as-is |
58
- | Stream | `watch` | NDJSON relayed line by line as events arrive; Ctrl-C/SIGTERM forwarded to HEY |
59
- | Interactive | `tui`, `auth login`/`login`, `setup …`, `mcp`, `upgrade` | HEY gets the terminal (inherited stdio). `tui` refuses to start without a TTY |
62
+ | Raw output | `--ids-only`, `--count`, `--markdown`, `--html`, `--styled`, `--jq`; `shell-completion generate`; `timetrack export` without `--output` | HEY's output is printed as-is once HEY succeeds; on failure only a structured error is printed |
63
+ | Stream | `watch` | Each event printed as it arrives, as a TOON block followed by a blank line (`--json`: HEY's NDJSON, one line per event); Ctrl-C/SIGTERM forwarded to HEY |
64
+ | Needs a person | `tui`, `mcp`, the `setup` wizard, `auth login`/`login` without `--token`/`--cookie` | Refused (exit 2) unless `--interactive` is passed, terminal or not, with the alternative (e.g. pass `--token`, or ask the user to run `hey-axi auth login --interactive` in their terminal). With `--interactive`, HEY gets the terminal (for `mcp`, its stdio, so an MCP client can register `hey-axi mcp --interactive`); the others also need a real terminal |
65
+ | Captured | other `setup …` commands, `upgrade`, `auth login --token …` | Run with stdin closed, `HEY_NONINTERACTIVE=1` and `EDITOR`/`VISUAL=false`, so nothing can wait for input; output is shaped like any other command |
60
66
 
61
67
  ### Safety rails
62
68
 
@@ -65,20 +71,28 @@ hey-axi move --help # usage, flags, examples, notes (no H
65
71
  - `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`).
66
72
  - If you pass `--draft` or `--dry-run` yourself, hey-axi adds and marks nothing.
67
73
  - **Credentials stay out of agent context.** `auth token` needs `--allow-secret` or `HEY_AXI_ALLOW_SECRETS=1`.
68
- - hey-axi's own flags (`--allow-send`, `--allow-secret`, `--fields`, `--full`) are never forwarded to HEY.
74
+ - **Content-first.** `compose`, `reply`, `draft edit`, `journal write`, `contact note set` and `bulk-reply send` must be given their content (`--message`, `--message -` for stdin, or a positional) and are refused (exit 2) otherwise, so HEY never opens an editor.
75
+ - hey-axi's own flags (`--allow-send`, `--allow-secret`, `--interactive`, `--fields`, `--full`) are never forwarded to HEY. Switches take no value: `--draft=false` or `--allow-send=false` is refused (exit 2) rather than guessed at.
69
76
 
70
77
  ### Errors and exit codes
71
78
 
72
- 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**.
79
+ Errors are printed as structured TOON on stdout: `ok: false`, `error`, a `kind`, and, when HEY gave them, `code`, `hint` and `meta`, plus a `help` next step. HEY's error text is translated too: only its first meaningful line is kept, stack traces, panics and terminal escapes are dropped, and debug keys (`stack`, `trace`, …) are removed from `meta`. On success HEY's stderr notices (warnings, `next_page: …`) go to stderr without that noise.
80
+
81
+ | Exit | Meaning |
82
+ |---|---|
83
+ | 0 | success (including no-op mutations and empty results) |
84
+ | 1 | the command failed; `kind` says why: `not_found`, `auth`, `forbidden`, `rate_limited`, `network`, `api_error`, `ambiguous`, `hey_missing`, `command_error` |
85
+ | 2 | usage error (`kind: usage`): unknown command/flag/field, bad flag value, missing or extra arguments, missing required flag or content, a switch given a value (`--draft=false`), blocked send, a person-only command without `--interactive`, or a usage error reported by HEY |
73
86
 
74
87
  ## Agent integrations: session hook or skill
75
88
 
76
89
  There are two ways to give an agent hey-axi. You only need one:
77
90
 
78
- 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.
91
+ 1. **Session hooks (recommended where supported):** `hey-axi setup hooks` registers the home view as session-start context, and a session-end hook (`hey-axi hook session-end`), 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.
79
92
  - `--project` writes to the current directory's `.claude/`, `.codex/` and `.opencode/` instead.
80
93
  - `--status` reports what's installed, and `--remove` removes only hey-axi's entries.
81
94
  - 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.
95
+ - The session-end hook records a one-line summary (at most 300 characters) of what the session did (drafts saved, messages sent, other changes; command names and numeric ids only, never message content) under `$XDG_STATE_HOME/hey-axi` (or `$HEY_AXI_STATE_DIR`), and the next home view shows it as `last_session`. Nothing is recorded unless `setup hooks` turned it on, and `setup hooks --remove` turns it off. Entries are tagged with the agent session (`CLAUDE_CODE_SESSION_ID` in Claude Code, `CODEX_THREAD_ID` in Codex, or `HEY_AXI_SESSION_ID`) so concurrent sessions in one directory stay apart. OpenCode has no exact session-end event, so its plugin records on `session.idle`/`session.deleted`.
82
96
  - Note that the hook puts Imbox senders and subjects into every session's context.
83
97
  2. **Agent skill (broader support, loads on demand):** see below.
84
98
 
@@ -110,7 +124,7 @@ See [docs/listing.md](docs/listing.md) for how hey-axi gets listed on skills.sh
110
124
  npm run refresh-manifest # runs only `hey version` and `hey commands`
111
125
  ```
112
126
 
113
- 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.
127
+ hey-axi routes only from the snapshot, so an unknown command is rejected immediately (exit 2, with suggestions) without running HEY. New HEY commands become available after a refresh and a hey-axi release. A weekly GitHub Action (`manifest-drift`) fails when the snapshot falls behind the latest HEY release.
114
128
 
115
129
  ## Development
116
130
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hey-axi",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Agent-ergonomic AXI wrapper for Basecamp's HEY CLI: TOON output, send-to-draft safety, and a shareable agent skill",
5
5
  "keywords": [
6
6
  "axi",
package/skills/hey-axi/SKILL.md CHANGED
@@ -2,7 +2,7 @@
2
2
  name: hey-axi
3
3
  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.
4
4
  license: MIT
5
- 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.
5
+ compatibility: Requires Node.js 20+ (commands run as `npx -y hey-axi`), the HEY CLI (`hey`, v1.7.0 or newer) signed in to a HEY account, and network access to app.hey.com.
6
6
  metadata:
7
7
  author: TangentialSolutions
8
8
  repository: https://github.com/TangentialSolutions/hey-axi
@@ -10,116 +10,119 @@ metadata:
10
10
 
11
11
  # hey-axi: HEY email for agents
12
12
 
13
- `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>`.
13
+ `hey-axi` runs Basecamp's HEY CLI (`hey`) and prints compact TOON. Lists show at most four columns and a count, long text is cut (the total size is shown), and suggestions name `hey-axi` commands. Every `hey` command works: `npx -y hey-axi <same args as hey>`.
14
+
15
+ Examples below use `npx -y hey-axi`, which works without installing anything. If `hey-axi` is installed globally (`npm i -g hey-axi`), drop the `npx -y`.
14
16
 
15
17
  ## 1. Start here
16
18
 
17
- 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.
19
+ Run `npx -y hey-axi` with no arguments. It shows the mail for this directory's scope (the Imbox unless a `.hey-axi.json` says otherwise), a `count`, what the last session here did, and what to do next. If HEY is missing or signed out, it prints a `status` line and the fix instead.
18
20
 
19
21
  <!-- generated:home:start -->
20
22
  <!-- Generated by scripts/gen-skill.js from src/guide.js, the same text the home view prints. Do not edit by hand. -->
21
23
  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
22
24
 
23
25
  Next steps the home view suggests:
24
- - Run `hey-axi thread read <topic_id>` to read a thread
25
- - Run `hey-axi box view imbox --limit 50` for more (also feed, papertrail, aside, later)
26
- - Run `hey-axi search "<query>"` to search mail
27
- - Run `hey-axi screener list` for senders waiting to be screened
28
- - Run `hey-axi reply <topic_id> --message "..."` to draft a reply (not sent without --allow-send)
29
- - Run `hey-axi --help` for all commands; lists take --fields a,b / --fields all, long text --full
26
+ - Run `npx -y hey-axi thread read <topic_id>` to read a thread
27
+ - Run `npx -y hey-axi box view imbox --limit 50` for more (also feed, papertrail, aside, later)
28
+ - Run `npx -y hey-axi search "<query>"` to search mail
29
+ - Run `npx -y hey-axi screener list` for senders waiting to be screened
30
+ - Run `npx -y hey-axi reply <topic_id> --message "..."` to draft a reply (not sent without --allow-send)
31
+ - Run `npx -y hey-axi --help` for all commands; lists take --fields a,b / --fields all, long text --full
30
32
  <!-- generated:home:end -->
31
33
 
32
34
  Problems:
33
- - `hey-axi: command not found`: run it as `npx -y hey-axi …`, or install it (see "Install" below).
34
- - `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`).
35
- - `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).
36
- - `hey-axi doctor` finds other login and config problems. `hey-axi version` shows both versions.
35
+ - `status: HEY CLI not found` (`kind: hey_missing`): install `hey`, or set `HEY_BIN=/path/to/hey` (cron/launchd jobs usually need `HEY_BIN=$HOME/.local/bin/hey`).
36
+ - `status: not signed in` (`kind: auth`): ask the **user** to run `npx -y hey-axi auth login --interactive` in their own terminal. It opens a browser, so without `--interactive` it is refused (exit 2); `tui`, `mcp` and the `setup` wizard work the same way. Never pass `--interactive` yourself. Don't try to sign in for them, and never print tokens (`auth token` is blocked unless `--allow-secret` is passed).
37
+ - `npx -y hey-axi doctor` finds other login and config problems. `npx -y hey-axi version` shows both versions.
37
38
 
38
39
  ## 2. Read and triage
39
40
 
40
41
  ```bash
41
- hey-axi box list # boxes and their ids
42
- hey-axi box view imbox --limit 25 # rows in a box (imbox, feed, papertrail, aside, later, …)
43
- hey-axi thread read <topic_id> # the thread (long bodies cut; --full for all)
44
- hey-axi search "invoice" --from a@b.com --date last_30_days
45
- hey-axi screener list # senders waiting to be screened
46
- hey-axi set-aside view | hey-axi bubble list | hey-axi draft list
42
+ npx -y hey-axi box list # boxes and their ids
43
+ npx -y hey-axi box view imbox --limit 25 # rows in a box (imbox, feed, papertrail, aside, later, …)
44
+ npx -y hey-axi thread read <topic_id> # the thread (long bodies cut; --full for all)
45
+ npx -y hey-axi search "invoice" --from a@b.com --date last_30_days
46
+ npx -y hey-axi screener list # senders waiting to be screened
47
+ npx -y hey-axi set-aside view | npx -y hey-axi bubble list | npx -y hey-axi draft list
47
48
  ```
48
49
 
49
50
  **Which id to use.** Each `box view` row has an `id` (the box item) and a `topic_id` (the thread):
50
51
  - `topic_id` goes to `thread read`, `reply` and `forward`.
51
52
  - `id` goes to `seen`, `unseen`, `move`, `label`, `bubble`, `trash`, `spam` and `ignore`.
52
- - A row with kind `bundle` has no `topic_id`. Open it with `hey-axi bundle view <id>`.
53
+ - A row with kind `bundle` has no `topic_id`. Open it with `npx -y hey-axi bundle view <id>`.
53
54
  - Screener commands take the clearance `id` from `screener list`. These aren't contact ids.
54
55
 
55
56
  ```bash
56
- hey-axi seen <id>... hey-axi unseen <id>...
57
- hey-axi move <id>... --to feed # imbox | feed | aside | later | papertrail
58
- hey-axi label add <id>... --to "Receipts"
59
- hey-axi bubble up <id>... --tomorrow # or --now | --on <date> | --weekend | --next-week
60
- hey-axi screener approve <clearance-id> hey-axi screener deny <clearance-id>
61
- hey-axi trash <id>... hey-axi spam <id>... hey-axi ignore <id>...
57
+ npx -y hey-axi seen <id>... npx -y hey-axi unseen <id>...
58
+ npx -y hey-axi move <id>... --to feed # imbox | feed | aside | later | papertrail
59
+ npx -y hey-axi label add <id>... --to "Receipts"
60
+ npx -y hey-axi bubble up <id>... --tomorrow # exactly one of --now | --on <date> | --tomorrow | --weekend | --next-week
61
+ npx -y hey-axi screener approve <clearance-id>
62
+ npx -y hey-axi trash <id>... npx -y hey-axi spam <id>... npx -y hey-axi ignore <id>...
62
63
  ```
63
64
 
64
65
  `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.
65
66
 
66
- 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.
67
+ Mutations are idempotent: when the desired state already holds (already seen, already deleted), the answer is `noop: true` with exit 0, not an error.
68
+
69
+ Output includes HEY's breadcrumb hints as `help` lines (with your `--account` carried over), plus `Run … --all for all N` when a list was cut. Follow them instead of guessing.
67
70
 
68
71
  ## 3. Writing mail: drafts by default
69
72
 
70
73
  - `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.
71
74
  ```bash
72
- hey-axi reply <topic_id> --message "Thanks, Thursday works."
73
- hey-axi compose --to a@b.com --subject "Hi" --message "…"
74
- hey-axi draft list | hey-axi draft show <draft-id>
75
+ npx -y hey-axi reply <topic_id> --message "Thanks, Thursday works."
76
+ npx -y hey-axi compose --to a@b.com --subject "Hi" --message "…"
77
+ cat reply.md | npx -y hey-axi reply <topic_id> --message -
78
+ npx -y hey-axi draft list | npx -y hey-axi draft show <draft-id>
75
79
  ```
80
+ - The message is required (`--message`, `--message-html`, `--attach`, or `--message -` to read stdin): HEY never opens an editor under hey-axi. The same goes for `journal write --content`, `contact note set --note` and `draft edit` (pass the fields to change).
76
81
  - `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.
77
82
  - 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.
78
83
 
79
- ## 4. Output: fields, truncation, modes
84
+ ## 4. Output: fields, truncation, counts, modes
80
85
 
81
- - **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.
86
+ - **Lists show at most four columns** (for example `box view`: `id, topic_id, from, subject`). Pick others with `--fields id,subject,seen,at,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. `npx -y hey-axi <command> --help` shows the defaults.
82
87
  - **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.
83
- - 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`).
88
+ - **Every list has a `count`**: `N of T total`, `N total` (HEY said the list is complete), `N shown; more available` (then a help line says how to get the rest), or `N shown; no more pages reported` (HEY gave no total and no further page). Empty lists say `empty: 0 results for …`.
84
89
 
85
90
  | Want | Use |
86
91
  |---|---|
87
- | Default: summary, data, help lines, as TOON | (nothing) |
92
+ | Default: summary, count, data, help lines, as TOON | (nothing) |
88
93
  | The same as compact JSON | `--json` |
89
- | Data only | `--quiet` |
94
+ | Less: data, count, empty state and hints only | `--quiet` |
90
95
  | HEY's complete, untouched result | `--full` (combine with `--json` for raw JSON) |
91
96
  | Raw HEY output | `--ids-only`, `--count`, `--markdown`, `--html`, `--styled`, `--jq '<expr>'` |
92
- | Help for one command: usage, flags, examples, notes (no network) | `hey-axi <command> --help` |
97
+ | Help for one command: usage, arguments, flags with defaults, examples, notes (no network) | `npx -y hey-axi <command> --help` |
93
98
 
94
- 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.
99
+ Everything is checked before HEY runs (exit 2, with the fix inline): unknown commands (with "did you mean"), unknown flags (the valid ones are listed), flags without a value, values of the wrong type (`--limit abc`), missing or extra arguments (quote multi-word text), missing required flags such as `move --to`. Global flags like `--account <id|all>` can go anywhere.
95
100
 
96
101
  ## 5. Watching for changes
97
102
 
98
- `hey-axi watch` streams HEY's NDJSON one line at a time until it's interrupted. Use bounded forms in agent sessions:
103
+ `npx -y hey-axi watch` streams each event as it arrives (a TOON block per event, separated by blank lines; add `--json` for HEY's NDJSON, one line per event) until it's interrupted. Use bounded forms in agent sessions:
99
104
 
100
105
  ```bash
101
- hey-axi watch --box imbox --events new --exit-on-first --timeout 10m
106
+ npx -y hey-axi watch --box imbox --events new --exit-on-first --timeout 10m
102
107
  ```
103
108
 
104
109
  Lines also include `ready`, `disconnected` and `resync`. On `resync`, re-read that box.
105
110
 
106
111
  ## 6. Errors and exit codes
107
112
 
108
- 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.
113
+ Errors are TOON on stdout: `ok: false`, `error`, `kind` (`usage`, `not_found`, `auth`, `forbidden`, `rate_limited`, `network`, `api_error`, `ambiguous`, `hey_missing`, `command_error`), HEY's `code`/`hint`/`meta` when it gave them, and a `help` line with the next step. Exit codes: **0** success (including no-ops) · **1** error · **2** usage error or refusal (unknown command/flag/field, bad argument, blocked send, needs the user). Read `hint`/`help` before you retry.
109
114
 
110
115
  ## Install
111
116
 
112
117
  ```bash
113
118
  # HEY CLI (macOS/Linux)
114
119
  curl -fsSL https://hey.com/install-cli | bash # or: brew install --cask basecamp/tap/hey
115
- hey auth login # the user runs this once, interactively
120
+ npx -y hey-axi auth login --interactive # the user runs this once, in their own terminal
116
121
 
117
- # hey-axi
122
+ # hey-axi (optional: every example here also works as npx -y hey-axi …)
118
123
  npm i -g hey-axi # puts `hey-axi` on PATH
119
124
  ```
120
125
 
121
- 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.
122
-
123
- 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.
126
+ Session hook (the alternative to this skill; you only need one): `npx -y hey-axi setup hooks` (user-invoked) shows the home view at the start of every Claude Code, Codex and OpenCode session and records what each session did for the next one. `--project` limits it to one directory, and `--remove` undoes it. `npx -y hey-axi setup scope --label <name>` focuses a directory's home view on one label, box or search.
124
127
 
125
128
  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 CHANGED
@@ -2,9 +2,9 @@
2
2
 
3
3
  <!-- Generated by scripts/gen-skill.js from src/manifest.json (hey 1.7.0). Do not edit by hand. -->
4
4
 
5
- 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]`.
6
- `hey-axi <command> --help` shows usage, flag descriptions, examples and notes, offline.
7
- 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).
5
+ Every command from HEY CLI 1.7.0 (154 runnable paths, including the `login`/`logout` aliases and shortcut forms such as `box <name>`). Run each as `npx -y hey-axi <command> [args] [flags]` (just `hey-axi …` when it is installed globally).
6
+ `npx -y hey-axi <command> --help` shows usage, arguments, every flag with its default, 2-3 examples and notes, offline.
7
+ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--fields <a,b|all>`, `--full`, `--ids-only`, `--count`, `--markdown`, `--html`, `--styled`, `--jq <expr>`. Unknown commands, flags and arguments, flags without a value and values of the wrong type are rejected before HEY runs (exit 2).
8
8
 
9
9
  | Command | What it does | Flags | hey-axi behavior |
10
10
  |---|---|---|---|
@@ -13,33 +13,33 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
13
13
  | `account use` | Set the default linked mail account | | |
14
14
  | `attachment list` | List a thread's attachments | `--allow-partial` | fields: id, filename, content_type, byte_size |
15
15
  | `attachment save` | Save an attachment to disk | `--force` `--output <v>` | |
16
- | `auth login` | Authenticate with the HEY server | `--cookie <v>` `--no-browser` `--token <v>` | interactive (user runs it) |
16
+ | `auth login` | Authenticate with the HEY server | `--cookie <v>` `--no-browser` `--token <v>` | |
17
17
  | `auth logout` | Clear stored credentials | | |
18
18
  | `auth refresh` | Force token refresh | | |
19
19
  | `auth status` | Show authentication status | | |
20
20
  | `auth token` | Print access token to stdout | `--stored` | refused unless `--allow-secret` |
21
- | `box` | List HEY boxes and their email threads | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
21
+ | `box` | List HEY boxes and their email threads | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
22
22
  | `box list` | List your HEY boxes | `--all` `--limit <v>` | fields: id, kind, name |
23
- | `box view` | List email threads in a box | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
24
- | `bubble list` | List bubbled-up and scheduled email threads | `--all` `--limit <v>` | fields: id, topic_id, from, subject, seen, at, bubbles_up |
23
+ | `box view` | List email threads in a box | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
24
+ | `bubble list` | List bubbled-up and scheduled email threads | `--all` `--limit <v>` | fields: id, topic_id, subject, bubbles_up |
25
25
  | `bubble pop` | Cancel bubble-ups | | |
26
26
  | `bubble up` | Bubble email threads up | `--next-week` `--now` `--on <v>` `--tomorrow` `--weekend` | |
27
27
  | `bulk-reply preview` | Preview threads and recipients without sending | | |
28
28
  | `bulk-reply send` | Send one reply to multiple threads | `--attach <v>` `--message <v>` `--message-html <v>` | refused unless `--allow-send` |
29
29
  | `bulk-reply undo` | Recall a delayed bulk reply | | |
30
- | `bundle` | List the unseen threads a bundle groups | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
31
- | `bundle view` | List the unseen threads a bundle groups | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
30
+ | `bundle` | List the unseen threads a bundle groups | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
31
+ | `bundle view` | List the unseen threads a bundle groups | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
32
32
  | `calendar list` | List calendars | | fields: id, name, kind, owned |
33
33
  | `clip create` | Save text from an email entry | `--content <v>` | |
34
34
  | `clip delete` | Delete a saved clip | | |
35
35
  | `clip list` | List the newest page of passages clipped from email | | fields: id, content, topic_id, at |
36
- | `collection` | List and manage email collections | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
36
+ | `collection` | List and manage email collections | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
37
37
  | `collection add` | Add email threads to a collection | `--to <v>` | |
38
38
  | `collection create` | Create a collection | `--summary <v>` | |
39
39
  | `collection list` | List your email collections | `--all` `--limit <v>` | fields: id, name |
40
40
  | `collection remove` | Remove email threads from a collection | `--from <v>` | |
41
41
  | `collection update` | Update a collection | `--name <v>` `--summary <v>` | |
42
- | `collection view` | List email threads in a collection | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
42
+ | `collection view` | List email threads in a collection | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
43
43
  | `commands` | List all available commands | | |
44
44
  | `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` |
45
45
  | `config set` | Set a configuration value in the global config | | |
@@ -56,7 +56,7 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
56
56
  | `contact note show` | Read a private contact note | | |
57
57
  | `contact show` | View a contact | | |
58
58
  | `contact show-again` | Show a hidden contact again | | |
59
- | `contact threads` | List every thread with a contact | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
59
+ | `contact threads` | List every thread with a contact | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
60
60
  | `contact unbundle` | List a contact's mail separately | | |
61
61
  | `contact update` | Edit a contact | `--alias <v>` `--email <v>` `--name <v>` | |
62
62
  | `doctor` | Find login and configuration problems | | |
@@ -66,11 +66,11 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
66
66
  | `draft send` | Deliver a draft | | refused unless `--allow-send` |
67
67
  | `draft show` | Read a draft back | | |
68
68
  | `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>` | |
69
- | `event day` | List the events of one day, as HEY draws it | `--all` `--limit <v>` | fields: id, title, starts_at, ends_at, calendar |
69
+ | `event day` | List the events of one day, as HEY draws it | `--all` `--limit <v>` | fields: id, title, starts_at, ends_at |
70
70
  | `event delete` | Delete an event | | |
71
71
  | `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>` | |
72
- | `event list` | List calendar events | `--all` `--calendar <v>` `--ends-on <v>` `--limit <v>` `--starts-on <v>` | fields: id, title, starts_at, ends_at, calendar |
73
- | `event week` | List the events of one week, as HEY draws it | `--all` `--limit <v>` | fields: id, title, starts_at, ends_at, calendar |
72
+ | `event list` | List calendar events | `--all` `--calendar <v>` `--ends-on <v>` `--limit <v>` `--starts-on <v>` | fields: id, title, starts_at, ends_at |
73
+ | `event week` | List the events of one week, as HEY draws it | `--all` `--limit <v>` | fields: id, title, starts_at, ends_at |
74
74
  | `forward` | Forward the latest message in a thread | `--bcc <v>` `--cc <v>` `--message <v>` `--message-html <v>` `--to <v>` | refused unless `--allow-send` |
75
75
  | `habit complete` | Mark a habit as complete for a date | `--date <v>` | |
76
76
  | `habit create` | Create a habit | `--color <v>` `--days <v>` `--icon <v>` `--name <v>` | |
@@ -82,40 +82,43 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
82
82
  | `journal list` | List journal entries | `--all` `--calendar <v>` `--ends-on <v>` `--limit <v>` `--starts-on <v>` | fields: id, starts_at, content |
83
83
  | `journal read` | Read a journal entry (default: today) | | |
84
84
  | `journal write` | Write or edit a journal entry (default: today) | `--content <v>` `--content-html <v>` | |
85
- | `label` | List and manage email labels | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
85
+ | `label` | List and manage email labels | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
86
86
  | `label add` | Add a label to email threads | `--to <v>` | |
87
87
  | `label create` | Create a label and add it to email threads | | |
88
88
  | `label list` | List your email labels | `--all` `--limit <v>` | fields: id, name |
89
89
  | `label remove` | Remove labels from email threads | `--from <v>` | |
90
- | `label view` | List email threads with a label | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
91
- | `login` | Authenticate with the HEY server | `--cookie <v>` `--no-browser` `--token <v>` | interactive (user runs it) |
90
+ | `label view` | List email threads with a label | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
91
+ | `login` | Authenticate with the HEY server | `--cookie <v>` `--no-browser` `--token <v>` | |
92
92
  | `logout` | Clear stored credentials | | |
93
- | `mcp` | Serve HEY to MCP clients over stdio | `--domains <v>` `--read-only` | interactive (user runs it) |
93
+ | `mcp` | Serve HEY to MCP clients over stdio | `--domains <v>` `--read-only` | |
94
94
  | `move` | Move email threads to another box | `--to <v>` | |
95
95
  | `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` |
96
96
  | `screener approve` | Let a sender through | `--box <v>` `--seen` | |
97
97
  | `screener clear` | Empty the Screener without deciding | | |
98
98
  | `screener deny` | Turn a sender away | `--spam` | |
99
- | `screener history` | List the senders already screened | `--all` `--page <v>` | fields: id, status, name, email_address, decided |
100
- | `screener list` | List the senders waiting to be screened | `--all` `--page <v>` | fields: id, name, email_address, subject, topic_id |
101
- | `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 |
99
+ | `screener history` | List the senders already screened | `--all` `--page <v>` | fields: id, status, email_address, decided |
100
+ | `screener list` | List the senders waiting to be screened | `--all` `--page <v>` | fields: id, email_address, subject, topic_id |
101
+ | `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: topic_id, subject, from, at |
102
102
  | `search filters` | List available search refinement values | | |
103
103
  | `seen` | Mark email threads as seen | | |
104
+ | `set-aside` | List and group email threads in Set Aside | | |
105
+ | `set-aside group` | List and manage groups in Set Aside | | |
104
106
  | `set-aside group add` | Add email threads to a Set Aside group | `--to <v>` | |
105
107
  | `set-aside group create` | Gather email threads into a new Set Aside group | | |
106
108
  | `set-aside group delete` | Break up a Set Aside group | | |
107
109
  | `set-aside group list` | List the groups in Set Aside | | fields: id, thread_count |
108
110
  | `set-aside group remove` | Take email threads out of their Set Aside group | | |
109
- | `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 |
110
- | `set-aside view` | List email threads in Set Aside | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
111
- | `setup` | Set up HEY for first use | `--silent-success` `--skip-agents` `--skip-omarchy` | interactive (user runs it) |
112
- | `setup agents` | Install or remove HEY coding-agent integrations | `--remove` | interactive (user runs it) |
113
- | `setup claude` | Connect Claude Code to HEY | | interactive (user runs it) |
114
- | `setup codex` | Connect Codex to HEY | | interactive (user runs it) |
115
- | `setup omarchy` | Install hey into the Omarchy desktop | `--no-notify` `--notify` `--remove` | interactive (user runs it) |
111
+ | `set-aside group view` | List email threads in a Set Aside group | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
112
+ | `set-aside view` | List email threads in Set Aside | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
113
+ | `setup` | Set up HEY for first use | `--silent-success` `--skip-agents` `--skip-omarchy` | |
114
+ | `setup agents` | Install or remove HEY coding-agent integrations | `--remove` | |
115
+ | `setup claude` | Connect Claude Code to HEY | | |
116
+ | `setup codex` | Connect Codex to HEY | | |
117
+ | `setup omarchy` | Install hey into the Omarchy desktop | `--no-notify` `--notify` `--remove` | |
116
118
  | `share` | Get a sharing link for an email thread | | |
117
119
  | `shell-completion generate` | Print a completion script to stdout | | raw output |
118
120
  | `shell-completion install` | Install shell completions where your shell will find them | `--force` | |
121
+ | `skill` | Manage the embedded agent skill | | |
119
122
  | `skill install` | Install the hey skill globally for your coding agents | | |
120
123
  | `snippet create` | Create a reusable email snippet | `--content <v>` `--content-html <v>` `--name <v>` | |
121
124
  | `snippet delete` | Delete a reusable email snippet | | |
@@ -132,7 +135,7 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
132
135
  | `timetrack delete` | Delete a time track | | |
133
136
  | `timetrack edit` | Edit a completed time track | `--category <v>` `--end <v>` `--notes <v>` `--start <v>` | |
134
137
  | `timetrack export` | Export completed time tracks as CSV | `--force` `--output <v>` | raw CSV unless `--output <file>` |
135
- | `timetrack list` | List completed time tracks | `--all` `--category <v>` `--limit <v>` | fields: id, starts_at, ends_at, category, notes |
138
+ | `timetrack list` | List completed time tracks | `--all` `--category <v>` `--limit <v>` | fields: id, starts_at, ends_at, category |
136
139
  | `timetrack start` | Start time tracking | | |
137
140
  | `timetrack stop` | Stop time tracking | `--category <v>` | |
138
141
  | `todo add` | Create a new todo | `--date <v>` `--title <v>` | |
@@ -141,12 +144,12 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
141
144
  | `todo list` | List todos | `--all` `--calendar <v>` `--ends-on <v>` `--limit <v>` `--starts-on <v>` | fields: id, title, starts_at, completed_at |
142
145
  | `todo uncomplete` | Mark a todo as incomplete | | |
143
146
  | `trash` | Move email threads to Trash | | |
144
- | `tui` | Launch the interactive terminal UI | `--instance <v>` `--remote` `--screener` `--topic <v>` `--topic-title <v>` | interactive, needs a TTY (user runs it) |
147
+ | `tui` | Launch the interactive terminal UI | `--instance <v>` `--remote` `--screener` `--topic <v>` `--topic-title <v>` | |
145
148
  | `unseen` | Mark email threads as unseen | | |
146
149
  | `unshare` | Turn off an email thread's sharing link | | |
147
- | `upgrade` | Upgrade hey to the latest release | | interactive (user runs it) |
150
+ | `upgrade` | Upgrade hey to the latest release | | |
148
151
  | `version` | Show the installed hey version | | |
149
- | `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 |
152
+ | `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 events (TOON; --json for NDJSON) |
150
153
  | `workflow` | List and manage email workflows | | |
151
154
  | `workflow add` | Add email threads to a workflow stage | `--stage <v>` `--to <v>` | |
152
155
  | `workflow create` | Create an email workflow | | |