@gobius/t3ctl 0.2.1 → 0.4.0

package/README.md

@@ -19,8 +19,8 @@ npm i -g @gobius/t3ctl
 # 2. mint a token — run this on the machine hosting T3 Code
 npx t3 auth session issue --label t3ctl --ttl 30d --token-only
 
-# 3. register that host under a short name of your choosing
-t3ctl host add laptop http://localhost:3773 eyJ2Ijox...
+# 3. register that host — t3ctl probes it and names it after the machine
+t3ctl host add http://localhost:3773 eyJ2Ijox...
 
 # 4. see everything
 t3ctl ls
@@ -81,15 +81,41 @@ t3ctl ls --json | jq -r '.projects[].threads[] | select(.status=="running") | .t
 The JSON shape is `{projects: [{host, id, title, workspaceRoot, threads: [{id,
 title, branch, status, provider, updatedAt}]}], unreachable: [{host, error}]}`.
 
-### `t3ctl host add <name> <origin> <token>`
+### `t3ctl host add <origin> [token] [--name <name>]`
 
-Register (or overwrite) a host. `<name>` is whatever you want to call it locally;
-`<origin>` is a scheme + host + optional port, with any trailing slash trimmed.
+Register (or update) a host. `<origin>` is a scheme + host + optional port, with
+any trailing slash trimmed — the scheme is required.
+
+Before writing anything, t3ctl fetches the host's environment descriptor from
+`/.well-known/t3/environment`. That endpoint is unauthenticated, so it confirms
+you are pointed at a real T3 Code server *before* a token is involved: a wrong
+origin fails with `not a T3 Code server` instead of a confusing 401 on your first
+`ls`. The descriptor's `environmentId`, `label` and `serverVersion` are stored
+alongside the token.
 
 ```sh
-t3ctl host add desktop https://studio.tailnet-1234.ts.net eyJ2Ijox...
+t3ctl host add https://studio.tailnet-1234.ts.net eyJ2Ijox...
 ```
 
+The host is named after the machine's own label (`SPR-Gobius-D` becomes
+`spr-gobius-d`); pass `--name` to choose your own. Re-running `host add` for an
+origin you already have updates that entry in place and keeps the stored token if
+you don't pass a new one.
+
+t3ctl warns you when:
+
+- the new host's `serverVersion` differs from your other hosts — the API is not a
+  stable public interface, so a version split is worth knowing about
+- an origin you already registered now reports a **different `environmentId`**,
+  meaning it points at a different machine than it used to and the stored token
+  belongs to the old one
+
+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 rm <name>`
 
 ```sh
@@ -98,7 +124,8 @@ t3ctl host rm desktop
 
 ### `t3ctl hosts`
 
-List registered hosts with truncated tokens. `t3ctl host` with no subcommand does
+List registered hosts, probing each one in parallel for its label, environment id
+(shortened), server version and reachability. `t3ctl host` with no subcommand does
 the same thing.
 
 ```sh
@@ -106,10 +133,13 @@ t3ctl hosts
 ```
 
 ```
-laptop           http://localhost:3773  token:eyJ2Ijox…
-desktop          https://studio.tailnet-1234.ts.net  token:eyJ2Ijox…
+● laptop         SPR-Gobius-D       9d9d9921  0.0.38-nightly.20260901.1250  http://localhost:3773
+✕ desktop        Desktop            11111111  0.0.31-nightly.20260801.0900  https://studio.tailnet-1234.ts.net  cannot reach …
 ```
 
+Unreachable hosts are dimmed and show the values last recorded, not live ones.
+`ls` deliberately does *not* probe — it stays a single request per host.
+
 ### `t3ctl project create <title> <workspace-root>`
 
 Register an existing directory on the host as a project. The path is resolved
@@ -126,7 +156,7 @@ t3ctl project create t3ctl ~/Code/t3ctl
 ### `t3ctl thread create <project> <title>`
 
 Create a thread. This produces an **idle thread with no messages** — it does not
