trodo-cli 0.2.0 → 0.3.0

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,7 +18,7 @@ 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' };
 
   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)]))}` : '';
@@ -65,6 +65,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,
   };

package/lib/main.js

@@ -9,31 +9,64 @@ const { ApiError } = require('./http');
 
 const pkg = require('../package.json');
 
-const HELP = `trodo ${pkg.version} — traces, datasets and agents from the terminal
+const HELP = `trodo ${pkg.version} — traces, evals, datasets, prompts and agents from the terminal
 
   trodo login [--url https://api.trodo.ai] [--no-browser]   sign in through the app
   trodo login --key trodo_mk_…                             or with a key (CI)
-  trodo whoami | logout
+  trodo whoami
+  trodo teams                                              the teams this terminal is signed in to
+  trodo switch TEAM                                        use another one (login adds teams; --team T for one command)
+  trodo logout [TEAM] [--all]
 
-  trodo evals list                                  eval names and their steps, for --eval
-  trodo traces count  [filter]
-  trodo traces export [filter] [--include-trace] [--format trodo|openai|dpo] [--target output|expected] [-o file]
-  trodo runs list [filter] [--limit 50]
-  trodo runs get RUN_ID
+Traces
+  trodo traces count  [filter]                       how many runs / spans / conversations / verdicts match
+  trodo traces stats  [filter] [--compare]           errors, latency, tokens, cost, feedback, evals, by agent
+  trodo traces agents | fields | values FIELD        what --agent and --where can name
+  trodo traces export [filter] [--include-trace] [--format trodo|openai|dpo] [--target output|expected]
+                      [-o file | --dir DIR]          JSONL, or one JSON file per run / span / conversation
+  trodo runs list [filter] [--limit 50] [--offset N]
+  trodo runs search TEXT                             runs whose input, output or spans mention TEXT
+  trodo runs get RUN_ID [--tree]                     the run, spans, messages, feedback, evaluations
+  trodo runs tree RUN_ID                             the span tree
+  trodo runs feedback RUN_ID [--thumbs up|down] [--rating 1-5] [--comment TEXT]
+  trodo spans list [filter] | search TEXT | get SPAN_ID
+  trodo conversations list [filter] [--search TEXT] | get ID [--messages]      (alias: threads)
+  trodo users get DISTINCT_ID                        one user's runs, cost, evals and feedback
 
+Evals
+  trodo evals list | get EVAL                        names, steps (STEP.FIELD), 30-day stats
+  trodo evals steps EVAL [--since 30d] [--table]     the paths verdicts took through the steps, with outcomes
+  trodo evals verdicts EVAL [--failed|--passed] [--since 7d] [--version N]
+  trodo evals verdicts --run ID | --span ID | --conversation ID
+  trodo evals verdict VERDICT_ID                     every step and why
+  trodo evals mark VERDICT_ID --right | --wrong --should pass|fail --reason TEXT
+  trodo evals queue [--eval EVAL] | review ITEM_ID | grade ITEM_ID CHOICE         verdicts waiting on a person
+
+Datasets
   trodo datasets list | get DATASET | versions DATASET
-  trodo datasets create NAME [--kind runs|spans|conversations|verdicts [filter] [--live] [--include-trace]]
+  trodo datasets create NAME [-f rows.jsonl] [--kind runs|spans|conversations|verdicts [filter] [--live] [--include-trace]]
   trodo datasets add DATASET --kind KIND [filter] [--live] [--include-trace]
-  trodo datasets append DATASET [-f rows.jsonl]     rows, or {run_id}/{span_id}/{conversation_id} lines
+  trodo datasets append DATASET [-f rows.jsonl]     {input, output?, expected?} or {run_id}/{span_id}/{conversation_id} lines
   trodo datasets update DATASET [-f updates.jsonl]  {id, expected?, output?, metadata?} lines, one version
   trodo datasets export DATASET [--rows passed|failed|expected|no-expected|marked-wrong|all]
                         [--eval NAME] [--min-score N] [--format trodo|openai|dpo] [--target ...] [--version N] [-o file]
 
-  trodo agents list | executions AGENT | execution ID
+Prompts
+  trodo prompts list | get PROMPT [--version N | --label L] | versions PROMPT
+  trodo prompts pull PROMPT [--label production] [-o prompt.json]
+  trodo prompts push PROMPT -f prompt.json [--message "why"] [--label staging]
+  trodo prompts label PROMPT VERSION LABEL [--remove]
+
+Issues and agents
+  trodo issues list [--status open,regression] | get ID | failures ID | close ID | reopen ID
+  trodo agents list | get AGENT | executions AGENT | execution ID
   trodo agents run AGENT [--input JSON] [--wait]
 
-Filter (traces, runs, datasets create/add):
-  --kind spans|runs|conversations|verdicts   (default runs)
+  trodo api GET|POST|PATCH|DELETE /path [--param k=v] [--data JSON]           any /api/v1 route
+  trodo setup claude [--global]                      install the Trodo skills for Claude Code (or --dir DIR)
+
+Filter (traces, runs, spans, conversations, datasets create/add):
+  --kind spans|runs|conversations|verdicts   (traces and datasets; default runs)
   --since 24h|7d|30d|3m|today  or  --from DATE --to DATE      (default 7d)
   --agent NAME                               repeatable
   --where "status=error"                     = != ~ > >= < <= on any Traces property:
@@ -50,25 +83,33 @@ Training data:
   trodo datasets export "Good refunds" --rows passed --format openai --target output -o train.jsonl
   firectl dataset create good-refunds train.jsonl
 
-Auth: TRODO_API_KEY / TRODO_API_URL, or \`trodo login\` (~/.trodo/config.json).
+Auth: TRODO_API_KEY / TRODO_API_URL, or \`trodo login\` (~/.trodo/config.json, one key per team).
 A key is a Trodo API key (Settings → MCP); it acts as the person who made it, on its team, with its scopes.
-Output: JSON by default; --table for a table. Exit codes: 0 ok, 1 API error, 2 usage.
+The CLI reads everything and only adds: nothing it does deletes, archives or replaces data.
+Output: JSON by default; --table for a table, --csv for CSV; lists take --all [--max-items N]. Exit codes: 0 ok, 1 API error, 2 usage.
 `;
 
 const COMMANDS = {
-  login: ['auth', 'login'], whoami: ['auth', 'whoami'], logout: ['auth', 'logout'],
+  login: ['auth', 'login'], whoami: ['auth', 'whoami'], logout: ['auth', 'logout'], api: ['api', 'call'], setup: ['setup', 'setup'], teams: ['auth', 'teams'], switch: ['auth', 'switch'],
 };
