trodo-cli 0.2.0 → 0.3.1

package/lib/commands/prompts.js

@@ -0,0 +1,125 @@
+'use strict';
+
+const fs = require('fs');
+const config = require('../config');
+const { client } = require('../http');
+const { print } = require('../output');
+const { usage, pick } = require('../common');
+
+/** What a prompt version is, without who saved it: what `pull` writes and `push` reads. */
+const CONTENT_KEYS = ['messages', 'model', 'tools', 'response_format', 'variables'];
+
+/** A refusal to edit, said as what to do about it. */
+async function editing(prompt, fn) {
+  try { return await fn(); } catch (e) {
+    if (e && e.status === 403 && e.body && e.body.error === 'forbidden_edit') {
+      throw Object.assign(new Error(`You can't change "${prompt}": only its owner and the editors they add can. Ask the owner to add you (prompt page → Editors).`), { exitCode: 1 });
+    }
+    throw e;
+  }
+}
+
+async function resolvePrompt(api, ref) {
+  const { prompts } = await api.get('/prompts');
+  const hit = pick(prompts || [], ref, { kind: 'prompt', listCmd: 'trodo prompts list' });
+  const { prompt } = await api.get(`/prompts/${hit.id}`);
+  return prompt;
+}
+
+/** The version a --version N or --label L names; the newest one otherwise. */
+function versionOf(prompt, flags) {
+  const versions = prompt.versions || [];
+  if (flags.version !== undefined && flags.version !== true) {
+    const v = versions.find((x) => String(x.version_no) === String(flags.version));
+    if (!v) throw usage(`"${prompt.name}" has no version ${flags.version}. \`trodo prompts versions "${prompt.name}"\` lists them.`);
+    return v;
+  }
+  if (flags.label !== undefined && flags.label !== true) {
+    const v = versions.find((x) => (x.labels || []).includes(String(flags.label)));
+    if (!v) throw usage(`No version of "${prompt.name}" has the label "${flags.label}".`);
+    return v;
+  }
+  return versions.reduce((a, b) => (!a || Number(b.version_no) > Number(a.version_no) ? b : a), null);
+}
+
+async function list(_a, flags) {
+  const { prompts } = await client(config.resolve(flags)).get('/prompts', { label: flags.label !== true ? flags.label : undefined, tag: flags.tag !== true ? flags.tag : undefined });
+  print(prompts || [], flags, [['name', 'Prompt', 36], ['current_version', 'Version', 8], ['labels', 'Labels', 24], ['id', 'Id', 36], ['updated_at', 'Updated', 24]]);
+}
+
+/** trodo prompts get PROMPT [--version N | --label production]: one version, whole. */
+async function get([ref], flags) {
+  const prompt = await resolvePrompt(client(config.resolve(flags)), ref);
+  const v = versionOf(prompt, flags);
+  print({ id: prompt.id, name: prompt.name, description: prompt.description, tags: prompt.tags, version: v }, flags);
+}
+
+async function versions([ref], flags) {
+  const prompt = await resolvePrompt(client(config.resolve(flags)), ref);
+  const rows = (prompt.versions || []).map((v) => ({ version_no: v.version_no, labels: v.labels, commit_message: v.commit_message, created_by: v.created_by_email, created_at: v.created_at, content_hash: v.content_hash }));
+  print(rows, flags, [['version_no', 'v', 4], ['labels', 'Labels', 22], ['commit_message', 'Message', 44], ['created_by', 'By', 24], ['created_at', 'At', 24]]);
+}
+
+/** trodo prompts pull PROMPT [--version N | --label L] [-o prompt.json]: the content to edit and push back. */
+async function pull([ref], flags) {
+  const prompt = await resolvePrompt(client(config.resolve(flags)), ref);
+  const v = versionOf(prompt, flags);
+  const out = { name: prompt.name, version_no: v.version_no };
+  for (const k of CONTENT_KEYS) out[k] = v[k];
+  if (flags.out && flags.out !== true) {
+    fs.writeFileSync(String(flags.out), `${JSON.stringify(out, null, 2)}\n`);
+    process.stderr.write(`${prompt.name} v${v.version_no} → ${flags.out}\n`);
+    return;
+  }
+  print(out, flags);
+}
+
+/**
+ * trodo prompts push PROMPT -f prompt.json [--message "why"] [--label staging]
+ * A new version from a file `pull` wrote (or any { messages, model?, tools?,
+ * variables? }). The prompt is made when no prompt has that name. Content equal
+ * to the newest version cuts no version.
+ */
+async function push([ref], flags) {
+  const file = flags.file;
+  if (!file || file === true) throw usage('Usage: trodo prompts push PROMPT -f prompt.json [--message "why"] [--label staging]');
+  let content;
+  try { content = JSON.parse(fs.readFileSync(String(file), 'utf8')); } catch (e) { throw usage(`${file} is not a JSON prompt: ${e.message}`); }
+  if (!Array.isArray(content.messages) || !content.messages.length) throw usage(`${file} has no messages.`);
+  const api = client(config.resolve(flags));
+  const name = ref && ref !== true ? String(ref) : content.name;
+  if (!name) throw usage('Name the prompt.');
+  const { prompts } = await api.get('/prompts');
+  let target = (prompts || []).find((p) => p.id === name || p.name === name);
+  let created = false;
+  if (!target) {
+    const made = await api.post('/prompts', { name, ...(content.description ? { description: content.description } : {}) });
+    target = made.prompt || made;
+    created = true;
+  }
+  const body = { messages: content.messages };
+  for (const k of ['model', 'tools', 'response_format', 'variables']) if (content[k] !== undefined) body[k] = content[k];
+  if (flags.message && flags.message !== true) body.commit_message = String(flags.message);
+  if (flags.label && flags.label !== true) body.labels = [].concat(flags.label).map(String);
+  const out = await editing(name, () => api.post(`/prompts/${target.id}/versions`, body));
+  const v = out.version || {};
+  print({ prompt: name, id: target.id, created, version_no: v.version_no, labels: v.labels, unchanged: Boolean(out.unchanged) }, flags);
+}
+
+/**
+ * trodo prompts label PROMPT VERSION LABEL [--remove]
+ * Moves LABEL (say production) to VERSION. Agents that fetch the prompt by that
+ * label run the new version from their next call.
+ */
+async function label([ref, versionNo, name], flags) {
+  if (!ref || !versionNo || !name) throw usage('Usage: trodo prompts label PROMPT VERSION LABEL [--remove]');
+  const api = client(config.resolve(flags));
+  const prompt = await resolvePrompt(api, ref);
+  const v = versionOf(prompt, { version: versionNo });
+  const out = await editing(prompt.name, () => (flags.remove
+    ? api.del(`/prompts/${prompt.id}/versions/${v.version_no}/label/${encodeURIComponent(String(name))}`)
+    : api.post(`/prompts/${prompt.id}/versions/${v.version_no}/label`, { label: String(name) })));
+  print({ prompt: prompt.name, version_no: v.version_no, ...(out.version ? { labels: out.version.labels } : out) }, flags);
+}
+
+module.exports = { list, get, versions, pull, push, label };