-start the agent. Use `thread start` for that.
+start the agent. Use `thread send` for that.
 
 ```sh
 t3ctl thread create t3ctl "rewrite the readme for users" --branch docs/readme
@@ -146,13 +176,15 @@ Flags:
 `--model` splits on the **first** slash, so slashed model names work as-is:
 `--model opencode/github-copilot/gpt-5.4`.
 
-### `t3ctl thread start <thread> <message...>`
+### `t3ctl thread send <thread> <message...>`
 
-Send a message and run the agent. Everything after the thread reference is the
+Send a message to a thread and run the agent. This is how you continue a
+conversation — it is the same thing the app does for every message you type,
+first or fiftieth. Aliased as `thread start`, the name it shipped under in 0.2.0. Everything after the thread reference is the
 message — no quoting needed.
 
 ```sh
-t3ctl thread start "rewrite the readme" move the endpoint tables into CONTRIBUTING.md
+t3ctl thread send "rewrite the readme" move the endpoint tables into CONTRIBUTING.md
 ```
 
 ```
@@ -165,13 +197,42 @@ started rewrite the readme for users
 
 Accepts `--model`, `--runtime-mode`, `--interaction-mode`, and `--host`. Unlike
 `thread create`, `--model` has no default here: the thread's existing model is
-reused unless you override it. Use `--interaction-mode plan` to make the agent
-plan instead of edit:
+reused unless you override it.
+
+### `t3ctl thread rename <thread> <new title...>`
+
+Rename a thread. Useful when a thread was created from a script and ended up with
+a title like a filename.
 
 ```sh
-t3ctl thread start "flaky release workflow" --interaction-mode plan why does the tag job race?
+t3ctl thread rename "probe well-known" Verify hosts with the environment descriptor
 ```
 
+### `t3ctl thread retitle <thread> [--timeout <seconds>]`
+
+Ask the server to derive a title from the thread's own content, instead of
+supplying one.
+
+```sh
+t3ctl thread retitle "probe well-known"
+```
+
+This is a **request, not a guarantee**. The server records the intent and expects
+something downstream to generate the title; in practice it sometimes clears the
+request a few seconds later without producing one, and reports no error when it
+does. So `retitle` watches the thread afterwards and tells you which happened:
+
+```
+asked the server to retitle Build t3ctl: a CLI for controlling T3 Code hosts  (seq 677390)
+no title was generated — the server cleared the request without producing one.
+  The title is still "Build t3ctl: a CLI for controlling T3 Code hosts". Set one directly:
+    t3ctl thread rename 861645a3-... <title...>
+```
+
+It exits non-zero when no title appears, so a script can tell. Waits 30s by
+default; `--timeout` changes that. If you need the rename to be certain, use
+`thread rename`, which sets the title directly.
+
 ### `t3ctl thread interrupt <thread>`
 
 Stop the turn that's currently running.
@@ -219,7 +280,7 @@ Write commands act on one host. With a single host registered, that one is
 implied. With more than one, pass `--host`:
 
 ```sh
-t3ctl thread start --host desktop "api rate limits" pick this back up
+t3ctl thread send --host desktop "api rate limits" pick this back up
 ```
 
 Otherwise you get `multiple hosts; pass --host <laptop|desktop>`.
@@ -264,9 +325,9 @@ reachable URL works.** There's nothing to configure beyond `host add`.
 and give each host its own short name:
 
 ```sh
-t3ctl host add laptop  http://localhost:3773                  eyJ2Ijox...
-t3ctl host add desktop https://studio.tailnet-1234.ts.net     eyJ2Ijox...
-t3ctl host add builder http://10.0.0.42:3773                  eyJ2Ijox...
+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 ls -t
 ```
 
@@ -274,8 +335,10 @@ t3ctl ls -t
 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 implemented in t3ctl** — the transports above are the options
