trodo-cli 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# trodo-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Trodo from the terminal, a script, CI or a coding agent: read and measure your
+agents' traces, see which eval step failed, triage and close issues, pull and
+push prompts, build and label datasets, run agents, and export fine-tuning files.
+
+```bash
+npm i -g trodo-cli
+trodo login                        # opens the app to connect this terminal
+trodo setup claude                 # give Claude Code the Trodo skills
+
+trodo traces stats --since 7d --compare
+trodo runs list --since 24h --eval "any:failed" --table
+trodo runs tree RUN_ID
+trodo evals verdicts --run RUN_ID --table
+trodo conversations get CONVERSATION_ID --messages
+trodo issues list --status open,regression --table
+trodo prompts pull support-triage --label production -o prompt.json
+trodo prompts push support-triage -f prompt.json --message "why" --label staging
+
+trodo traces export --kind spans --since 30d --eval any:passed --format openai --target output -o sft.jsonl
+trodo datasets create "Good refunds" --kind runs --eval "Refund policy:passed" --include-trace
+trodo datasets export "Good refunds" --rows passed --format openai --target output -o train.jsonl
+```
+
+`trodo help` lists every command and filter. Output is JSON (`--table` for a
+table, `--csv` for CSV; lists take `--all`). Exit codes: 0 ok, 1 API error, 2 usage.
+`trodo api GET /path` reaches any route of the CLI's API.
+
+Auth: `trodo login` (browser), `trodo login --key trodo_mk_…`, or
+`TRODO_API_KEY` / `TRODO_API_URL`. Keys live in Settings → MCP; one acts as
+the person who made it, on its team, with its scopes.
+
+Docs: https://docs.trodo.ai/platform/cli

package/bin/trodo.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+'use strict';
+
+// `trodo … | head` closes the pipe early: that is done, not an error.
+process.stdout.on('error', (e) => { if (e && e.code === 'EPIPE') process.exit(0); throw e; });
+
+require('../lib/main').main(process.argv.slice(2)).then((code) => { process.exitCode = code; });

package/lib/args.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * Flags: `--name value`, `--name=value`, `--flag` (true), `-o file`, `-f file`.
+ * A flag given twice collects into an array (`--where a --where b`).
+ * `--` ends flags. Everything else is positional.
+ */
+const SHORT = { o: 'out', f: 'file', h: 'help', n: 'limit' };
+const BOOLEAN = new Set(['help', 'json', 'table', 'live', 'include-trace', 'wait', 'yes', 'no-trace', 'no-browser', 'any-span', 'tree', 'messages', 'failed', 'passed', 'right', 'wrong', 'remove', 'compare', 'all', 'csv', 'global']);
+
+function parse(argv) {
+  const flags = {};
+  const positional = [];
+  const put = (k, v) => {
+    if (flags[k] === undefined) flags[k] = v;
+    else flags[k] = [].concat(flags[k], v);
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--') { positional.push(...argv.slice(i + 1)); break; }
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      const key = eq > 0 ? a.slice(2, eq) : a.slice(2);
+      if (eq > 0) { put(key, a.slice(eq + 1)); continue; }
+      if (BOOLEAN.has(key)) { put(key, true); continue; }
+      const next = argv[i + 1];
+      if (next === undefined || (next.startsWith('--') && next.length > 2)) { put(key, true); continue; }
+      put(key, next); i += 1;
+      continue;
+    }
+    if (/^-[a-zA-Z]$/.test(a)) {
+      const key = SHORT[a[1]] || a[1];
+      if (BOOLEAN.has(key)) { put(key, true); continue; }
+      put(key, argv[i + 1]); i += 1;
+      continue;
+    }
+    positional.push(a);
+  }
+  return { flags, positional };
+}
+
+/** A flag as a list (absent → []). */
+const list = (v) => (v === undefined || v === true ? [] : [].concat(v)).map(String);
+
+module.exports = { parse, list };