package/lib/commands/runs.js

@@ -4,9 +4,10 @@ const config = require('../config');
 const { client } = require('../http');
 const { print } = require('../output');
 const { buildSpec } = require('./traces');
+const { usage, listQuery, pages, unitVerdicts, int } = require('../common');
 
 const DAY = 86400e3;
-/** A filter's time → { time_start, time_end } for the runs list. */
+/** A filter's time → { time_start, time_end } for the lists. */
 function windowOf(time, now = Date.now()) {
   if (time.from || time.to) return { time_start: time.from || new Date(now - 7 * DAY).toISOString(), time_end: time.to || new Date(now).toISOString() };
   const p = String(time.preset || '7d');
@@ -19,23 +20,99 @@ function windowOf(time, now = Date.now()) {
   return { time_start: new Date(now - n * unit).toISOString(), time_end: new Date(now).toISOString() };
 }
 
-/** trodo runs list [filter flags] [--limit 50] */
+/** trodo runs list [filter flags] [--limit 50] [--offset N] */
 async function listRuns(_args, flags) {
   const api = client(config.resolve(flags));
   const spec = await buildSpec(api, flags, 'runs');
-  const mf = [...spec.filter.modularFilters];
-  if (spec.filter.eval_conditions) mf.push({ category: 'evals', field: 'eval_conditions', operator: 'is', value: spec.filter.eval_conditions });
-  const query = { ...windowOf(spec.filter.time), limit: spec.options.limit || 50 };
-  // The runs list decodes this once more (decodeURIComponent then JSON), as the app sends it.
-  if (mf.length) query.modularFilters = encodeURIComponent(JSON.stringify(mf));
-  const out = await api.get('/runs', query);
-  print(out.runs || out, flags, [['run_id', 'Run', 36], ['agent_name', 'Agent', 30], ['status', 'Status', 8], ['started_at', 'Started', 24], ['duration_ms', 'ms', 8]]);
+  const q = listQuery(spec, windowOf);
+  const rows = await pages(flags, async (limit, offset) => { const out = await api.get('/runs', { ...q, limit, offset }); return out.runs || []; }, { max: 100 });
+  print(rows, flags, [['run_id', 'Run', 36], ['agent_name', 'Agent', 30], ['status', 'Status', 8], ['started_at', 'Started', 24], ['duration_ms', 'ms', 8]]);
 }
 
-/** trodo runs get RUN_ID: the run and its spans. */
+/** The spans of a run as an indented tree, one line each: what a person reads first. */
+function spanTree(spans) {
+  const byId = new Map(spans.map((s) => [s.span_id, s]));
+  const kids = new Map();
+  const roots = [];
+  const order = (a, b) => String(a.started_at || '').localeCompare(String(b.started_at || ''));
+  for (const s of [...spans].sort(order)) {
+    if (s.parent_span_id && byId.has(s.parent_span_id)) {
+      if (!kids.has(s.parent_span_id)) kids.set(s.parent_span_id, []);
+      kids.get(s.parent_span_id).push(s);
+    } else roots.push(s);
+  }
+  const lines = [];
+  const label = (s) => {
+    const bits = [`${s.name || s.tool_name || s.kind}`, `[${s.kind || 'span'}]`];
+    if (s.model) bits.push(s.model);
+    if (s.duration_ms != null) bits.push(`${(Number(s.duration_ms) / 1000).toFixed(2)}s`);
+    const tok = (Number(s.input_tokens) || 0) + (Number(s.output_tokens) || 0);
+    if (tok) bits.push(`${tok} tok`);
+    if (s.status && s.status !== 'ok') bits.push(`✗ ${s.status}${s.error_message ? `: ${String(s.error_message).slice(0, 80)}` : ''}`);
+    bits.push(s.span_id);
+    return bits.join('  ');
+  };
+  const walk = (s, prefix, last, depth) => {
+    lines.push(`${depth ? `${prefix}${last ? '└─ ' : '├─ '}` : ''}${label(s)}`);
+    const c = kids.get(s.span_id) || [];
+    c.forEach((k, i) => walk(k, depth ? `${prefix}${last ? '   ' : '│  '}` : '', i === c.length - 1, depth + 1));
+  };
+  roots.forEach((r, i) => walk(r, '', i === roots.length - 1, 0));
+  return lines.join('\n');
+}
+
+/**
+ * trodo runs get RUN_ID [--tree]: the run, its spans, messages, feedback and
+ * evaluations. --tree prints the span tree instead of JSON.
+ */
 async function getRun([id], flags) {
-  if (!id) { const e = new Error('Usage: trodo runs get RUN_ID'); e.exitCode = 2; throw e; }
-  print(await client(config.resolve(flags)).get(`/runs/${encodeURIComponent(id)}`, { include: 'spans,messages' }), flags);
+  if (!id) throw usage('Usage: trodo runs get RUN_ID [--tree]');
+  const api = client(config.resolve(flags));
+  const [detail, verdicts] = await Promise.all([
+    api.get(`/runs/${encodeURIComponent(id)}`, { include: 'spans,messages' }),
+    api.get(`/eval3/units/run/${encodeURIComponent(id)}/verdicts`).catch(() => null),
+  ]);
+  if (flags.tree) {
+    const r = detail.run || {};
+    const head = `${r.agent_name || 'run'}  ${r.status || ''}  ${r.started_at || ''}  ${r.duration_ms != null ? `${(r.duration_ms / 1000).toFixed(2)}s` : ''}  ${r.run_id || id}`;
+    process.stdout.write(`${head}\n${spanTree(detail.spans || [])}\n`);
+    return;
+  }
+  print({ ...detail, evaluations: unitVerdicts(verdicts) }, flags);
+}
+
+/** trodo runs tree RUN_ID: the span tree alone. */
+const tree = (args, flags) => getRun(args, { ...flags, tree: true });
+
+/**
+ * trodo runs feedback RUN_ID [--thumbs up|down] [--rating 1-5] [--comment TEXT] [--user DISTINCT_ID]
+ * A person's feedback on the run, as the SDK and the run page record it.
+ */
+async function feedback([id], flags) {
+  if (!id) throw usage('Usage: trodo runs feedback RUN_ID --thumbs up|down [--rating 1-5] [--comment TEXT]');
+  const body = {};
+  if (flags.thumbs !== undefined) {
+    const t = String(flags.thumbs);
+    if (!['up', 'down'].includes(t)) throw usage('--thumbs is up or down.');
+    body.satisfaction = t === 'up' ? 'positive' : 'negative';
+  }
+  if (flags.rating !== undefined) {
+    const n = Number(flags.rating);
+    if (!Number.isInteger(n) || n < 1 || n > 5) throw usage('--rating is a whole number from 1 to 5.');
+    body.rating = n;
+  }
+  if (flags.comment !== undefined && flags.comment !== true) body.comment = String(flags.comment);
+  if (flags.user !== undefined && flags.user !== true) body.distinct_id = String(flags.user);
+  if (!Object.keys(body).some((k) => ['satisfaction', 'rating', 'comment'].includes(k))) throw usage('Give --thumbs, --rating or --comment.');
+  print(await client(config.resolve(flags)).post(`/runs/${encodeURIComponent(id)}/feedback`, body), flags);
+}
+
+/** trodo runs search TEXT [--limit 50]: runs whose input, output or spans mention TEXT. */
+async function search(words, flags) {
+  const q = words.join(' ').trim();
+  if (!q) throw usage('Usage: trodo runs search TEXT [--limit 50]');
+  const out = await client(config.resolve(flags)).get('/runs/search', { q, limit: int(flags.limit, 50, 200) });
+  print(out.runs || out, flags, [['run_id', 'Run', 36], ['agent_name', 'Agent', 30], ['status', 'Status', 8], ['started_at', 'Started', 24], ['distinct_id', 'User', 26]]);
 }
 
-module.exports = { list: listRuns, get: getRun, windowOf };
+module.exports = { list: listRuns, get: getRun, tree, feedback, search, windowOf, spanTree };

package/lib/commands/setup.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { print } = require('../output');
+const { usage } = require('../common');
+
+const SKILLS_DIR = path.join(__dirname, '..', '..', 'skills');
+
+/**
+ * trodo setup claude [--global] | trodo setup --dir DIR
+ * Installs the skills this CLI ships (trodo: read and act on traces; trodo-datasets:
+ * training data) where a coding agent finds them: ./.claude/skills (this project),
+ * ~/.claude/skills with --global, or any folder with --dir.
+ */
+async function setup([agent], flags) {
+  let root;
+  if (flags.dir && flags.dir !== true) root = path.resolve(String(flags.dir));
+  else if (agent === 'claude') root = flags.global ? path.join(os.homedir(), '.claude', 'skills') : path.resolve('.claude', 'skills');
+  else throw usage('Usage: trodo setup claude [--global]   or   trodo setup --dir SKILLS_DIR');
+  const installed = [];
+  for (const name of fs.readdirSync(SKILLS_DIR)) {
+    const src = path.join(SKILLS_DIR, name, 'SKILL.md');
+    if (!fs.existsSync(src)) continue;
+    const dest = path.join(root, name);
+    fs.mkdirSync(dest, { recursive: true });
+    fs.copyFileSync(src, path.join(dest, 'SKILL.md'));
+    installed.push(path.join(dest, 'SKILL.md'));
+  }
+  print({ installed }, flags);
+}
+
+module.exports = { setup };

package/lib/commands/spans.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const config = require('../config');
+const { client } = require('../http');
+const { print } = require('../output');
+const { buildSpec } = require('./traces');
+const { windowOf } = require('./runs');
+const { usage, listQuery, pages, unitVerdicts, int } = require('../common');
+
+/** trodo spans list [filter flags] [--limit 50] [--offset N]: newest first. */
+async function list(_args, flags) {
+  const api = client(config.resolve(flags));
+  const spec = await buildSpec(api, flags, 'spans');
+  const q = listQuery(spec, windowOf);
+  const rows = await pages(flags, async (limit, offset) => { const out = await api.get('/spans', { ...q, limit, offset }); return out.spans || []; });
+  print(rows, flags, [['span_id', 'Span', 36], ['name', 'Name', 28], ['kind', 'Kind', 8], ['model', 'Model', 22], ['status', 'Status', 8], ['duration_ms', 'ms', 8], ['run_id', 'Run', 36]]);
+}
+
+/** trodo spans get SPAN_ID: the span with its full input and output, and its evaluations. */
+async function get([id], flags) {
+  if (!id) throw usage('Usage: trodo spans get SPAN_ID');
+  const api = client(config.resolve(flags));
+  const [detail, verdicts] = await Promise.all([
+    api.get(`/spans/${encodeURIComponent(id)}`),
+    api.get(`/eval3/units/span/${encodeURIComponent(id)}/verdicts`).catch(() => null),
+  ]);
+  print({ ...detail, evaluations: unitVerdicts(verdicts) }, flags);
+}
+
+/** trodo spans search TEXT [--limit 50]: spans whose name, input or output mention TEXT. */
+async function search(words, flags) {
+  const q = words.join(' ').trim();
+  if (!q) throw usage('Usage: trodo spans search TEXT [--limit 50]');
+  const out = await client(config.resolve(flags)).get('/spans/search', { q, limit: int(flags.limit, 50, 200) });
+  print(out.spans || out, flags, [['span_id', 'Span', 36], ['name', 'Name', 28], ['kind', 'Kind', 8], ['started_at', 'Started', 24], ['run_id', 'Run', 36]]);
+}
+
+module.exports = { list, get, search };

package/lib/commands/traces.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const fs = require('fs');
+const path = require('path');
 const config = require('../config');
 const { client } = require('../http');
 const { print, sink } = require('../output');
@@ -32,15 +34,79 @@ async function exportTraces(_args, flags) {
   const body = { ...spec };
   if (flags.format) body.format = String(flags.format);
   if (flags.target) body.target = String(flags.target);
-  const out = sink(flags.out && flags.out !== true ? String(flags.out) : null);
+  const dir = flags.dir && flags.dir !== true ? String(flags.dir) : null;
+  if (dir && flags.out) throw Object.assign(new Error('Give -o FILE or --dir DIR, not both.'), { exitCode: 2 });
+  if (dir) fs.mkdirSync(dir, { recursive: true });
+  const out = dir ? null : sink(flags.out && flags.out !== true ? String(flags.out) : null);
   let summary = null;
+  let n = 0;
   for await (const line of api.lines('POST', '/traces/export', { body })) {
     if (line && line._trodo) { summary = line._trodo; continue; }
+    n += 1;
+    if (dir) {
+      // One file per unit, named by what it is: run-<id>.json, span-<id>.json, conversation-<id>.json.
+      const src = line.source || {};
+      const kind = line.unit_kind || (spec.kind === 'eval_results' ? 'verdict' : spec.kind.replace(/s$/, ''));
+      const md = line.metadata || {};
+      const byKind = { span: src.span_id || md.span_id, conversation: src.conversation_id || md.conversation_id, verdict: md.eval_run_id || src.eval_run_id, run: src.run_id || md.run_id };
+      const id = byKind[kind] || src.span_id || src.run_id || src.conversation_id || String(n).padStart(5, '0');
+      fs.writeFileSync(path.join(dir, `${kind}-${String(id).replace(/[^\w.-]/g, '_')}.json`), `${JSON.stringify(line, null, 2)}\n`);
+      continue;
+    }
     // eslint-disable-next-line no-await-in-loop
     await out.write(line);
   }
-  await out.close();
-  if (summary) process.stderr.write(`${summary.rows} ${spec.kind}${summary.skipped ? `, ${summary.skipped} skipped (no input or no target)` : ''}${flags.out ? ` → ${flags.out}` : ''}\n`);
+  if (out) await out.close();
+  if (summary) process.stderr.write(`${summary.rows} ${spec.kind}${summary.skipped ? `, ${summary.skipped} skipped (no input or no target)` : ''}${flags.out ? ` → ${flags.out}` : dir ? ` → ${dir}/` : ''}\n`);
 }
 
-module.exports = { count, export: exportTraces, buildSpec };
+/**
+ * trodo traces stats [filter flags] [--compare]
+ * Count, error rate, latency p50/p95/p99, tokens, cost, feedback, eval
+ * outcomes and the busiest agents for what the filter matches. --compare puts
+ * the window just before it beside it (the last 7 days against the 7 before).
+ */
+async function stats(_args, flags) {
+  const api = client(config.resolve(flags));
+  const spec = await buildSpec(api, flags, flags.kind || 'runs');
+  const current = await api.post('/traces/stats', spec);
+  if (!flags.compare) { print(current, flags); return; }
+  const from = new Date(current.window.from).getTime();
+  const to = new Date(current.window.to).getTime();
+  const prevSpec = { ...spec, filter: { ...spec.filter, time: { from: new Date(from - (to - from)).toISOString(), to: new Date(from).toISOString() } } };
+  const previous = await api.post('/traces/stats', prevSpec);
+  const pct = (a, b) => (b ? Number((((a - b) / b) * 100).toFixed(1)) : null);
+  print({
+    current,
+    previous,
+    change_pct: {
+      units: pct(current.units, previous.units),
+      error_rate: current.error_rate != null && previous.error_rate != null ? Number(((current.error_rate - previous.error_rate) * 100).toFixed(2)) : null,
+      p50_ms: pct(current.latency_ms.p50, previous.latency_ms.p50),
+      p95_ms: pct(current.latency_ms.p95, previous.latency_ms.p95),
+      cost: pct(current.cost, previous.cost),
+    },
+  }, flags);
+}
+
+/** trodo traces agents: the agent names traces carry (what --agent takes), with run counts. */
+async function agents(_a, flags) {
+  const out = await client(config.resolve(flags)).get('/runs/agents');
+  print(out.agents || out, flags, [['agent_name', 'Agent', 40], ['run_count', 'Runs', 8], ['error_count', 'Errors', 8], ['total_cost', 'Cost', 12], ['last_seen_at', 'Last seen', 24]]);
+}
+
+/** trodo traces fields [--agent NAME]: the properties --where can name, run and span, fixed and custom. */
+async function fields(_a, flags) {
+  const agent = flags.agent && flags.agent !== true ? [].concat(flags.agent)[0] : undefined;
+  print(await client(config.resolve(flags)).get('/runs/property-keys', { agent_name: agent }), flags);
+}
+
+/** trodo traces values FIELD [--search TEXT] [--limit 50]: the values one property takes, most common first. */
+async function values([field], flags) {
+  if (!field) throw Object.assign(new Error('Usage: trodo traces values FIELD [--search TEXT]  (trodo traces fields lists them)'), { exitCode: 2 });
+  const agent = flags.agent && flags.agent !== true ? [].concat(flags.agent)[0] : undefined;
+  const out = await client(config.resolve(flags)).get('/runs/property-values', { field, q: flags.search !== true ? flags.search : undefined, agent_name: agent, limit: flags.limit });
+  print(out.values || out, flags, [['value', 'Value', 50], ['count', 'Count', 10]]);
+}
+
+module.exports = { count, export: exportTraces, stats, agents, fields, values, buildSpec };

package/lib/commands/users.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const config = require('../config');
+const { client } = require('../http');
+const { print } = require('../output');
+const { usage } = require('../common');
+
+/** trodo users get DISTINCT_ID [--since 30d]: one user's runs, conversations, cost, evals and feedback, as the user drawer shows. */
+async function get([id], flags) {
+  if (!id) throw usage('Usage: trodo users get DISTINCT_ID');
+  print(await client(config.resolve(flags)).get(`/runs/users/${encodeURIComponent(id)}/profile`, { period: flags.since !== true ? flags.since : undefined }), flags);
+}
+
+module.exports = { get };

package/lib/common.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/** Small pieces every command uses. */
+
+const usage = (msg) => { const e = new Error(msg); e.exitCode = 2; return e; };
+
+/** The one named `ref` (an id, an exact name, or a name in any case) out of `all`. */
+function pick(all, ref, { kind, listCmd, nameKey = 'name', idKeys = ['id'] } = {}) {
+  if (ref == null || ref === '' || ref === true) throw usage(`Name the ${kind} (its name or id).`);
+  const r = String(ref);
+  const hit = all.find((x) => idKeys.some((k) => x[k] != null && String(x[k]) === r))
+    || all.find((x) => x[nameKey] === r)
+    || all.find((x) => String(x[nameKey] || '').toLowerCase() === r.toLowerCase());
+  if (!hit) throw usage(`No ${kind} "${r}". \`${listCmd}\` shows them.`);
+  return hit;
+}
+
+/**
+ * A filter spec (filters.specFromFlags) as the query the Runs, Spans and
+ * Conversations lists read: the time window plus the Traces filter chips,
+ * eval conditions included, sent the way the app sends them.
+ */
+function listQuery(spec, windowOf) {
+  const mf = [...(spec.filter.modularFilters || [])];
+  if (spec.filter.eval_conditions) mf.push({ category: 'evals', field: 'eval_conditions', operator: 'is', value: spec.filter.eval_conditions });
+  const q = { ...windowOf(spec.filter.time) };
+  // The lists decode this once more (decodeURIComponent then JSON), as the app sends it.
+  if (mf.length) q.modularFilters = encodeURIComponent(JSON.stringify(mf));
+  return q;
+}
+
+const int = (v, dflt, max) => {
+  const n = Number.parseInt(v, 10);
+  if (!Number.isFinite(n) || n < 1) return dflt;
+  return max ? Math.min(n, max) : n;
+};
+
+/**
+ * One page, or with --all every page (`max` at a time, up to --max-items,
+ * 10,000 by default): `page(limit, offset)` returns that page's rows.
+ */
+async function pages(flags, page, { dflt = 50, max = 200 } = {}) {
+  if (!flags.all) return page(int(flags.limit, dflt, max), flags.offset);
+  const cap = int(flags['max-items'], 10000, 1000000);
+  const out = [];
+  let offset = Number.parseInt(flags.offset, 10) || 0;
+  for (;;) {
+    // eslint-disable-next-line no-await-in-loop
+    const rows = await page(max, offset);
+    out.push(...rows);
+    if (rows.length < max || out.length >= cap) break;
+    offset += rows.length;
+  }
+  return out.slice(0, cap);
+}
+
+/**
+ * Every eval's verdicts on one unit (GET /eval3/units/:target/:id/verdicts,
+ * grouped by eval) as one list, newest first, each carrying its eval's name.
+ */
+function unitVerdicts(out) {
+  if (!out) return undefined;
+  if (Array.isArray(out.verdicts)) return out.verdicts;
+  const rows = [];
+  for (const l of out.lineages || []) for (const v of l.verdicts || []) rows.push({ lineage_name: l.name, ...v });
+  return rows.sort((a, b) => String(b.created_at || '').localeCompare(String(a.created_at || '')));
+}
+
+module.exports = { usage, pick, listQuery, int, pages, unitVerdicts };

package/lib/config.js

@@ -3,8 +3,13 @@
 /**
  * Where the CLI finds its key and server: TRODO_API_KEY / TRODO_API_URL, else
  * ~/.trodo/config.json (written by `trodo login`, mode 600). A key is a Trodo
- * API key (trodo_mk_…, Settings → MCP); it acts as the person who made
- * it, on its team, with its scopes.
+ * API key (trodo_mk_…, Settings → MCP); it acts as the person who made it, on
+ * its team, with its scopes.
+ *
+ * A key belongs to one team, so the file keeps one per team signed in to:
+ *   { "current_team": "12", "teams": { "12": { "name", "api_key", "api_url" }, … } }
+ * `trodo switch TEAM` changes the current one; `--team TEAM` picks one for a
+ * single command. A file from 0.2 ({ api_key, api_url }) still works.
  */
 const fs = require('fs');
 const os = require('os');
@@ -24,14 +29,50 @@ function write(cfg) {
   const f = file();
   fs.mkdirSync(path.dirname(f), { recursive: true, mode: 0o700 });
   fs.writeFileSync(f, `${JSON.stringify(cfg, null, 2)}\n`, { mode: 0o600 });
+  // `mode` applies only when the file is created: an older file keeps whatever it had.
+  try { fs.chmodSync(f, 0o600); } catch { /* not ours to change (a shared mount); the key is still written */ }
   return f;
 }
 
+/** The saved teams as a list, the current one marked. */
+function teams(cfg = read()) {
+  return Object.entries(cfg.teams || {}).map(([id, t]) => ({ id, name: t.name || id, api_url: t.api_url || cfg.api_url || DEFAULT_URL, current: String(cfg.current_team) === id, api_key: t.api_key }));
+}
+
+/** A saved team by id or name (exact, then any case); null when none. */
+function findTeam(cfg, ref) {
+  const all = teams(cfg);
+  const r = String(ref);
+  return all.find((t) => t.id === r) || all.find((t) => t.name === r) || all.find((t) => t.name.toLowerCase() === r.toLowerCase()) || null;
+}
+
 function resolve(flags = {}) {
   const cfg = read();
-  const key = flags.key || process.env.TRODO_API_KEY || cfg.api_key || null;
-  const url = String(flags.url || process.env.TRODO_API_URL || cfg.api_url || DEFAULT_URL).replace(/\/+$/, '');
-  return { key, url };
+  const envUrl = flags.url || process.env.TRODO_API_URL;
+  const finish = (key, url) => ({ key, url: String(envUrl || url || cfg.api_url || DEFAULT_URL).replace(/\/+$/, '') });
+  if (flags.key && flags.key !== true) return finish(String(flags.key));
+  if (process.env.TRODO_API_KEY) return finish(process.env.TRODO_API_KEY);
+  if (flags.team && flags.team !== true) {
+    const t = findTeam(cfg, flags.team);
+    if (!t) {
+      const e = new Error(`Not signed in to a team called "${flags.team}". \`trodo teams\` lists yours; \`trodo login\` adds one.`);
+      e.exitCode = 2;
+      throw e;
+    }
+    return finish(t.api_key, t.api_url);
+  }
+  const cur = cfg.teams && cfg.current_team != null ? cfg.teams[String(cfg.current_team)] : null;
+  if (cur) return finish(cur.api_key, cur.api_url);
+  return finish(cfg.api_key || null);
+}
+
+/** Save a team's key and make it the current team. */
+function saveTeam({ id, name, key, url }) {
+  const cfg = read();
+  const t = { ...(cfg.teams || {}) };
+  t[String(id)] = { name, api_key: key, api_url: url };
+  const next = { api_url: url, current_team: String(id), teams: t };
+  return write(next);
 }
 
-module.exports = { read, write, resolve, file, DEFAULT_URL };
+module.exports = { read, write, resolve, file, teams, findTeam, saveTeam, DEFAULT_URL };

package/lib/http.js

@@ -18,16 +18,34 @@ function client({ url, key, fetchImpl = globalThis.fetch }) {
     throw e;
   }
   const base = `${url}/api/v1`;
-  const headers = { Authorization: `Bearer ${key}`, 'User-Agent': 'trodo-cli/0.2', Accept: 'application/json' };
+  const headers = { Authorization: `Bearer ${key}`, 'User-Agent': `trodo-cli/${require('../package.json').version}`, Accept: 'application/json' };
+
+  // Reads are retried on a dropped connection or a gateway hiccup (502/503/504):
+  // a script pulling thousands of rows should not die on one blip. A write is
+  // never retried, so it can never happen twice.
+  const READ_POSTS = /^\/traces\/(count|stats|export)$/;
+  const isRead = (method, p) => method === 'GET' || (method === 'POST' && READ_POSTS.test(p));
+  const RETRY_STATUS = new Set([502, 503, 504]);
+  const pause = (ms) => new Promise((r) => setTimeout(r, ms));
 
   async function request(method, p, { query, body } = {}) {
     const qs = query ? `?${new URLSearchParams(Object.entries(query).filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k, v]) => [k, String(v)]))}` : '';
-    const res = await fetchImpl(`${base}${p}${qs}`, {
-      method,
-      headers: body !== undefined ? { ...headers, 'Content-Type': 'application/json' } : headers,
-      body: body !== undefined ? JSON.stringify(body) : undefined,
-    });
-    return res;
+    const attempts = isRead(method, p) ? 4 : 1;
+    for (let i = 1; ; i += 1) {
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        const res = await fetchImpl(`${base}${p}${qs}`, {
+          method,
+          headers: body !== undefined ? { ...headers, 'Content-Type': 'application/json' } : headers,
+          body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (i < attempts && RETRY_STATUS.has(res.status)) { await pause(500 * 2 ** (i - 1)); continue; } // eslint-disable-line no-await-in-loop
+        return res;
+      } catch (e) {
+        if (i >= attempts) throw Object.assign(new Error(`Could not reach ${url} (${e.cause && e.cause.code ? e.cause.code : e.message}).`), { exitCode: 1 });
+        await pause(500 * 2 ** (i - 1)); // eslint-disable-line no-await-in-loop
+      }
+    }
   }
 
   async function json(method, p, opts) {
@@ -65,6 +83,7 @@ function client({ url, key, fetchImpl = globalThis.fetch }) {
     get: (p, query) => json('GET', p, { query }),
     post: (p, body, query) => json('POST', p, { body, query }),
     patch: (p, body) => json('PATCH', p, { body }),
+    del: (p, query) => json('DELETE', p, { query }),
     lines,
     raw: request,
   };