+const ALIASES = { threads: 'conversations', thread: 'conversations', run: 'runs', span: 'spans', dataset: 'datasets', prompt: 'prompts', issue: 'issues', agent: 'agents', eval: 'evals', trace: 'traces' };
 const GROUPS = {
-  evals: ['list'],
-  traces: ['count', 'export'],
-  runs: ['list', 'get'],
-  datasets: ['list', 'get', 'create', 'add', 'append', 'update', 'export', 'rows', 'versions'],
-  agents: ['list', 'run', 'executions', 'execution'],
+  evals: ['list', 'get', 'steps', 'verdicts', 'verdict', 'mark', 'queue', 'review', 'grade'],
+  traces: ['count', 'stats', 'export', 'agents', 'fields', 'values'],
+  runs: ['list', 'search', 'get', 'tree', 'feedback'],
+  spans: ['list', 'search', 'get'],
+  conversations: ['list', 'get'],
+  datasets: ['list', 'get', 'create', 'add', 'append', 'update', 'export', 'rows', 'download', 'versions'],
+  prompts: ['list', 'get', 'versions', 'pull', 'push', 'label'],
+  issues: ['list', 'get', 'failures', 'close', 'reopen'],
+  agents: ['list', 'get', 'run', 'executions', 'execution'],
+  users: ['get'],
 };
 
 async function main(argv) {
   const { flags, positional } = parse(argv);
-  const [cmd, sub, ...rest] = positional;
+  const [cmd0, sub, ...rest] = positional;
+  const cmd = ALIASES[cmd0] || cmd0;
   // `trodo --version` alone is the CLI's version; `datasets export X --version 3` is a dataset's.
   if (flags.version === true && !cmd) { process.stdout.write(`${pkg.version}\n`); return 0; }
   if (!cmd || flags.help || cmd === 'help') { process.stdout.write(HELP); return 0; }

package/lib/output.js

@@ -7,6 +7,7 @@
 const fs = require('fs');
 
 function print(data, flags = {}, columns = null) {
+  if (flags.csv && Array.isArray(data)) return process.stdout.write(csv(data, columns));
   if (flags.table && columns && Array.isArray(data)) return process.stdout.write(table(data, columns));
   const pretty = process.stdout.isTTY && !flags.json;
   return process.stdout.write(`${JSON.stringify(data, null, pretty ? 2 : 0)}\n`);
@@ -20,6 +21,16 @@ function table(rows, columns) {
   return `${[line(columns.map(([, label]) => label)), ...rows.map((r) => line(columns.map(([key]) => cell(r[key]))))].join('\n')}\n`;
 }
 
+/** RFC 4180 CSV: the table's columns when the command has them, every key otherwise. */
+function csv(rows, columns) {
+  const keys = columns ? columns.map(([k]) => k) : [...new Set(rows.flatMap((r) => (r && typeof r === 'object' ? Object.keys(r) : [])))];
+  const cell = (v) => {
+    const s = v == null ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v);
+    return /[",\r\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+  };
+  return `${[keys.join(','), ...rows.map((r) => keys.map((k) => cell(r[k])).join(','))].join('\n')}\n`;
+}
+
 /** Write lines to --out or stdout; returns { write(obj), close() }. */
 function sink(out) {
   const stream = out ? fs.createWriteStream(out) : process.stdout;
@@ -47,4 +58,4 @@ async function readRows(file) {
   });
 }
 
-module.exports = { print, table, sink, readRows };
+module.exports = { print, table, csv, sink, readRows };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "trodo-cli",
-  "version": "0.2.0",
-  "description": "Trodo from the terminal: pull traces by their eval results, build datasets, run labeling agents, export fine-tuning data",
+  "version": "0.3.0",
+  "description": "Trodo from the terminal: traces, evals, datasets, prompts, issues and agents for people, scripts and coding agents",
   "bin": {
     "trodo": "bin/trodo.js"
   },
@@ -9,6 +9,7 @@
   "files": [
     "bin/",
     "lib/",
+    "skills/",
     "README.md"
   ],
   "scripts": {