package/lib/commands/agents.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const config = require('../config');
+const { client } = require('../http');
+const { print } = require('../output');
+
+const usage = (msg) => { const e = new Error(msg); e.exitCode = 2; return e; };
+const DONE = new Set(['succeeded', 'failed', 'cancelled', 'canceled', 'stopped']);
+
+async function resolveAgent(api, ref) {
+  if (!ref) throw usage('Name the agent (its name or id).');
+  const { workflows } = await api.get('/agents');
+  const all = workflows || [];
+  const hit = all.find((w) => w.id === ref) || all.find((w) => w.name === ref) || all.find((w) => w.name.toLowerCase() === String(ref).toLowerCase());
+  if (!hit) throw usage(`No agent "${ref}". \`trodo agents list\` shows them.`);
+  return hit;
+}
+
+/** trodo agents get AGENT: the agent with its steps, trigger and published version. */
+async function getAgent([ref], flags) {
+  const api = client(config.resolve(flags));
+  const a = await resolveAgent(api, ref);
+  print(await api.get(`/agents/${a.id}`), flags);
+}
+
+async function listAgents(_a, flags) {
+  const { workflows } = await client(config.resolve(flags)).get('/agents');
+  print(workflows || [], flags, [['name', 'Agent', 44], ['status', 'Status', 10], ['id', 'Id', 36], ['updated_at', 'Updated', 24]]);
+}
+
+/** trodo agents run AGENT [--input JSON] [--wait]: start its published version, as Run manually does. */
+async function run([ref], flags) {
+  const api = client(config.resolve(flags));
+  const a = await resolveAgent(api, ref);
+  let input = null;
+  if (flags.input) { try { input = JSON.parse(String(flags.input)); } catch (e) { throw usage(`--input is not JSON: ${e.message}`); } }
+  const { execution } = await api.post(`/agents/${a.id}/executions`, { input });
+  if (!flags.wait) return print({ agent: a.name, execution }, flags);
+  let exec = execution;
+  const deadline = Date.now() + (Number(flags.timeout) || 900) * 1000;
+  while (!DONE.has(String(exec.status)) && Date.now() < deadline) {
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((r) => setTimeout(r, 2000));
+    // eslint-disable-next-line no-await-in-loop
+    exec = (await api.get(`/agents/executions/${exec.id}`, { lite: 1 })).execution;
+  }
+  print({ agent: a.name, execution: exec }, flags);
+  if (exec.status === 'failed') process.exitCode = 1;
+}
+
+async function executions([ref], flags) {
+  const api = client(config.resolve(flags));
+  const a = await resolveAgent(api, ref);
+  const out = await api.get(`/agents/${a.id}/executions`, { limit: flags.limit || 20 });
+  print(out.executions || out, flags, [['id', 'Execution', 36], ['status', 'Status', 10], ['started_at', 'Started', 24], ['finished_at', 'Finished', 24]]);
+}
+
+async function execution([id], flags) {
+  if (!id) throw usage('Usage: trodo agents execution EXECUTION_ID');
+  print(await client(config.resolve(flags)).get(`/agents/executions/${encodeURIComponent(id)}`), flags);
+}
+
+module.exports = { get: getAgent, list: listAgents, run, executions, execution };

package/lib/commands/api.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const fs = require('fs');
+const config = require('../config');
+const { client } = require('../http');
+const { print } = require('../output');
+const { usage } = require('../common');
+const { list: flagList } = require('../args');
+
+/**
+ * trodo api METHOD PATH [--param k=v …] [--data JSON | -f body.json]
+ * Any /api/v1 route with the signed-in key, for what no command covers yet.
+ * Reads are open; the server refuses any write that deletes, archives or replaces:
+ *   trodo api GET /runs/conversations --param q=alice
+ *   trodo api POST /datasets --data '{"name":"Scratch"}'
+ */
+async function call([method, path], flags) {
+  const m = String(method || '').toUpperCase();
+  if (!['GET', 'POST', 'PATCH', 'PUT', 'DELETE'].includes(m) || !path) throw usage('Usage: trodo api GET|POST|PATCH|PUT|DELETE /path [--param k=v] [--data JSON | -f body.json]');
+  const query = {};
+  for (const kv of flagList(flags.param)) {
+    const i = kv.indexOf('=');
+    if (i < 1) throw usage(`--param takes k=v, got "${kv}".`);
+    query[kv.slice(0, i)] = kv.slice(i + 1);
+  }
+  let body;
+  const raw = flags.data !== undefined && flags.data !== true ? String(flags.data) : (flags.file && flags.file !== true ? fs.readFileSync(String(flags.file), 'utf8') : null);
+  if (raw != null) { try { body = JSON.parse(raw); } catch (e) { throw usage(`The body is not JSON: ${e.message}`); } }
+  const p = String(path).startsWith('/') ? String(path) : `/${path}`;
+  const res = await client(config.resolve(flags)).raw(m, p, { query, body });
+  const text = await res.text();
+  let data; try { data = text ? JSON.parse(text) : null; } catch { data = text; }
+  if (!res.ok) { process.exitCode = 1; process.stderr.write(`trodo: HTTP ${res.status}\n`); }
+  if (typeof data === 'string') process.stdout.write(`${data}\n`); else print(data, flags);
+}
+
+module.exports = { call };

