trodo-cli 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,78 @@
+'use strict';
+
+/**
+ * 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.
+ *
+ * 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');
+const path = require('path');
+
+const DEFAULT_URL = 'https://api.trodo.ai';
+
+function file() {
+  return process.env.TRODO_CONFIG || path.join(os.homedir(), '.trodo', 'config.json');
+}
+
+function read() {
+  try { return JSON.parse(fs.readFileSync(file(), 'utf8')); } catch { return {}; }
+}
+
+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 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, teams, findTeam, saveTeam, DEFAULT_URL };

package/lib/filters.js

@@ -0,0 +1,157 @@
+'use strict';
+
+/**
+ * Filter flags → the filter the Traces page and dataset sources use
+ * ({ modularFilters, time, eval_conditions }), so `trodo traces export`, a
+ * dataset source and the Traces page all mean the same thing.
+ *
+ *   --since 7d | 24h | 30d | 3m | today | 90d     (default 7d)
+ *   --from ISO --to ISO
+ *   --agent NAME                                  (repeatable)
+ *   --where "status=error"   = != ~ (contains) > >= < <=   e.g. total_cost>0.05,
+ *            span.model~gpt-4o, metadata.tier=pro, attributes.region!=eu
+ *   --eval "NAME:COND"       COND: failed | passed | not-failed | marked-wrong |
+ *            not-marked-wrong | marked-right | score<0.5 | reason=A,B |
+ *            "STEP.FIELD=value" | "STEP.FIELD<3"     NAME may be "any"
+ *   --sample PCT, --limit N
+ */
+
+const { list } = require('./args');
+
+const OPS = [
+  ['>=', 'greater_than_equal'], ['<=', 'less_than_equal'], ['!=', 'is_not'],
+  ['>', 'greater_than'], ['<', 'less_than'], ['~', 'contains'], ['=', 'is'],
+];
+const NUM = { '<': 'lt', '<=': 'lte', '>': 'gt', '>=': 'gte', '=': 'eq' };
+
+function fail(msg) { const e = new Error(msg); e.exitCode = 2; throw e; }
+
+function timeOf(flags) {
+  if (flags.from || flags.to) {
+    const from = flags.from ? new Date(flags.from) : null;
+    const to = flags.to ? new Date(flags.to) : null;
+    if ((from && Number.isNaN(from.getTime())) || (to && Number.isNaN(to.getTime()))) fail('--from / --to must be dates (2026-10-01 or ISO)');
+    return { preset: 'custom', ...(from ? { from: from.toISOString() } : {}), ...(to ? { to: to.toISOString() } : {}) };
+  }
+  const since = String(flags.since || '7d');
+  if (!/^(\d+[mhd]|today|yesterday|\d+m)$/.test(since)) fail('--since takes 24h, 7d, 30d, 3m, 6m, 12m, today or yesterday');
+  return { preset: since };
+}
+
+/** "status=error" → a Traces filter chip. */
+function whereChip(expr) {
+  const s = String(expr);
+  for (const [sym, operator] of OPS) {
+    const i = s.indexOf(sym);
+    if (i > 0) {
+      const field = s.slice(0, i).trim();
+      const raw = s.slice(i + sym.length).trim();
+      if (!field || raw === '') fail(`--where "${s}": write it as field${sym}value`);
+      const isNum = /^-?\d+(\.\d+)?$/.test(raw);
+      let value = raw;
+      if (operator === 'is' || operator === 'is_not') value = raw.split(',').map((x) => x.trim()).filter(Boolean);
+      else if (operator.startsWith('greater') || operator.startsWith('less')) {
+        if (!isNum) fail(`--where "${s}": ${sym} needs a number`);
+        value = Number(raw);
+      }
+      return { field, operator, value, category: 'global' };
+    }
+  }
+  return fail(`--where "${s}": use =, !=, ~ (contains), >, >=, < or <=`);
+}
+
+function findEval(evals, name) {
+  if (/^any$/i.test(name)) return null;
+  const n = name.toLowerCase();
+  const exact = evals.filter((e) => e.id === name || e.name.toLowerCase() === n);
+  if (exact.length === 1) return exact[0];
+  const part = evals.filter((e) => e.name.toLowerCase().includes(n));
+  if (part.length === 1) return part[0];
+  if (!part.length) fail(`No eval called "${name}". \`trodo evals list\` shows them.`);
+  return fail(`"${name}" matches ${part.length} evals: ${part.map((e) => e.name).join(', ')}. Use more of the name.`);
+}
+
+/** "Grounded:failed", "any:score<0.4", "Router:route.choice=billing" → an eval condition. */
+function evalCondition(expr, evals) {
+  const s = String(expr);
+  const colon = s.indexOf(':');
+  if (colon <= 0) fail(`--eval "${s}": write it as NAME:CONDITION (e.g. "Grounded:failed")`);
+  const ev = findEval(evals, s.slice(0, colon).trim());
+  const base = ev ? { lineage_id: ev.id } : {};
+  const cond = s.slice(colon + 1).trim();
+  const words = {
+    failed: { verdict: 'fail' }, passed: { verdict: 'pass' }, 'not-failed': { verdict: 'fail', negate: true },
+    'marked-wrong': { marked: 'wrong' }, 'not-marked-wrong': { marked: 'wrong', negate: true }, 'marked-right': { marked: 'right' },
+  };
+  if (words[cond]) return { ...base, ...words[cond] };
+  let m = /^score\s*(<=|>=|<|>|=)\s*(-?\d+(\.\d+)?)$/.exec(cond);
+  if (m) return { ...base, score: { op: NUM[m[1]], value: Number(m[2]) } };
+  m = /^reason\s*=\s*(.+)$/.exec(cond);
+  if (m) return { ...base, reason_codes: m[1].split(',').map((x) => x.trim()).filter(Boolean) };
+  m = /^(.+?)\.([A-Za-z_][\w]*)\s*(<=|>=|<|>|!=|=)\s*(.+)$/.exec(cond);
+  if (m) {
+    if (!ev) fail(`--eval "${s}": a step needs a named eval, not "any"`);
+    const [, stepRef, field, op, rawVal] = m;
+    const steps = ev.steps || [];
+    const ref = stepRef.trim().toLowerCase();
+    const byStart = steps.filter((st) => st.name.toLowerCase().startsWith(ref));
+    const step = steps.find((st) => st.id === stepRef || st.name.toLowerCase() === ref) || (byStart.length === 1 ? byStart[0] : null);
+    if (!step) fail(`--eval "${s}": "${ev.name}" has no step "${stepRef}". Its steps: ${(ev.steps || []).map((st) => st.name).join(', ') || 'none that answer'}`);
+    const f = (step.fields || []).find((x) => x.name === field);
+    if (!f) fail(`--eval "${s}": step "${step.name}" answers ${(step.fields || []).map((x) => x.name).join(', ')}, not ${field}`);
+    const val = rawVal.trim();
+    if (f.type === 'boolean') {
+      const yes = /^(true|yes|1)$/i.test(val); const no = /^(false|no|0)$/i.test(val);
+      if (!yes && !no) fail(`--eval "${s}": ${field} is yes/no`);
+      return { ...base, step: { node_id: step.id, field, op: op === '!=' ? 'neq' : 'eq', value: yes } };
+    }
+    if (f.type === 'number') {
+      if (!/^-?\d+(\.\d+)?$/.test(val)) fail(`--eval "${s}": ${field} is a number`);
+      return { ...base, step: { node_id: step.id, field, op: op === '!=' ? 'neq' : NUM[op], value: Number(val) } };
+    }
+    if (f.type === 'enum') {
+      return { ...base, step: { node_id: step.id, field, op: op === '!=' ? 'not_in' : 'in', value: val.split(',').map((x) => x.trim()) } };
+    }
+    return { ...base, step: { node_id: step.id, field, op: op === '!=' ? 'neq' : 'eq', value: val } };
+  }
+  return fail(`--eval "${s}": unknown condition "${cond}". Use failed, passed, not-failed, marked-wrong, not-marked-wrong, marked-right, score<0.5, reason=CODE or STEP.FIELD=value`);
+}
+
+/**
+ * The flags → { kind, filter, options }. `evals` is GET /evals's list,
+ * needed only when --eval names one.
+ */
+function specFromFlags(flags, { kind = flags.kind || 'runs', evals = [] } = {}) {
+  if (!['spans', 'runs', 'conversations', 'verdicts'].includes(kind)) fail('--kind is spans, runs, conversations or verdicts');
+  const time = timeOf(flags);
+  const agents = list(flags.agent);
+  const where = list(flags.where).map(whereChip);
+  const conds = list(flags.eval).map((e) => evalCondition(e, evals));
+  const options = {};
+  if (flags.limit !== undefined) {
+    const n = parseInt(flags.limit, 10);
+    if (!(n > 0)) fail('--limit must be a positive number');
+    options.limit = n;
+  }
+  if (flags.sample !== undefined) options.sample_pct = Number(flags.sample);
+  if (flags['include-trace']) options.include_trace = true;
+
+  if (kind === 'verdicts') {
+    const outcomes = list(flags.outcome).flatMap((o) => o.split(',')).map((o) => o.trim().replace(/-/g, '_')).filter(Boolean);
+    const ids = conds.map((c) => c.lineage_id).filter(Boolean);
+    const filter = { lineage_ids: ids, outcomes: outcomes.length ? outcomes : ['failed'], time };
+    if (flags.step) options.node_id = String(flags.step);
+    return { kind, filter, options };
+  }
+  const modularFilters = [];
+  if (agents.length) modularFilters.push({ field: 'agent_name', operator: 'is', value: agents, category: kind === 'spans' ? 'global' : 'agents' });
+  modularFilters.push(...where);
+  const filter = { modularFilters, time };
+  if (conds.length) filter.eval_conditions = conds;
+  if (kind === 'spans' && flags['any-span']) filter.span_kind = 'any';
+  return { kind, filter, options };
+}
+
+const needsEvals = (flags) => list(flags.eval).some((e) => !/^any:/i.test(e));
+
+module.exports = { specFromFlags, whereChip, evalCondition, timeOf, needsEvals };

