@gobius/t3ctl 0.4.0 → 0.6.0

package/README.md

@@ -113,8 +113,48 @@ t3ctl warns you when:
 The token is optional so you can register a host before minting one, but reads
 will fail until you add it.
 
-The older `t3ctl host add <name> <origin> <token>` form still works and prints a
-deprecation notice.
+### `t3ctl host add <ssh-target> [--name <name>] [--ttl <duration>]`
+
+Register a host given **only its ssh login** — no URL, no token, no port:
+
+```sh
+t3ctl host add agent@goobles-agentbox
+```
+
+That one command bootstraps the machine end to end:
+
+1. **Probes it over ssh** for a running T3 Code server. The server records its
+   port in `~/.t3/userdata/server-runtime.json` on the remote, so the port is
+   discovered, never assumed (it is 3773 or whatever free port the server fell
+   back to).
+2. **Installs the server if none is running** — `t3 service install`, T3 Code's
+   own per-user launchd/systemd service (no sudo; macOS and Linux). The exact
+   `t3` CLI version is resolved locally via npm (`latest`, falling back to
+   `nightly`); override with `--t3-version <version-or-tag>`. The remote npm
+   output streams past — a cold cache can download for a few minutes.
+3. **Mints a token for you** — `t3 auth session issue` on the remote, labeled
+   `t3ctl:<name>`, TTL 30d by default (`--ttl` changes it). The session id is
+   printed along with the exact revoke command for that host.
+4. **Tunnels to it** — an ssh ControlMaster forwards a local port to the remote
+   server (loopback-only by design; nothing is exposed on the remote's network).
+   The master outlives t3ctl, and every command silently rebuilds it when it
+   dies or the remote port changed.
+
+Registering again for the same login is idempotent: it refreshes the tunnel and
+reuses the stored token unless the login now lands on a *different machine*
+(different `environmentId`), in which case a fresh token is minted.
+
+Give it a name with `--name` (otherwise it is named after the remote's own
+machine label, same as the origin form). Notes:
+
+- `t3ctl host rm <name>` tears the tunnel down with the entry.
+- **macOS remotes need someone logged in at the console** — a launchd agent
+  starts at login, so an ssh install with nobody logged in installs fine but
+  cannot start the server. Linux (systemd user service) has no such gap.
+- If the remote lacks node for non-interactive shells, install Node there (a
+  version manager may need configuring for non-login shells); if a native
+  dependency fails to build, a C toolchain is missing (`build-essential` /
+  `gcc-c++` / `xcode-select --install`).
 
 ### `t3ctl host rm <name>`
 
@@ -255,6 +295,82 @@ t3ctl thread delete "scratch experiment"
 
 `delete` is not prompted and not undoable from t3ctl — check with `ls -t` first.
 
+### `t3ctl export prompts --since <date> [--until <date>]`
+
+Every prompt you typed in a window, across every registered host, with the
+project each one happened in. Read-only, and built for other tools to consume
+rather than for reading yourself — time trackers, activity logs, weeknotes.
+
+```sh
+t3ctl export prompts --since 2026-09-14 --until 2026-09-15
+```
+```
+29 prompts  2026-09-14T00:00:00.000Z -> 2026-09-15T00:00:00.000Z
+
+agentbox  29  local state.sqlite
+  @clients/dsl  28
+  t3ctl          1
+```
+
+| Option | |
+|---|---|
+| `--since <date>` | Required. Start of the window, inclusive. |
+| `--until <date>` | End of the window, exclusive. Defaults to now. |
+| `--host <name>` | Just this host. Defaults to all of them. |
+| `--watch <path>` | Only projects under this root. Repeatable. Defaults to `~/Code`. |
+| `--json` | The full records instead of the summary. |
+
+A bare `YYYY-MM-DD` is a **UTC** day boundary, not local midnight — the stored
+timestamps are UTC and an export should mean the same window wherever it runs.
+Pass a full ISO instant (`2026-09-14T09:00:00+02:00`) when you want a different
+edge. The window is half-open: `[since, until)`.
+
+`--watch` is also the filter. A prompt in a project outside every watched root
+is not exported, because it has no marker to file it under.
+
+With `--json`:
+
+```json
+{
+  "messages": [
+    {
+      "host": "agentbox",
+      "threadId": "f54ddbd8-92e1-402b-b228-a45e948e2f08",
+      "messageId": "8e7ea607-39db-4572-9373-92d3ac764bc7",
+      "createdAt": "2026-09-14T10:32:47.421Z",
+      "text": "which data is being fetched from /api/data?",
+      "workspaceRoot": "/home/agent/Code/@clients/dsl",
+      "marker": "@clients/dsl"
+    }
+  ],
+  "unreachable": []
+}
+```
+
+`text` is the prompt on one line: `<user_query>` wrappers removed, whitespace
+collapsed. `marker` is the project path relative to the watched root it sits
+under — prefixed with the host name for every host but the local one, since two
+machines routinely hold the same repo at the same path.
+
+A host that can't be read lands in `unreachable` and the rest still return, so
+one asleep laptop doesn't cost you the export. The exit code is non-zero only
+when *every* host failed.
+
+#### How each host is read
+
+Same rows either way; only the cost differs.
+
+| Host | How | Cost |
+|---|---|---|
+| Origin on loopback | Reads `~/.t3/userdata/state.sqlite` directly | One query |
+| Anything else | Snapshot, then one fetch per thread that could match | N+1 requests |
+
+The snapshot is filtered by each thread's `updatedAt` before anything is
+fetched, so a host with hundreds of idle threads still only requests the ones
+active in the window. The database is in WAL mode, so reading it alongside a
+running T3 Code is safe and needs no copy — which matters, because it runs to
+hundreds of megabytes.
+
 ## Referring to projects and threads
 
 You rarely need to paste a UUID.
@@ -312,13 +428,17 @@ settled shows as `running`.
 t3ctl only ever stores an origin string, so **any transport that gives a host a
 reachable URL works.** There's nothing to configure beyond `host add`.
 
+- **SSH login** — `t3ctl host add you@box` does everything: server install if
+  needed, token minting, and a managed tunnel (see its section above). Good for
+  hosts you don't want exposed at all.
 - **Tailscale** — on the host, `npx t3 serve --tailscale-serve` publishes it at
   `https://machine.tailnet.ts.net/`. Register that URL.
 - **LAN** — `npx t3 serve --host 0.0.0.0` (or a specific interface), then register
   `http://192.168.1.x:3773`. Read the URL `t3 serve` prints; it picks another port
   if the default is taken.
-- **SSH port-forward** — `ssh -N -L 3773:localhost:3773 you@box`, then register
-  `http://localhost:3773`. Good for hosts you don't want exposed at all.
+- **Manual SSH port-forward** — `ssh -N -L 3773:localhost:3773 you@box` in a
+  terminal you keep open, then register `http://localhost:3773`. The `host add
+  you@box` form automates exactly this and keeps the forward alive for you.
 
 **One token per host.** Tokens are issued by the server they belong to, so run
 `npx t3 auth session issue --label t3ctl --ttl 30d --token-only` on each machine
@@ -328,11 +448,12 @@ and give each host its own short name:
 t3ctl host add http://localhost:3773               eyJ2Ijox...
 t3ctl host add https://studio.tailnet-1234.ts.net  eyJ2Ijox...
 t3ctl host add http://10.0.0.42:3773               eyJ2Ijox...
+t3ctl host add you@elsewhere                       # token minted for you
 t3ctl ls -t
 ```
 
-`ls` then fans out to all three at once. Machines that are asleep or offline show
-up as `unreachable` and don't block the rest.
+`ls` then fans out to all of them at once. Machines that are asleep or offline
+show up as `unreachable` and don't block the rest.
 
 T3 Code's own **T3 Connect relay** (what the mobile app uses when you're off your
 tailnet) is **not planned**: the relay's `dpop-token` exchange only accepts a
@@ -349,14 +470,16 @@ Worth knowing before you build a workflow on this:
   and payloads can change without warning** and a T3 Code update may break t3ctl
   until it catches up.
 - **A host is only reachable while its T3 Code server is running.** t3ctl can't
-  wake a machine, launch a server, or queue work for later. If the desktop app is
-  closed and no `t3 serve` is running, that host is `unreachable`.
+  wake a machine or queue work for later. If the desktop app is closed and no
+  `t3 serve` is running, that host is `unreachable` — except an ssh-registered
+  host, whose boot service keeps a server running (on macOS only while someone
+  is logged in at that console).
 - **`thread create` doesn't run anything.** It leaves an idle thread with no
   messages — a state the desktop UI never produces. Follow it with `thread start`,
   or the thread just sits there.
 - **Not everything the API supports is wired up.** No `pin`, `unsettle`,
-  `snooze`/`unsnooze`, no reading message content, no live tailing of a running
-  turn. `unpin` exists without `pin` because only some of these share a payload
+  `snooze`/`unsnooze`, no live tailing of a running turn. `export prompts` reads
+  your own prompts; nothing reads agent output. `unpin` exists without `pin` because only some of these share a payload
   shape — see [CONTRIBUTING.md](CONTRIBUTING.md).
 - **`ls` fetches full snapshots.** Fine interactively; too heavy to poll in a
   loop.