package/lib/commands/auth.js

@@ -0,0 +1,165 @@
+'use strict';
+
+const config = require('../config');
+const { client } = require('../http');
+const { print } = require('../output');
+
+async function readHidden(prompt) {
+  if (!process.stdin.isTTY) {
+    const chunks = [];
+    for await (const c of process.stdin) chunks.push(c);
+    return Buffer.concat(chunks).toString('utf8').trim();
+  }
+  process.stdout.write(prompt);
+  return new Promise((resolve) => {
+    let v = '';
+    process.stdin.setRawMode(true); process.stdin.resume();
+    const onData = (b) => {
+      const s = b.toString('utf8');
+      if (s === '\r' || s === '\n' || s === '\u0004') { process.stdin.setRawMode(false); process.stdin.pause(); process.stdin.off('data', onData); process.stdout.write('\n'); resolve(v.trim()); }
+      else if (s === '\u0003') { process.stdout.write('\n'); process.exit(130); }
+      else if (s === '\u007f') v = v.slice(0, -1);
+      else v += s;
+    };
+    process.stdin.on('data', onData);
+  });
+}
+
+/** Open a URL in the default browser; false when there is none to open. */
+function openBrowser(url) {
+  // eslint-disable-next-line global-require
+  const { spawn } = require('child_process');
+  const cmd = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]];
+  try {
+    const p = spawn(cmd[0], cmd[1], { stdio: 'ignore', detached: true });
+    p.on('error', () => {});
+    p.unref();
+    return true;
+  } catch { return false; }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** The browser sign-in: a code here, Connect in the app, a key back. */
+async function browserLogin(url, flags) {
+  // eslint-disable-next-line global-require
+  const os = require('os');
+  // eslint-disable-next-line global-require
+  const pkg = require('../../package.json');
+  const fetchImpl = globalThis.fetch;
+  const post = async (p, body) => {
+    const res = await fetchImpl(`${url}/api/v1${p}`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'User-Agent': `trodo-cli/${pkg.version}` }, body: JSON.stringify(body) });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) { const e = new Error(data.message || data.error || `HTTP ${res.status} from ${url}`); e.status = res.status; throw e; }
+    return data;
+  };
+  const start = await post('/auth/device', { host: os.hostname().replace(/\.local$/, ''), client: `trodo-cli ${pkg.version}` });
+  process.stderr.write(`\nYour code: ${start.user_code}\n`);
+  const opened = !flags['no-browser'] && openBrowser(start.verification_url);
+  process.stderr.write(`${opened ? 'Opened' : 'Open'} ${start.verification_url}\n${opened ? 'Check the code there and press Connect.' : 'Sign in there, check the code and press Connect.'} Waiting…\n`);
+  const deadline = Date.now() + (start.expires_in || 600) * 1000;
+  while (Date.now() < deadline) {
+    // eslint-disable-next-line no-await-in-loop
+    await sleep((start.interval || 2) * 1000);
+    // eslint-disable-next-line no-await-in-loop
+    const out = await post('/auth/device/token', { device_code: start.device_code });
+    if (out.status === 'approved') return out.api_key;
+    if (out.status === 'denied') { const e = new Error('Sign-in was refused in the browser.'); e.exitCode = 1; throw e; }
+    if (out.status === 'expired') break;
+  }
+  const e = new Error('The sign-in code expired. Run `trodo login` again.');
+  e.exitCode = 1;
+  throw e;
+}
+
+/**
+ * trodo login [--url URL] [--no-browser]: sign in through the app (a code, Connect, done).
+ * trodo login --key trodo_mk_…: use a key you made in Settings → MCP (CI, no browser).
+ * Saved to ~/.trodo/config.json, mode 600.
+ */
+async function login(_args, flags) {
+  const url = config.resolve(flags).url;
+  let key;
+  // --key K uses that key; --key alone (or --key -) reads it from the terminal or stdin.
+  if (flags.key === true || flags.key === '-') key = await readHidden('API key (trodo_mk_…, Settings → MCP): ');
+  else if (flags.key) key = String(flags.key);
+  else key = await browserLogin(url, flags);
+  if (!key.startsWith('trodo_mk_')) { const e = new Error('That is not a Trodo API key (they start with trodo_mk_).'); e.exitCode = 2; throw e; }
+  const me = await client({ url, key }).get('/me');
+  await adoptOldKey();
+  const before = config.teams().filter((t) => String(t.id) !== String(me.team.id));
+  const file = config.saveTeam({ id: me.team.id, name: me.team.name || String(me.team.id), key, url });
+  process.stderr.write(`Signed in to ${me.team.name} as ${me.user.email}. Saved to ${file}.${before.length ? ` Also signed in to ${before.map((t) => t.name).join(', ')}: \`trodo switch\` moves between them.` : ''}\n`);
+  print({ team: me.team, scopes: me.key.scopes }, flags);
+}
+
+/**
+ * A 0.2 config held one key and no team: ask the server whose it is and put it
+ * in the list, so signing in to a second team keeps the first. Silent when the
+ * key no longer works (it is then simply dropped by the next login).
+ */
+async function adoptOldKey(keepCurrent = true) {
+  const cfg = config.read();
+  if (!cfg.api_key || (cfg.teams && Object.keys(cfg.teams).length)) return;
+  const url = String(cfg.api_url || config.DEFAULT_URL).replace(/\/+$/, '');
+  try {
+    const me = await client({ url, key: cfg.api_key }).get('/me');
+    const teams = { [String(me.team.id)]: { name: me.team.name || String(me.team.id), api_key: cfg.api_key, api_url: url } };
+    config.write({ api_url: url, current_team: keepCurrent ? String(me.team.id) : null, teams });
+  } catch { /* an old key that no longer works is not worth keeping */ }
+}
+
+/** trodo teams: the teams this terminal is signed in to; the current one is marked. */
+async function teams(_args, flags) {
+  await adoptOldKey();
+  const rows = config.teams().map(({ api_key: k, ...t }) => ({ ...t, current: t.current ? '*' : '' }));
+  if (!rows.length) {
+    const legacy = config.read().api_key;
+    process.stderr.write(legacy ? 'Signed in with one key from an older trodo; `trodo login` adds teams by name.\n' : 'Not signed in. `trodo login` adds a team.\n');
+  }
+  print(flags.table ? rows : rows.map((r) => ({ ...r, current: r.current === '*' })), flags, [['current', '', 1], ['name', 'Team', 40], ['id', 'Id', 8], ['api_url', 'Server', 30]]);
+}
+
+/** trodo switch TEAM: the team every command uses from now on (`--team` picks one for a single command). */
+async function switchTeam([ref], flags) {
+  if (!ref) { const e = new Error('Usage: trodo switch TEAM   (`trodo teams` lists them)'); e.exitCode = 2; throw e; }
+  await adoptOldKey();
+  const cfg = config.read();
+  const t = config.findTeam(cfg, ref);
+  if (!t) { const e = new Error(`Not signed in to a team called "${ref}". \`trodo teams\` lists yours; \`trodo login\` adds one.`); e.exitCode = 2; throw e; }
+  config.write({ ...cfg, current_team: t.id });
+  process.stderr.write(`Now on ${t.name}.\n`);
+  print({ team: { id: t.id, name: t.name } }, flags);
+}
+
+async function whoami(_args, flags) {
+  print(await client(config.resolve(flags)).get('/me'), flags);
+}
+
+/**
+ * trodo logout [TEAM] [--all]: forget the current team's key (or TEAM's, or
+ * every one). The key itself stays valid until revoked in Settings → MCP.
+ */
+async function logout([ref], flags) {
+  const cfg = config.read();
+  const all = config.teams(cfg);
+  let removed = [];
+  if (flags.all || !all.length) {
+    removed = all.map((t) => t.name);
+    config.write({ api_url: cfg.api_url });
+  } else {
+    const t = ref ? config.findTeam(cfg, ref) : all.find((x) => x.current) || all[0];
+    if (!t) { const e = new Error(`Not signed in to a team called "${ref}".`); e.exitCode = 2; throw e; }
+    const rest = { ...cfg.teams };
+    delete rest[t.id];
+    const left = Object.keys(rest);
+    const current = String(cfg.current_team) === t.id ? (left[0] || null) : cfg.current_team;
+    config.write({ api_url: cfg.api_url, current_team: current, teams: rest });
+    removed = [t.name];
+    if (current && current !== cfg.current_team) process.stderr.write(`Now on ${rest[current].name || current}.\n`);
+  }
+  process.stderr.write(removed.length ? `Forgot the key for ${removed.join(', ')}.\n` : 'Removed the saved key.\n');
+  print({ ok: true, removed }, flags);
+}
+
+module.exports = { login, whoami, logout, teams, switch: switchTeam };