package/lib/http.js

@@ -0,0 +1,74 @@
+'use strict';
+
+/** The API, over fetch (Node 18+). Every call goes to {url}/api/v1. */
+
+class ApiError extends Error {
+  constructor(status, body) {
+    const msg = (body && (body.message || body.error)) || `HTTP ${status}`;
+    super(typeof msg === 'string' ? msg : JSON.stringify(msg));
+    this.status = status;
+    this.body = body;
+  }
+}
+
+function client({ url, key, fetchImpl = globalThis.fetch }) {
+  if (!key) {
+    const e = new Error('No API key. Run `trodo login`, or set TRODO_API_KEY (a trodo_mk_ key from Settings → MCP).');
+    e.exitCode = 2;
+    throw e;
+  }
+  const base = `${url}/api/v1`;
+  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)]))}` : '';
+    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;
+  }
+
+  async function json(method, p, opts) {
+    const res = await request(method, p, opts);
+    const text = await res.text();
+    let data = null;
+    try { data = text ? JSON.parse(text) : null; } catch { data = { message: text.slice(0, 300) }; }
+    if (!res.ok) throw new ApiError(res.status, data);
+    return data;
+  }
+
+  /** NDJSON lines from a response, one parsed object at a time. */
+  async function* lines(method, p, opts) {
+    const res = await request(method, p, opts);
+    if (!res.ok) {
+      const text = await res.text();
+      let data; try { data = JSON.parse(text); } catch { data = { message: text.slice(0, 300) }; }
+      throw new ApiError(res.status, data);
+    }
+    const decoder = new TextDecoder();
+    let buf = '';
+    for await (const chunk of res.body) {
+      buf += decoder.decode(chunk, { stream: true });
+      let i;
+      while ((i = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, i).trim();
+        buf = buf.slice(i + 1);
+        if (line) yield JSON.parse(line);
+      }
+    }
+    if (buf.trim()) yield JSON.parse(buf.trim());
+  }
+
+  return {
+    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,
+  };
+}
+
+module.exports = { client, ApiError };

package/lib/main.js

@@ -0,0 +1,137 @@
+'use strict';
+
+/**
+ * trodo — Trodo from a terminal, a script, CI or a coding agent.
+ * Every command prints JSON (pretty on a terminal) unless --table is given.
+ */
+const { parse } = require('./args');
+const { ApiError } = require('./http');
+
+const pkg = require('../package.json');
+
+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
+  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]
+
+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 [-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]     {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]
+
+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]
+
+  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:
+                                             total_cost>0.05  span.model~gpt-4o  metadata.tier=pro
+  --eval "NAME:COND"                         failed | passed | not-failed | marked-wrong | not-marked-wrong |
+                                             marked-right | score<0.5 | reason=CODE | STEP.FIELD=value | STEP.FIELD<3
+                                             NAME may be "any". Conditions AND together.
+  --outcome failed,passed,marked-wrong       (verdicts)   --step STEP_ID (verdicts, one step per row)
+  --limit N   --sample PCT
+
+Training data:
+  trodo traces export --kind spans --eval "any:passed" --eval "any:not-failed" --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
+  firectl dataset create good-refunds train.jsonl
+
+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.
+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'], 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', '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 [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; }
+  try {
+    if (COMMANDS[cmd]) {
+      const [mod, fn] = COMMANDS[cmd];
+      // eslint-disable-next-line global-require, import/no-dynamic-require
+      await require(`./commands/${mod}`)[fn]([sub, ...rest].filter(Boolean), flags);
+      return process.exitCode || 0;
+    }
+    if (!GROUPS[cmd]) throw Object.assign(new Error(`Unknown command "${cmd}". \`trodo help\` lists them.`), { exitCode: 2 });
+    const action = sub || 'list';
+    if (!GROUPS[cmd].includes(action)) throw Object.assign(new Error(`Unknown: trodo ${cmd} ${action}. Try: ${GROUPS[cmd].map((a) => `trodo ${cmd} ${a}`).join(', ')}`), { exitCode: 2 });
+    // eslint-disable-next-line global-require, import/no-dynamic-require
+    await require(`./commands/${cmd}`)[action](rest, flags);
+    return process.exitCode || 0;
+  } catch (e) {
+    const msg = e instanceof ApiError ? `${e.message}${e.status ? ` (HTTP ${e.status})` : ''}` : e.message;
+    process.stderr.write(`trodo: ${msg}\n`);
+    if (flags.json) process.stdout.write(`${JSON.stringify({ error: msg, status: e.status || null, detail: e.body || null })}\n`);
+    return e.exitCode || 1;
+  }
+}
+
+module.exports = { main, HELP };