-today.
+tailnet) is **not planned**: the relay's `dpop-token` exchange only accepts a
+Clerk *session* JWT carrying the relay audience, and its allowed scopes are keyed
+by `client_id`, which is pinned to `t3-mobile` and `t3-web`. A third-party CLI has
+no way to present either. The transports above are the options.
 
 ## Limitations
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gobius/t3ctl",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "Controller CLI for T3 Code hosts — list and drive threads across machines",
   "keywords": [

package/t3ctl.mjs

@@ -22,7 +22,7 @@ const writeHosts = (hosts) => {
 
 const snapshot = async (host) => {
   const res = await fetch(`${host.origin}/api/orchestration/snapshot`, {
-    headers: { authorization: `Bearer ${host.token}` },
+    headers: host.token ? { authorization: `Bearer ${host.token}` } : {},
     signal: AbortSignal.timeout(host.timeoutMs ?? 15000),
   });
   if (!res.ok) throw new Error(`${host.name}: HTTP ${res.status} ${await res.text().catch(() => '')}`.trim());
@@ -67,7 +67,7 @@ const cmdLs = async (args) => {
   const showAll = args.includes('--all') || args.includes('-a');
   const asJson = args.includes('--json');
   const hosts = readHosts();
-  if (!hosts.length) return console.error('No hosts registered. Run: t3ctl host add <name> <origin> <token>');
+  if (!hosts.length) return console.error('No hosts registered. Run: t3ctl host add <origin> <token>');
 
   const { ok, failed } = await collect(hosts);
 
@@ -111,22 +111,135 @@ const cmdLs = async (args) => {
   for (const f of failed) console.error(`\n\x1b[31munreachable\x1b[0m ${f.host.name}: ${f.error}`);
 };
 
-const cmdHost = (args) => {
+// ---- host registry ------------------------------------------------------
+// The descriptor at /.well-known/t3/environment is UNAUTHENTICATED, so probing
+// it answers "is anyone home, and is it T3 Code?" without a token — a wrong
+// origin fails here instead of as a baffling 401 on the first real call.
+// Schema: ExecutionEnvironmentDescriptor in packages/contracts/src/environment.ts.
+
+const DESCRIPTOR_PATH = '/.well-known/t3/environment';
+
+const probe = async (origin, timeoutMs = 5000) => {
+  let res;
+  try {
+    res = await fetch(`${origin}${DESCRIPTOR_PATH}`, { signal: AbortSignal.timeout(timeoutMs) });
+  } catch (error) {
+    // Node's fetch reports a bare "fetch failed"; the cause carries the real reason.
+    const why = error.name === 'TimeoutError' ? `no response in ${timeoutMs}ms`
+      : (error.cause?.message ?? error.message);
+    throw new Error(`cannot reach ${origin}: ${why}`);
+  }
+  const notT3 = (why) => new Error(`not a T3 Code server (${DESCRIPTOR_PATH} ${why})`);
+  if (!res.ok) throw notT3(`returned HTTP ${res.status}`);
+  let d;
+  try { d = await res.json(); } catch { throw notT3('is not JSON'); }
+  const missing = ['environmentId', 'label', 'serverVersion'].filter((k) => typeof d?.[k] !== 'string' || !d[k]);
+  if (missing.length) throw notT3(`is missing ${missing.join(', ')}`);
+  return { environmentId: d.environmentId, label: d.label, serverVersion: d.serverVersion };
+};
+
+const shortId = (id) => (id ? id.slice(0, 8) : '-');
+const warn = (message) => console.error(`\x1b[33mwarning\x1b[0m ${message}`);
+
+// The name is what you type in --host, so derive a typeable slug from the label
+// rather than using the label verbatim.
+const slugify = (label) => label.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'host';
+
+const uniqueName = (base, hosts) => {
+  if (!hosts.some((h) => h.name === base)) return base;
+  for (let n = 2; ; n++) if (!hosts.some((h) => h.name === `${base}-${n}`)) return `${base}-${n}`;
+};
+
+const isOrigin = (value) => /^https?:\/\//i.test(value ?? '');
+
+// Two accepted shapes, told apart by the scheme:
+//   host add <origin> [token] [--name <n>]     current
+//   host add <name> <origin> <token>           legacy, still works
+const parseHostAdd = (pos) => {
+  if (isOrigin(pos[0])) return { origin: pos[0], token: pos[1] ?? null, legacy: false };
+  if (isOrigin(pos[1])) return { name: pos[0], origin: pos[1], token: pos[2] ?? null, legacy: true };
+  return null;
+};
+
+const HOST_ADD_USAGE = 'usage: t3ctl host add <origin> [token] [--name <name>]\n' +
+  '       an origin needs a scheme, e.g. http://localhost:3773';
+
+const cmdHostAdd = async (pos, flags, hosts) => {
+  // Validate before any network or registry work so a bare `host add` prints
+  // usage instead of stalling on a probe.
+  const parsed = parseHostAdd(pos);
+  if (!parsed) return usage(HOST_ADD_USAGE);
+  if ('name' in flags && !flags.name) return usage(HOST_ADD_USAGE);
+  if (parsed.legacy) warn('"host add <name> <origin> <token>" is deprecated — use: t3ctl host add <origin> [token] [--name <name>]');
+
+  const origin = parsed.origin.replace(/\/$/, '');
+  const descriptor = await probe(origin);
+  const existing = hosts.find((h) => h.origin === origin);
+
+  // A changed environmentId on a known origin means the origin now points at a
+  // different machine — the stored token almost certainly belongs to the old one.
+  if (existing?.environmentId && existing.environmentId !== descriptor.environmentId) {
+    warn(`${origin} is now a DIFFERENT environment\n` +
+      `  was ${existing.environmentId} (${existing.label ?? 'unknown'})\n` +
+      `  now ${descriptor.environmentId} (${descriptor.label})\n` +
+      `  the token stored for "${existing.name}" was issued by the old one and will likely fail`);
+  }
+
+  const name = flags.name ?? parsed.name ?? existing?.name ??
+    uniqueName(slugify(descriptor.label), hosts);
+  const token = parsed.token ?? existing?.token ?? null;
+
+  const others = hosts.filter((h) => h.name !== name && h.origin !== origin && h.serverVersion);
+  const skewed = [...new Set(others.map((h) => h.serverVersion))].filter((v) => v !== descriptor.serverVersion);
+  if (skewed.length) warn(`serverVersion ${descriptor.serverVersion} differs from other hosts: ${skewed.join(', ')}`);
+
+  writeHosts(hosts.filter((h) => h.name !== name && h.origin !== origin).concat({
+    name, origin, token,
+    environmentId: descriptor.environmentId,
+    label: descriptor.label,
+    serverVersion: descriptor.serverVersion,
+  }));
+  console.log(`added ${bold(name)} -> ${origin}\n  label   ${descriptor.label}\n` +
+    `  env     ${descriptor.environmentId}\n  version ${descriptor.serverVersion}`);
+  if (!token) warn(`no token stored for ${name} — reads will fail until you run: t3ctl host add ${origin} <token>`);
+};
+
+const cmdHostsList = async (hosts) => {
+  if (!hosts.length) return console.log('(no hosts)');
+  const probes = await Promise.allSettled(hosts.map((h) => probe(h.origin)));
+  const drifted = [];
+  hosts.forEach((h, i) => {
+    const p = probes[i];
+    const live = p.status === 'fulfilled' ? p.value : null;
+    if (live && h.environmentId && h.environmentId !== live.environmentId) drifted.push({ h, live });
+    const icon = live ? ICON.running : ICON.error;
+    const label = live?.label ?? h.label ?? '-';
+    const env = shortId(live?.environmentId ?? h.environmentId);
+    const version = live?.serverVersion ?? h.serverVersion ?? '-';
+    // Values for an unreachable host are whatever was last stored, so dim the
+    // whole row to keep remembered data visually distinct from probed data.
+    const cell = (text, width) => (live ? text.padEnd(width) : dim(text.padEnd(width)));
+    console.log(`${icon} ${live ? bold(h.name.padEnd(14)) : dim(h.name.padEnd(14))} ${cell(label, 18)} ${dim(env.padEnd(9))} ${cell(version, 28)} ${dim(h.origin)}` +
+      (live ? '' : ` ${dim(p.reason.message)}`));
+  });
+  for (const { h, live } of drifted) {
+    warn(`${h.name} (${h.origin}) is now a DIFFERENT environment\n` +
+      `  was ${h.environmentId} (${h.label ?? 'unknown'})\n  now ${live.environmentId} (${live.label})`);
+  }
+};
+
+const cmdHost = async (args) => {
   const [sub, ...rest] = args;
+  const { flags, pos } = parseArgs(rest);
   const hosts = readHosts();
-  if (sub === 'add') {
-    const [name, origin, token] = rest;
-    if (!name || !origin || !token) return usage('usage: t3ctl host add <name> <origin> <token>');
-    const next = hosts.filter((h) => h.name !== name).concat({ name, origin: origin.replace(/\/$/, ''), token });
-    writeHosts(next);
-    console.log(`added ${name} -> ${origin}`);
-  } else if (sub === 'rm') {
-    writeHosts(hosts.filter((h) => h.name !== rest[0]));
-    console.log(`removed ${rest[0]}`);
-  } else {
-    if (!hosts.length) return console.log('(no hosts)');
-    for (const h of hosts) console.log(`${h.name.padEnd(16)} ${h.origin}  ${dim('token:' + h.token.slice(0, 8) + '…')}`);
+  if (sub === 'add') return cmdHostAdd(pos, flags, hosts);
+  if (sub === 'rm') {
+    if (!pos[0]) return usage('usage: t3ctl host rm <name>');
+    writeHosts(hosts.filter((h) => h.name !== pos[0]));
+    console.log(`removed ${pos[0]}`);
+    return;
   }
+  return cmdHostsList(hosts);
 };
 
 
@@ -135,7 +248,7 @@ const cmdHost = (args) => {
 // commandId is the idempotency key, so retries are safe.
 // Schemas: packages/contracts/src/orchestration.ts in pingdotgg/t3code.
 
-const VALUE_FLAGS = ['host', 'model', 'branch', 'runtime-mode', 'interaction-mode', 'worktree'];
+const VALUE_FLAGS = ['host', 'model', 'branch', 'runtime-mode', 'interaction-mode', 'worktree', 'name'];
 
 const parseArgs = (argv) => {
   const flags = {}, pos = [];
@@ -155,7 +268,7 @@ const pickHost = (flags) => {
     if (!h) throw new Error(`no such host: ${flags.host}`);
     return h;
   }
-  if (!hosts.length) throw new Error('no hosts registered — run: t3ctl host add <name> <origin> <token>');
+  if (!hosts.length) throw new Error('no hosts registered — run: t3ctl host add <origin> <token>');
   if (hosts.length > 1) throw new Error(`multiple hosts; pass --host <${hosts.map((h) => h.name).join('|')}>`);
   return hosts[0];
 };
@@ -163,7 +276,7 @@ const pickHost = (flags) => {
 const dispatch = async (host, command) => {
   const res = await fetch(`${host.origin}/api/orchestration/dispatch`, {
     method: 'POST',
-    headers: { authorization: `Bearer ${host.token}`, 'content-type': 'application/json' },
+    headers: { ...(host.token ? { authorization: `Bearer ${host.token}` } : {}), 'content-type': 'application/json' },
     body: JSON.stringify(command),
     signal: AbortSignal.timeout(host.timeoutMs ?? 15000),
   });
@@ -251,15 +364,88 @@ const cmdProject = async (args) => {
   console.log(`created project ${bold(title)} on ${host.name}\n  id   ${projectId}\n  root ${workspaceRoot}\n  seq  ${sequence}`);
 };
 
+
+// thread.meta.update also accepts regenerateTitle:true, which asks the server to
+// derive a title from the thread's own content instead of taking one from us.
+const cmdThreadRename = async (thread, host, title) => {
+  const { sequence } = await dispatch(host, {
+    type: 'thread.meta.update', commandId: crypto.randomUUID(), threadId: thread.id, title,
+  });
+  console.log(`renamed ${dim(thread.title || thread.id)} -> ${bold(title)}\n  seq ${sequence}`);
+};
+
+// Lighter than the full snapshot; retitle polls this so it does not refetch every
+// thread's history once a second.
+const threadDetail = async (host, threadId) => {
+  const res = await fetch(`${host.origin}/api/orchestration/threads/${threadId}?turnLimit=1`, {
+    headers: { authorization: `Bearer ${host.token}` },
+    signal: AbortSignal.timeout(host.timeoutMs ?? 15000),
+  });
+  if (!res.ok) throw new Error(`${host.name}: HTTP ${res.status}`);
+  return (await res.json()).thread;
+};
+
+// `regenerateTitle` does NOT rename anything by itself. The server records an
+// intent marker (`titleRegeneration: {requestId, startedAt}`) and expects something
+// downstream to generate a title and write it back. Observed on a live server: the
+// marker is sometimes cleared a few seconds later with the title untouched, and no
+// error is reported anywhere — not in the event, the command receipt, or the server
+// trace. So we dispatch, then watch, and say what actually happened.
+const cmdThreadRetitle = async (thread, host, timeoutSeconds) => {
+  const before = thread.title;
+  const { sequence } = await dispatch(host, {
+    type: 'thread.meta.update', commandId: crypto.randomUUID(), threadId: thread.id,
+    regenerateTitle: true,
+  });
+  console.log(`asked the server to retitle ${bold(before || thread.id)}${dim(`  (seq ${sequence})`)}`);
+
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  let sawMarker = false;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 1500));
+    const current = await threadDetail(host, thread.id);
+    if (current.title && current.title !== before) {
+      console.log(`retitled -> ${bold(current.title)}`);
+      return;
+    }
+    if (current.titleRegeneration) { sawMarker = true; continue; }
+    if (sawMarker) break; // marker appeared and was cleared, title unchanged
+  }
+
+  console.error(
+    `\x1b[33mno title was generated\x1b[0m — the server ${sawMarker ? 'cleared the request without producing one' : `did not act on it within ${timeoutSeconds}s`}.\n` +
+    `  The title is still "${before}". Set one directly:\n` +
+    `    t3ctl thread rename ${thread.id} <title...>`,
+  );
+  process.exitCode = 1;
+};
+
 const cmdThread = async (args) => {
   const [sub, ...rest] = args;
   const { flags, pos } = parseArgs(rest);
-  if (sub === 'start' || sub === 'interrupt') {
+  // `send` is the accurate name: thread.turn.start posts a message to a thread and
+  // runs a turn, which is exactly what the UI does for every message, first or not.
+  // `start` stays as an alias because it shipped in 0.2.0.
+  const isSend = sub === 'send' || sub === 'start';
+
+  if (sub === 'rename' || sub === 'retitle') {
+    const [ref, ...titleParts] = pos;
+    if (!ref) return usage(`usage: t3ctl thread ${sub} <thread>` + (sub === 'rename' ? ' <new title...>' : ''));
+    const title = titleParts.join(' ');
+    if (sub === 'rename' && !title) return usage('usage: t3ctl thread rename <thread> <new title...>');
+    const host = pickHost(flags);
+    const target = resolveThread(await snapshot(host), ref);
+    return sub === 'retitle'
+      ? cmdThreadRetitle(target, host, Number(flags.timeout) > 0 ? Number(flags.timeout) : 30)
+      : cmdThreadRename(target, host, title);
+  }
+
+  if (isSend || sub === 'interrupt') {
     // Validate arguments before touching the host registry, so `t3ctl thread
-    // start` with no args prints usage instead of "no hosts registered".
+    // send` with no args prints usage instead of "no hosts registered".
     const [ref, ...rest2] = pos;
-    if (!ref) return usage(`usage: t3ctl thread ${sub} <thread>` + (sub === 'start' ? ' <message...>' : ''));
-    if (sub === 'start' && rest2.length === 0) return usage('usage: t3ctl thread start <thread> <message...>');
+    if (!ref) return usage(`usage: t3ctl thread ${sub} <thread>` + (isSend ? ' <message...>' : ''));
+    if (isSend && rest2.length === 0) return usage(`usage: t3ctl thread ${sub} <thread> <message...>`);
     const host = pickHost(flags);
     const thread = resolveThread(await snapshot(host), ref);
     if (sub === 'interrupt') return cmdThreadInterrupt(thread, host);
@@ -309,14 +495,18 @@ if (!commands[cmd]) {
   console.log(`t3ctl — control T3 Code hosts
 
   t3ctl ls [-t|--threads] [-a|--all] [--json]   list projects and threads across hosts
-  t3ctl host add <name> <origin> <token>        register a host
+  t3ctl host add <origin> [token] [--name <n>]  register a host (probes it first)
   t3ctl host rm <name>                          remove a host
-  t3ctl hosts                                   list registered hosts
+  t3ctl hosts                                   list hosts and probe each one
 
   t3ctl project create <title> <root>           create a project for an existing dir
   t3ctl thread create <project> <title>         start a thread (--model inst/model,
                                                 --branch, --host)
-  t3ctl thread start <thread> <message...>      send a message and run the agent
+  t3ctl thread send <thread> <message...>       send a message and run the agent
+                                                (alias: start)
+  t3ctl thread rename <thread> <title...>       rename a thread
+  t3ctl thread retitle <thread> [--timeout n]   ask the server to derive a title
+                                                (warns if it produces none)
   t3ctl thread interrupt <thread>               stop the running turn
   t3ctl thread settle <thread>                  settle a thread (also: archive,
                                                 unarchive, unpin, delete)`);