package/lib/commands/conversations.js

@@ -0,0 +1,49 @@
+'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 } = require('../common');
+
+/**
+ * trodo conversations list [filter flags] [--search TEXT] [--limit 50] [--offset N]
+ * A conversation (a thread) matches when any of its runs does; eval conditions
+ * are decided for the whole conversation. --search matches the id or the user.
+ */
+async function list(_args, flags) {
+  const api = client(config.resolve(flags));
+  const spec = await buildSpec(api, flags, 'runs');
+  const q = listQuery(spec, windowOf);
+  if (flags.search && flags.search !== true) q.q = String(flags.search);
+  const rows = await pages(flags, async (limit, offset) => { const out = await api.get('/runs/conversations', { ...q, limit, offset }); return out.conversations || []; });
+  print(rows, flags, [['conversation_id', 'Conversation', 40], ['distinct_id', 'User', 26], ['run_count', 'Runs', 5], ['error_count', 'Errors', 6], ['last_run_at', 'Last run', 24]]);
+}
+
+/**
+ * trodo conversations get ID [--messages]: the thread, every run in it in order,
+ * and its evaluations. --messages prints the thread as user / assistant turns.
+ */
+async function get([id], flags) {
+  if (!id) throw usage('Usage: trodo conversations get CONVERSATION_ID [--messages]');
+  const api = client(config.resolve(flags));
+  const [detail, verdicts] = await Promise.all([
+    api.get(`/runs/conversations/${encodeURIComponent(id)}`),
+    api.get(`/eval3/units/conversation/${encodeURIComponent(id)}/verdicts`).catch(() => null),
+  ]);
+  if (flags.messages) {
+    const turns = [];
+    for (const r of detail.runs || []) {
+      const input = r.input ?? r.input_preview ?? null;
+      const output = r.output ?? r.output_preview ?? null;
+      if (input != null) turns.push({ role: 'user', content: input, run_id: r.run_id, at: r.started_at });
+      if (output != null) turns.push({ role: 'assistant', content: output, run_id: r.run_id, at: r.ended_at || r.started_at });
+    }
+    print({ conversation_id: id, messages: turns }, flags);
+    return;
+  }
+  print({ ...detail, evaluations: unitVerdicts(verdicts) }, flags);
+}
+
+module.exports = { list, get };