package/lib/output.js

@@ -0,0 +1,61 @@
+'use strict';
+
+/**
+ * JSON by default (pretty on a terminal, one line when piped) so a coding
+ * agent can read every command; --table for a person.
+ */
+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`);
+}
+
+function table(rows, columns) {
+  const cell = (v) => (v == null ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v)).replace(/\s+/g, ' ');
+  const cut = (s, w) => (s.length > w ? `${s.slice(0, w - 1)}…` : s);
+  const widths = columns.map(([key, label, max = 40]) => Math.min(max, Math.max(label.length, ...rows.map((r) => cell(r[key]).length))));
+  const line = (vals) => vals.map((v, i) => cut(v, widths[i]).padEnd(widths[i])).join('  ').trimEnd();
+  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;
+  return {
+    write: (obj) => new Promise((resolve) => { if (stream.write(`${JSON.stringify(obj)}\n`)) resolve(); else stream.once('drain', resolve); }),
+    close: () => new Promise((resolve) => { if (out) stream.end(resolve); else resolve(); }),
+  };
+}
+
+/** Read JSON lines (or one JSON array) from a file or stdin. */
+async function readRows(file) {
+  let text;
+  if (file && file !== '-') text = fs.readFileSync(file, 'utf8');
+  else {
+    if (process.stdin.isTTY) { const e = new Error('Give rows with -f rows.jsonl, or pipe them in.'); e.exitCode = 2; throw e; }
+    const chunks = [];
+    for await (const c of process.stdin) chunks.push(c);
+    text = Buffer.concat(chunks).toString('utf8');
+  }
+  const t = text.trim();
+  if (!t) return [];
+  if (t.startsWith('[')) return JSON.parse(t);
+  return t.split('\n').map((l) => l.trim()).filter(Boolean).map((l, i) => {
+    try { return JSON.parse(l); } catch (e) { const err = new Error(`line ${i + 1} is not JSON: ${e.message}`); err.exitCode = 2; throw err; }
+  });
+}
+
+module.exports = { print, table, csv, sink, readRows };

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "trodo-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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"
+  },
+  "main": "./lib/main.js",
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "trodo",
+    "traces",
+    "datasets",
+    "fine-tuning",
+    "evals",
+    "cli",
+    "agents"
+  ],
+  "license": "ISC"
+}