package/lib/commands/datasets.js

@@ -0,0 +1,182 @@
+'use strict';
+
+const config = require('../config');
+const { client } = require('../http');
+const { print, sink, readRows } = require('../output');
+const { buildSpec } = require('./traces');
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const usage = (msg) => { const e = new Error(msg); e.exitCode = 2; return e; };
+
+async function resolveDataset(api, ref) {
+  if (!ref) throw usage('Name the dataset (its name or id).');
+  const { datasets } = await api.get('/datasets');
+  const all = datasets || [];
+  const hit = all.find((d) => d.id === ref) || all.find((d) => d.name === ref) || all.find((d) => d.name.toLowerCase() === String(ref).toLowerCase());
+  if (!hit) throw usage(`No dataset "${ref}". \`trodo datasets list\` shows them.`);
+  return hit;
+}
+
+async function listDatasets(_a, flags) {
+  const { datasets } = await client(config.resolve(flags)).get('/datasets');
+  print(datasets || [], flags, [['name', 'Dataset', 40], ['item_count', 'Rows', 8], ['expected_count', 'With Expected', 14], ['id', 'Id', 36], ['updated_at', 'Updated', 24]]);
+}
+
+async function getDataset([ref], flags) {
+  const api = client(config.resolve(flags));
+  const d = await resolveDataset(api, ref);
+  const [sources, versions] = await Promise.all([
+    api.get(`/datasets/${d.id}/sources`).catch(() => ({ sources: [] })),
+    api.get(`/datasets/${d.id}/versions`).catch(() => ({ versions: [] })),
+  ]);
+  print({ ...d, sources: sources.sources || sources, versions: (versions.versions || versions || []).slice(0, 20) }, flags);
+}
+
+/**
+ * trodo datasets create NAME [--description D] [-f rows.jsonl]
+ *   [--kind spans|runs|conversations|verdicts <filter flags> [--live] [--include-trace]]
+ * With --kind, the dataset starts with a source: what the filter matches is copied now
+ * (and, with --live, every 15 minutes after).
+ */
+async function create([name], flags) {
+  if (!name) throw usage('Usage: trodo datasets create NAME [--kind runs --eval "Grounded:passed" --include-trace]');
+  const api = client(config.resolve(flags));
+  // The filter is checked before anything is made: a typo never leaves an empty dataset behind.
+  const spec = flags.kind ? await buildSpec(api, flags, String(flags.kind)) : null;
+  // So is the file: read and parsed before the dataset exists.
+  const rows = flags.file && flags.file !== true ? await readRows(String(flags.file)) : null;
+  const { dataset } = await api.post('/datasets', { name, ...(flags.description ? { description: String(flags.description) } : {}) });
+  let source = null;
+  if (spec) source = await api.post(`/datasets/${dataset.id}/sources`, { ...spec, live: Boolean(flags.live) });
+  const added = rows && rows.length ? await appendRows(api, dataset, rows, flags) : null;
+  print({ dataset: { id: dataset.id, name: dataset.name }, ...(source ? { source: source.source, run: source.feed } : {}), ...(added ? { rows: added } : {}) }, flags);
+}
+
+/** trodo datasets add DATASET --kind KIND <filter flags> [--live] [--include-trace]: another source. */
+async function addSource([ref], flags) {
+  const api = client(config.resolve(flags));
+  const d = await resolveDataset(api, ref);
+  const spec = await buildSpec(api, flags, String(flags.kind || 'runs'));
+  const out = await api.post(`/datasets/${d.id}/sources`, { ...spec, live: Boolean(flags.live) });
+  print({ dataset: d.name, source: out.source, run: out.feed }, flags);
+}
+
+/**
+ * trodo datasets append DATASET [-f rows.jsonl | stdin] [--include-trace]
+ * A line is a plain row { input | messages, output?, expected?, metadata? } or a
+ * reference to traffic ({ run_id } / { span_id } / { conversation_id } / { eval_run_id }),
+ * which the server fills with Input, Output and the evaluations. Rows already held are skipped.
+ */
+async function append([ref], flags) {
+  const api = client(config.resolve(flags));
+  const d = await resolveDataset(api, ref);
+  const rows = await readRows(flags.file);
+  print({ dataset: d.name, ...(await appendRows(api, d, rows, flags)) }, flags);
+}
+
+/** Rows (plain or references to traffic) into dataset `d`; returns { written, skipped }. */
+async function appendRows(api, d, rows, flags) {
+  const REF = new Set(['run_id', 'span_id', 'conversation_id', 'eval_run_id']);
+  const refs = { run_ids: [], span_ids: [], conversation_ids: [], eval_run_ids: [] };
+  const plain = [];
+  for (const r of rows) {
+    const keys = r && typeof r === 'object' ? Object.keys(r) : [];
+    if (keys.length && keys.every((k) => REF.has(k))) {
+      if (r.eval_run_id) refs.eval_run_ids.push(String(r.eval_run_id));
+      else if (r.span_id) refs.span_ids.push(String(r.span_id));
+      else if (r.run_id) refs.run_ids.push(String(r.run_id));
+      else refs.conversation_ids.push(String(r.conversation_id));
+    } else if (r && typeof r === 'object') {
+      const { expected, ...rest } = r;
+      plain.push(expected !== undefined && rest.expected_output === undefined ? { ...rest, expected_output: expected } : rest);
+    }
+  }
+  let written = 0; let skipped = 0;
+  const chunk = (arr, n) => Array.from({ length: Math.ceil(arr.length / n) }, (_, i) => arr.slice(i * n, i * n + n));
+  for (const [key, ids] of Object.entries(refs)) {
+    for (const part of chunk(ids, 200)) {
+      // eslint-disable-next-line no-await-in-loop
+      const out = await api.post(`/datasets/${d.id}/items`, { [key]: part, ...(flags['include-trace'] ? { include_trace: true } : {}) });
+      written += Number(out.written ?? out.added ?? 0); skipped += Number(out.skipped ?? 0);
+    }
+  }
+  for (const part of chunk(plain, 500)) {
+    // eslint-disable-next-line no-await-in-loop
+    const out = await api.post(`/datasets/${d.id}/items`, { items: part });
+    written += Number(out.written ?? out.added ?? (Array.isArray(out.items) ? out.items.length : part.length)); skipped += Number(out.skipped ?? 0);
+  }
+  return { written, skipped };
+}
+
+/**
+ * trodo datasets update DATASET [-f updates.jsonl | stdin] [--label person|derived] [--name "version name"]
+ * Lines: { id, expected?, output?, metadata? } — the row ids an export or `rows` gave you.
+ * One version for the whole call. Expected counts as a person's unless --label derived.
+ */
+async function update([ref], flags) {
+  const api = client(config.resolve(flags));
+  const d = await resolveDataset(api, ref);
+  const rows = (await readRows(flags.file)).filter((r) => r && r.id);
+  if (!rows.length) throw usage('No updates: give lines like {"id": "…", "expected": "…"}.');
+  let updated = 0; let unchanged = 0; const missing = []; let version = null;
+  for (let i = 0; i < rows.length; i += 5000) {
+    // eslint-disable-next-line no-await-in-loop
+    const out = await api.post(`/datasets/${d.id}/items/update`, {
+      updates: rows.slice(i, i + 5000),
+      label: flags.label === 'derived' ? 'derived' : 'person',
+      ...(flags.name ? { version_name: String(flags.name) } : {}),
+    });
+    updated += out.updated; unchanged += out.unchanged; missing.push(...(out.missing || [])); version = out.version || version;
+  }
+  print({ dataset: d.name, updated, unchanged, missing: missing.slice(0, 50), version }, flags);
+}
+
+/**
+ * trodo datasets export DATASET [--rows all|expected|no-expected|passed|failed|marked-wrong]
+ *   [--eval NAME] [--min-score N] [--format trodo|openai|dpo] [--target expected|output|expected-else-output]
+ *   [--version N] [-o file]
+ * `--rows passed --format openai --target output` is a supervised fine-tuning file
+ * made of what went well, no labeling needed.
+ */
+async function exportDataset([ref], flags) {
+  const api = client(config.resolve(flags));
+  const d = await resolveDataset(api, ref);
+  const query = {
+    rows: flags.rows ? String(flags.rows).replace(/-/g, '_') : undefined,
+    eval: flags.eval ? String(flags.eval) : undefined,
+    min_score: flags['min-score'],
+    format: flags.format ? String(flags.format) : undefined,
+    target: flags.target ? String(flags.target).replace(/-/g, '_') : undefined,
+    version: flags.version === true ? undefined : flags.version,
+  };
+  const res = await api.raw('GET', `/datasets/${d.id}/export`, { query });
+  if (!res.ok) {
+    const t = await res.text(); let body; try { body = JSON.parse(t); } catch { body = { message: t }; }
+    const e = new Error(body.message || body.error || `HTTP ${res.status}`); e.exitCode = 1; throw e;
+  }
+  const out = sink(flags.out && flags.out !== true ? String(flags.out) : null);
+  const decoder = new TextDecoder();
+  let buf = '';
+  for await (const c of res.body) {
+    buf += decoder.decode(c, { stream: true });
+    let i;
+    while ((i = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, i).trim(); buf = buf.slice(i + 1);
+      // eslint-disable-next-line no-await-in-loop
+      if (line) await out.write(JSON.parse(line));
+    }
+  }
+  if (buf.trim()) await out.write(JSON.parse(buf.trim()));
+  await out.close();
+  const n = res.headers.get('x-trodo-export-rows'); const skipped = res.headers.get('x-trodo-export-skipped');
+  process.stderr.write(`${n} rows from ${d.name}${skipped ? `, ${skipped} skipped (no input or no target)` : ''}${flags.out ? ` → ${flags.out}` : ''}\n`);
+}
+
+async function versions([ref], flags) {
+  const api = client(config.resolve(flags));
+  const d = await resolveDataset(api, ref);
+  const out = await api.get(`/datasets/${d.id}/versions`);
+  print(out.versions || out, flags, [['version_no', 'v', 4], ['name', 'Name', 40], ['item_count', 'Rows', 8], ['created_at', 'At', 24]]);
+}
+
+module.exports = { list: listDatasets, get: getDataset, create, add: addSource, append, update, export: exportDataset, rows: exportDataset, download: exportDataset, versions, resolveDataset, UUID };