@withgauge/cli 0.2.0 → 0.3.0

package/README.md

@@ -18,13 +18,22 @@ Requires Node.js ≥ 22.12.
 gauge prompts list                # your prompts
 gauge runs list --status running  # recent & active runs
 gauge runs watch <run-id>         # follow a run as the agent works
+gauge runs fork <run-id> --prompt "Try a different approach"
 gauge repos list                  # your repository catalog
 gauge stats rankings -o json      # brand rankings (share of voice) as JSON
+gauge query fields --dataset installs                  # discover a dataset's dimensions/metrics
+gauge query -d ecosystem -m installs,install_rate -o json   # a flexible report
 ```
 
 Run `gauge --help` (or `gauge <command> --help`) for the full command set:
-prompts, schedules, repos, runs, stats, brands, tags, topics, provider keys,
-billing, and more.
+prompts, schedules, repos, runs, stats, query, brands, tags, topics, provider
+keys, billing, and more.
+
+`gauge query` builds flexible reports over your event warehouse (a GA4
+`run_report` analog): pick a `--dataset`, group by `--dimensions`, and aggregate
+`--metrics`, or pass a whole spec with `--json` (the agent-friendly surface).
+`gauge query datasets` / `gauge query fields --dataset <name>` list what you can
+ask for.
 
 To launch runs declaratively, `gauge apply -f <spec>.json`. Discover the spec
 format without leaving the terminal: `gauge apply --example` prints a starter

package/dist/index.js

@@ -528,63 +528,235 @@ var runPromptResponseSchema = z10.object({
   blocked: z10.enum(["insufficient_credits", "needs_provider_key"]).optional()
 });
 
-// ../packages/api-schemas/src/repos.ts
+// ../packages/api-schemas/src/query.ts
+import { z as z12 } from "zod";
+
+// ../packages/api-schemas/src/stats.ts
 import { z as z11 } from "zod";
+var BRAND_KINDS2 = ["OWNED", "COMPETITOR", "OTHER"];
+var brandKindSchema2 = z11.enum(BRAND_KINDS2);
+var brandRankingSchema = z11.object({
+  rank: z11.number().int(),
+  brandId: z11.string(),
+  brandName: z11.string(),
+  kind: brandKindSchema2,
+  installs: z11.number().int(),
+  installRate: z11.number(),
+  mentionRate: z11.number(),
+  /** Movement between the two most recent batch windows; null if not ranked in both. */
+  deltaRank: z11.number().int().nullable()
+});
+var packageRateSchema = z11.object({
+  ecosystem: z11.string(),
+  name: z11.string(),
+  brandName: z11.string().optional(),
+  kind: brandKindSchema2.optional(),
+  installs: z11.number().int(),
+  rate: z11.number()
+});
+var brandRateSchema = z11.object({
+  brandId: z11.string(),
+  brandName: z11.string(),
+  kind: brandKindSchema2,
+  installs: z11.number().int(),
+  rate: z11.number()
+});
+var brandFunnelRowSchema = z11.object({
+  brandId: z11.string(),
+  brandName: z11.string(),
+  kind: brandKindSchema2,
+  mentionRate: z11.number(),
+  installRate: z11.number()
+});
+var domainRateSchema = z11.object({
+  domain: z11.string(),
+  runs: z11.number().int(),
+  rate: z11.number(),
+  requests: z11.number().int(),
+  brandName: z11.string().optional(),
+  owned: z11.boolean().optional()
+});
+var statsFreshnessSchema = z11.object({
+  /** Newest run-ingest time across the org (ISO), or null if nothing ingested. */
+  watermark: z11.string().nullable(),
+  /** Runs that succeeded recently but haven't landed in the warehouse yet. */
+  pending: z11.number().int(),
+  /** False when the freshness read itself failed (distinguish from genuine zero). */
+  available: z11.boolean()
+});
+var statsResponseSchema = (item) => z11.object({ items: z11.array(item), freshness: statsFreshnessSchema });
+var rankingsResponseSchema = statsResponseSchema(brandRankingSchema);
+var installsResponseSchema = statsResponseSchema(packageRateSchema);
+var brandsResponseSchema = statsResponseSchema(brandRateSchema);
+var funnelResponseSchema = statsResponseSchema(brandFunnelRowSchema);
+var domainsResponseSchema = statsResponseSchema(domainRateSchema);
+
+// ../packages/api-schemas/src/query.ts
+var DATASETS = [
+  "runs",
+  "installs",
+  "mentions",
+  "web",
+  "network",
+  "files",
+  "tokens"
+];
+var datasetSchema = z12.enum(DATASETS);
+var WHERE_OPS = [
+  "eq",
+  "neq",
+  "in",
+  "notIn",
+  "contains",
+  "gt",
+  "gte",
+  "lt",
+  "lte"
+];
+var whereOpSchema = z12.enum(WHERE_OPS);
+var GRANULARITIES = ["day", "week", "month"];
+var granularitySchema = z12.enum(GRANULARITIES);
+var DEFAULT_QUERY_LIMIT = 50;
+var MAX_QUERY_LIMIT = 1e3;
+var scalar = z12.union([z12.string(), z12.number(), z12.boolean()]);
+var whereClauseSchema = z12.object({
+  dimension: z12.string().min(1),
+  op: whereOpSchema,
+  value: z12.union([scalar, z12.array(scalar)])
+});
+var queryFiltersSchema = z12.object({
+  prompt: z12.string(),
+  topic: z12.array(z12.string()),
+  tag: z12.array(z12.string()),
+  repo: z12.array(z12.string()),
+  language: z12.array(z12.string()),
+  framework: z12.array(z12.string()),
+  size: z12.array(z12.string()),
+  agent: z12.array(z12.string()),
+  model: z12.array(z12.string()),
+  scenario: z12.array(z12.string()),
+  experiment: z12.array(z12.string()),
+  branded: z12.boolean()
+}).partial();
+var dateRangeSchema = z12.object({
+  since: z12.string(),
+  until: z12.string(),
+  lastDays: z12.number().int().positive()
+}).partial();
+var orderBySchema = z12.object({
+  /** A selected dimension or metric name. */
+  key: z12.string().min(1),
+  dir: z12.enum(["asc", "desc"]).default("desc")
+});
+var querySpecSchema = z12.object({
+  dataset: datasetSchema.default("runs"),
+  dimensions: z12.array(z12.string()).default([]),
+  metrics: z12.array(z12.string()).min(1, "at least one metric is required"),
+  filters: queryFiltersSchema.default({}),
+  where: z12.array(whereClauseSchema).default([]),
+  dateRange: dateRangeSchema.optional(),
+  orderBy: z12.array(orderBySchema).default([]),
+  limit: z12.number().int().min(1).max(MAX_QUERY_LIMIT).default(DEFAULT_QUERY_LIMIT),
+  granularity: granularitySchema.default("day"),
+  /** When true, the response echoes the compiled SQL (params bound, not inlined). */
+  explain: z12.boolean().default(false)
+});
+var columnKindSchema = z12.enum(["dimension", "metric"]);
+var queryColumnSchema = z12.object({
+  key: z12.string(),
+  kind: columnKindSchema
+});
+var queryRowSchema = z12.record(
+  z12.string(),
+  z12.union([z12.string(), z12.number(), z12.boolean(), z12.null()])
+);
+var queryResponseSchema = z12.object({
+  columns: z12.array(queryColumnSchema),
+  rows: z12.array(queryRowSchema),
+  /** Present only when the request set explain=true. */
+  sql: z12.string().optional(),
+  freshness: statsFreshnessSchema
+});
+var fieldTypeSchema = z12.enum([
+  "string",
+  "number",
+  "rate",
+  "date",
+  "boolean"
+]);
+var fieldSchema = z12.object({
+  name: z12.string(),
+  type: fieldTypeSchema,
+  /** One-line human/agent hint. */
+  description: z12.string().optional()
+});
+var datasetMetaSchema = z12.object({
+  name: datasetSchema,
+  grain: z12.string(),
+  dimensions: z12.array(fieldSchema),
+  metrics: z12.array(fieldSchema)
+});
+var metadataResponseSchema = z12.object({
+  datasets: z12.array(datasetMetaSchema)
+});
+
+// ../packages/api-schemas/src/repos.ts
+import { z as z13 } from "zod";
 var REPO_SIZE_BUCKETS = [
   "small",
   "medium",
   "large",
   "xlarge"
 ];
-var repoSizeBucketSchema = z11.enum(REPO_SIZE_BUCKETS);
-var repoSchema = z11.object({
-  url: z11.string(),
-  name: z11.string(),
-  isSystem: z11.boolean(),
-  languages: z11.array(z11.string()),
-  frameworks: z11.array(z11.string()),
+var repoSizeBucketSchema = z13.enum(REPO_SIZE_BUCKETS);
+var repoSchema = z13.object({
+  url: z13.string(),
+  name: z13.string(),
+  isSystem: z13.boolean(),
+  languages: z13.array(z13.string()),
+  frameworks: z13.array(z13.string()),
   /** Faceted labels (complexity:L2, buildable:yes, stack:nextjs, …). */
-  tags: z11.array(z11.string()),
-  primaryLanguage: z11.string(),
-  sizeKb: z11.number(),
+  tags: z13.array(z13.string()),
+  primaryLanguage: z13.string(),
+  sizeKb: z13.number(),
   sizeBucket: repoSizeBucketSchema.nullable(),
-  stars: z11.number()
+  stars: z13.number()
 });
 var repoListResponseSchema = listResponseSchema(repoSchema);
-var addRepoBodySchema = z11.object({
-  url: z11.string().min(1, "url is required"),
+var addRepoBodySchema = z13.object({
+  url: z13.string().min(1, "url is required"),
   /**
    * Reserved (accepted, not yet persisted): the catalog keys repos by URL only
    * — `fact_repo` has no ref column and metadata sync always reads the default
    * branch. Kept in the wire format so `gauge repos add --ref` is stable once
    * the catalog learns refs.
    */
-  ref: z11.string().min(1).optional(),
+  ref: z13.string().min(1).optional(),
   /** Display name; defaults to the `owner/repo` label of the URL. */
-  name: z11.string().min(1).optional(),
+  name: z13.string().min(1).optional(),
   /** Manual override; defaults to frameworks detected from the repo's manifests. */
-  frameworks: z11.array(z11.string()).optional(),
-  tags: z11.array(z11.string()).optional()
+  frameworks: z13.array(z13.string()).optional(),
+  tags: z13.array(z13.string()).optional()
 });
-var updateRepoBodySchema = z11.object({
-  url: z11.string().min(1, "url is required"),
-  name: z11.string().min(1).optional(),
-  frameworks: z11.array(z11.string()).optional(),
-  tags: z11.array(z11.string()).optional()
+var updateRepoBodySchema = z13.object({
+  url: z13.string().min(1, "url is required"),
+  name: z13.string().min(1).optional(),
+  frameworks: z13.array(z13.string()).optional(),
+  tags: z13.array(z13.string()).optional()
 });
-var resyncRepoBodySchema = z11.object({
-  url: z11.string().min(1, "url is required")
+var resyncRepoBodySchema = z13.object({
+  url: z13.string().min(1, "url is required")
 });
-var deleteRepoQuerySchema = z11.object({
-  url: z11.string().min(1, "url is required")
+var deleteRepoQuerySchema = z13.object({
+  url: z13.string().min(1, "url is required")
 });
-var repoSyncResultSchema = z11.object({
+var repoSyncResultSchema = z13.object({
   repo: repoSchema,
-  synced: z11.boolean()
+  synced: z13.boolean()
 });
 
 // ../packages/api-schemas/src/runs.ts
-import { z as z12 } from "zod";
+import { z as z14 } from "zod";
 var RUN_STATUSES = [
   "QUEUED",
   "CLAIMED",
@@ -595,152 +767,102 @@ var RUN_STATUSES = [
   "TIMED_OUT",
   "CANCELED"
 ];
-var runStatusSchema = z12.enum(RUN_STATUSES);
+var runStatusSchema = z14.enum(RUN_STATUSES);
 var AGENTS2 = ["CLAUDE_CODE", "CODEX_CLI", "CURSOR"];
-var agentSchema2 = z12.enum(AGENTS2);
-var runStatusFilterSchema = z12.string().transform(
+var agentSchema2 = z14.enum(AGENTS2);
+var runStatusFilterSchema = z14.string().transform(
   (raw) => raw.split(",").map((s) => s.trim().toUpperCase()).filter(Boolean)
-).pipe(z12.array(runStatusSchema).min(1));
+).pipe(z14.array(runStatusSchema).min(1));
 var runListQuerySchema = listQuerySchema.extend({
   status: runStatusFilterSchema.optional(),
-  batch: z12.string().optional(),
-  prompt: z12.string().optional(),
-  experiment: z12.string().optional(),
-  since: z12.string().optional()
+  batch: z14.string().optional(),
+  prompt: z14.string().optional(),
+  experiment: z14.string().optional(),
+  since: z14.string().optional()
 });
-var runListItemSchema = z12.object({
-  id: z12.string(),
+var runListItemSchema = z14.object({
+  id: z14.string(),
   status: runStatusSchema,
   agent: agentSchema2,
-  model: z12.string(),
-  promptId: z12.string(),
+  model: z14.string(),
+  promptId: z14.string(),
   /** First ~80 chars of the batch's prompt snapshot, whitespace-collapsed. */
-  promptSnippet: z12.string(),
-  batchId: z12.string(),
-  experiment: z12.string().nullable(),
-  turns: z12.number().int().nullable(),
-  usdCost: z12.number().nullable(),
-  durationMs: z12.number().int().nullable(),
-  exitReason: z12.string().nullable(),
-  createdAt: z12.string(),
-  startedAt: z12.string().nullable(),
-  finishedAt: z12.string().nullable()
+  promptSnippet: z14.string(),
+  batchId: z14.string(),
+  experiment: z14.string().nullable(),
+  turns: z14.number().int().nullable(),
+  usdCost: z14.number().nullable(),
+  durationMs: z14.number().int().nullable(),
+  exitReason: z14.string().nullable(),
+  createdAt: z14.string(),
+  startedAt: z14.string().nullable(),
+  finishedAt: z14.string().nullable()
 });
 var runListResponseSchema = listResponseSchema(runListItemSchema);
 var runDetailSchema = runListItemSchema.omit({ promptSnippet: true }).extend({
-  promptText: z12.string(),
-  attempt: z12.number().int(),
-  cancelRequested: z12.boolean(),
-  failureReason: z12.string().nullable(),
-  repoUrl: z12.string().nullable(),
-  repoRef: z12.string().nullable(),
-  scenario: z12.string(),
-  funding: z12.string(),
+  promptText: z14.string(),
+  attempt: z14.number().int(),
+  cancelRequested: z14.boolean(),
+  failureReason: z14.string().nullable(),
+  repoUrl: z14.string().nullable(),
+  repoRef: z14.string().nullable(),
+  scenario: z14.string(),
+  funding: z14.string(),
   /** Raw harness usage write-back (token counts etc.); shape may evolve. */
-  usage: z12.unknown().nullable(),
+  usage: z14.unknown().nullable(),
   /** Artifact pointer: a working-tree diff exists at GET /runs/{id}/diff. */
-  hasDiff: z12.boolean(),
-  claimedAt: z12.string().nullable()
+  hasDiff: z14.boolean(),
+  claimedAt: z14.string().nullable()
 });
-var cancelRunResponseSchema = z12.object({
-  id: z12.string(),
+var cancelRunResponseSchema = z14.object({
+  id: z14.string(),
   status: runStatusSchema,
-  cancelRequested: z12.boolean(),
-  note: z12.string().optional()
-});
-var runEventSchema = z12.looseObject({
-  run_id: z12.string(),
-  seq: z12.number(),
-  turn: z12.number(),
-  ts: z12.string(),
-  type: z12.string()
-});
-
-// ../packages/api-schemas/src/stats.ts
-import { z as z13 } from "zod";
-var BRAND_KINDS2 = ["OWNED", "COMPETITOR", "OTHER"];
-var brandKindSchema2 = z13.enum(BRAND_KINDS2);
-var brandRankingSchema = z13.object({
-  rank: z13.number().int(),
-  brandId: z13.string(),
-  brandName: z13.string(),
-  kind: brandKindSchema2,
-  installs: z13.number().int(),
-  installRate: z13.number(),
-  mentionRate: z13.number(),
-  /** Movement between the two most recent batch windows; null if not ranked in both. */
-  deltaRank: z13.number().int().nullable()
-});
-var packageRateSchema = z13.object({
-  ecosystem: z13.string(),
-  name: z13.string(),
-  brandName: z13.string().optional(),
-  kind: brandKindSchema2.optional(),
-  installs: z13.number().int(),
-  rate: z13.number()
-});
-var brandRateSchema = z13.object({
-  brandId: z13.string(),
-  brandName: z13.string(),
-  kind: brandKindSchema2,
-  installs: z13.number().int(),
-  rate: z13.number()
-});
-var brandFunnelRowSchema = z13.object({
-  brandId: z13.string(),
-  brandName: z13.string(),
-  kind: brandKindSchema2,
-  mentionRate: z13.number(),
-  installRate: z13.number()
-});
-var domainRateSchema = z13.object({
-  domain: z13.string(),
-  runs: z13.number().int(),
-  rate: z13.number(),
-  requests: z13.number().int(),
-  deniedRequests: z13.number().int(),
-  brandName: z13.string().optional(),
-  owned: z13.boolean().optional()
-});
-var statsFreshnessSchema = z13.object({
-  /** Newest run-ingest time across the org (ISO), or null if nothing ingested. */
-  watermark: z13.string().nullable(),
-  /** Runs that succeeded recently but haven't landed in the warehouse yet. */
-  pending: z13.number().int(),
-  /** False when the freshness read itself failed (distinguish from genuine zero). */
-  available: z13.boolean()
+  cancelRequested: z14.boolean(),
+  note: z14.string().optional()
+});
+var forkRunBodySchema = z14.object({
+  prompt: z14.string().trim().min(1).max(2e4),
+  turn: z14.number().int().min(0).optional()
+});
+var forkRunResponseSchema = z14.object({
+  runId: z14.string(),
+  batchId: z14.string(),
+  parentRunId: z14.string(),
+  checkpointId: z14.string(),
+  turn: z14.number().int().min(0)
+});
+var runEventSchema = z14.looseObject({
+  run_id: z14.string(),
+  seq: z14.number(),
+  turn: z14.number(),
+  ts: z14.string(),
+  type: z14.string()
 });
-var statsResponseSchema = (item) => z13.object({ items: z13.array(item), freshness: statsFreshnessSchema });
-var rankingsResponseSchema = statsResponseSchema(brandRankingSchema);
-var installsResponseSchema = statsResponseSchema(packageRateSchema);
-var brandsResponseSchema = statsResponseSchema(brandRateSchema);
-var funnelResponseSchema = statsResponseSchema(brandFunnelRowSchema);
-var domainsResponseSchema = statsResponseSchema(domainRateSchema);
 
 // ../packages/api-schemas/src/tokens.ts
-import { z as z14 } from "zod";
-var apiTokenSchema = z14.object({
-  id: z14.string(),
-  name: z14.string(),
+import { z as z15 } from "zod";
+var apiTokenSchema = z15.object({
+  id: z15.string(),
+  name: z15.string(),
   /** Last 4 chars of the plaintext, for recognizability (non-secret). */
-  last4: z14.string(),
-  expiresAt: z14.iso.datetime().nullable(),
-  lastUsedAt: z14.iso.datetime().nullable(),
-  createdAt: z14.iso.datetime(),
-  revokedAt: z14.iso.datetime().nullable()
-});
-var createTokenRequestSchema = z14.object({
-  name: z14.string().min(1).max(100),
+  last4: z15.string(),
+  expiresAt: z15.iso.datetime().nullable(),
+  lastUsedAt: z15.iso.datetime().nullable(),
+  createdAt: z15.iso.datetime(),
+  revokedAt: z15.iso.datetime().nullable()
+});
+var createTokenRequestSchema = z15.object({
+  name: z15.string().min(1).max(100),
   /** ISO-8601 datetime; omit for no expiry. */
-  expiresAt: z14.iso.datetime({ offset: true }).optional()
+  expiresAt: z15.iso.datetime({ offset: true }).optional()
 });
 var createTokenResponseSchema = apiTokenSchema.extend({
-  token: z14.string()
+  token: z15.string()
 });
 var listTokensResponseSchema = listResponseSchema(apiTokenSchema);
 
 // src/commands/apply.ts
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 
 // src/version.ts
 import { createRequire } from "module";
@@ -1082,7 +1204,16 @@ var EXAMPLE_SPEC = {
       key: "migrate-to-vitest",
       text: "Migrate the test suite from Jest to Vitest.",
       scenario: "MIGRATION",
-      schedules: [{ repoUrl: "https://github.com/acme/api", repoRef: "main" }]
+      schedules: [
+        {
+          repoUrl: "https://github.com/acme/api",
+          repoRef: "main",
+          // Optional: pin a specific model id. Must be one the schedule's
+          // agent(s) can actually serve, or the run falls back to the agent
+          // default. Omit (or use null) to always use the agent default.
+          model: "claude-opus-4-8"
+        }
+      ]
     }
   ]
 };
@@ -1181,7 +1312,7 @@ function register(program2) {
   ).option("-f, --file <path>", "battery spec JSON file").option("--dry-run", "print the plan without applying").option("--schema", "print the battery spec JSON Schema and exit").option("--example", "print a minimal example battery spec and exit").action(
     async (opts, command) => {
       if (opts.schema) {
-        printJson(z15.toJSONSchema(batteries_exports.batterySpecSchema));
+        printJson(z16.toJSONSchema(batteries_exports.batterySpecSchema));
         return;
       }
       if (opts.example) {
@@ -2244,10 +2375,239 @@ function register9(program2) {
   );
 }
 
+// src/commands/query.ts
+var query_exports2 = {};
+__export(query_exports2, {
+  register: () => register10
+});
+var collect3 = (value, prev = []) => [
+  ...prev,
+  value
+];
+var csv = (raw) => raw.split(",").map((s) => s.trim()).filter(Boolean);
+function parseWhere(expr) {
+  const inMatch = expr.match(/^\s*(\w+)\s+(in|contains)\s+(.*)$/i);
+  if (inMatch) {
+    const [, dimension2, opRaw, rest2] = inMatch;
+    const op = opRaw.toLowerCase();
+    if (op === "in") {
+      return { dimension: dimension2, op: "in", value: csv(rest2) };
+    }
+    return { dimension: dimension2, op: "contains", value: rest2.trim() };
+  }
+  const opMatch = expr.match(/^\s*(\w+)\s*(!=|>=|<=|=|>|<)\s*(.*)$/);
+  if (!opMatch) {
+    throw new CliError(
+      "usage",
+      `Could not parse --where "${expr}". Use e.g. "action=install", "ecosystem in npm,pypi", or "name contains supa".`
+    );
+  }
+  const [, dimension, sym, rest] = opMatch;
+  const opFor = {
+    "=": "eq",
+    "!=": "neq",
+    ">": "gt",
+    ">=": "gte",
+    "<": "lt",
+    "<=": "lte"
+  };
+  return { dimension, op: opFor[sym], value: rest.trim() };
+}
+function parseOrderBy(raw) {
+  const [key, dir] = raw.split(":");
+  return { key: key.trim(), dir: dir?.trim() === "asc" ? "asc" : "desc" };
+}
+async function readStdin2() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function buildSpec(opts) {
+  let spec = { metrics: [] };
+  if (opts.json) {
+    const raw = opts.json === "-" ? await readStdin2() : opts.json;
+    try {
+      spec = JSON.parse(raw);
+    } catch (e) {
+      throw new CliError(
+        "usage",
+        `--json is not valid JSON: ${e.message}`
+      );
+    }
+  }
+  if (opts.dataset) spec.dataset = opts.dataset;
+  if (opts.dimensions !== void 0) spec.dimensions = csv(opts.dimensions);
+  if (opts.metrics !== void 0) spec.metrics = csv(opts.metrics);
+  if (opts.where?.length) spec.where = opts.where.map(parseWhere);
+  if (opts.orderBy?.length) spec.orderBy = opts.orderBy.map(parseOrderBy);
+  if (opts.limit !== void 0) spec.limit = Number(opts.limit);
+  if (opts.granularity)
+    spec.granularity = opts.granularity;
+  if (opts.explain) spec.explain = true;
+  const date = {
+    ...spec.dateRange ?? {}
+  };
+  if (opts.since) {
+    date.since = opts.since;
+    delete date.lastDays;
+  } else if (opts.lastDays) {
+    date.lastDays = Number(opts.lastDays);
+    delete date.since;
+  }
+  if (opts.until) date.until = opts.until;
+  if (Object.keys(date).length) spec.dateRange = date;
+  if (opts.branded && opts.unbranded) {
+    throw new CliError("usage", "Pass at most one of --branded / --unbranded.");
+  }
+  const filters = {
+    ...spec.filters ?? {}
+  };
+  if (opts.prompt) filters.prompt = opts.prompt;
+  if (opts.topic) filters.topic = csv(opts.topic);
+  if (opts.tag) filters.tag = csv(opts.tag);
+  if (opts.repo) filters.repo = csv(opts.repo);
+  if (opts.language) filters.language = csv(opts.language);
+  if (opts.framework) filters.framework = csv(opts.framework);
+  if (opts.size) filters.size = csv(opts.size);
+  if (opts.agent) filters.agent = csv(opts.agent);
+  if (opts.model) filters.model = csv(opts.model);
+  if (opts.scenario) filters.scenario = csv(opts.scenario);
+  if (opts.experiment) filters.experiment = csv(opts.experiment);
+  if (opts.branded) filters.branded = true;
+  if (opts.unbranded) filters.branded = false;
+  if (Object.keys(filters).length) spec.filters = filters;
+  if (!spec.metrics || spec.metrics.length === 0) {
+    throw new CliError(
+      "usage",
+      "At least one metric is required. Pass --metrics <a,b> (or a `metrics` array in --json). See `gauge query fields --dataset <name>`."
+    );
+  }
+  return spec;
+}
+var pct = (n) => `${(n * 100).toFixed(1)}%`;
+function noteFreshness(f) {
+  if (!f.available) {
+    console.error(
+      "warning: analytics store is temporarily unavailable; results may be incomplete."
+    );
+  } else if (f.pending > 0) {
+    console.error(
+      `note: ${f.pending} recent run(s) still ingesting; results may not reflect them yet.`
+    );
+  }
+}
+async function runQuery(command, opts) {
+  const org = resolveOrg(command);
+  const output = resolveOutput(command);
+  const spec = await buildSpec(opts);
+  const res = await createClient().post(
+    `/api/v1/orgs/${encodeURIComponent(org)}/query`,
+    spec
+  );
+  if (output === "json") {
+    printJson(res);
+    return;
+  }
+  if (res.sql) console.error(`
+${res.sql}
+`);
+  const rateKeys = new Set(
+    res.columns.filter((c) => c.kind === "metric" && c.key.endsWith("_rate")).map((c) => c.key)
+  );
+  const rows = res.rows.map((row) => {
+    const out = {};
+    for (const col of res.columns) {
+      const v = row[col.key];
+      out[col.key] = rateKeys.has(col.key) && typeof v === "number" ? pct(v) : v;
+    }
+    return out;
+  });
+  printItems(
+    rows,
+    "table",
+    res.columns.map((c) => ({ key: c.key }))
+  );
+  noteFreshness(res.freshness);
+}
+async function showMetadata(command, mode, dataset) {
+  const org = resolveOrg(command);
+  const output = resolveOutput(command);
+  const meta = await createClient().get(
+    `/api/v1/orgs/${encodeURIComponent(org)}/query/metadata`
+  );
+  if (mode === "datasets") {
+    if (output === "json")
+      return printJson(
+        meta.datasets.map((d) => ({ name: d.name, grain: d.grain }))
+      );
+    printItems(
+      meta.datasets.map((d) => ({ dataset: d.name, grain: d.grain })),
+      "table"
+    );
+    return;
+  }
+  const ds = meta.datasets.find((d) => d.name === dataset);
+  if (!ds) {
+    throw new CliError(
+      "usage",
+      `Unknown dataset "${dataset}". Valid: ${meta.datasets.map((d) => d.name).join(", ")}.`
+    );
+  }
+  if (output === "json") return printJson(ds);
+  const rows = [
+    ...ds.dimensions.map((f) => ({
+      field: f.name,
+      kind: "dimension",
+      type: f.type,
+      about: f.description ?? ""
+    })),
+    ...ds.metrics.map((f) => ({
+      field: f.name,
+      kind: "metric",
+      type: f.type,
+      about: f.description ?? ""
+    }))
+  ];
+  console.error(`dataset: ${ds.name} \u2014 ${ds.grain}`);
+  printItems(rows, "table");
+}
+function register10(program2) {
+  const group = program2.command("query").description(
+    "Flexible reports over your event warehouse (run a report, or discover the catalog)"
+  );
+  group.command("run", { isDefault: true }).description("Run a report (default command)").option(
+    "--json <spec>",
+    "full query spec as JSON (or '-' to read stdin); flags override its keys"
+  ).option(
+    "--dataset <name>",
+    "runs | installs | mentions | web | network | files | tokens (default runs)"
+  ).option("-d, --dimensions <names>", "comma-separated GROUP BY dimensions").option("-m, --metrics <names>", "comma-separated metrics (at least one)").option(
+    "--where <expr>",
+    'predicate, e.g. "action=install" (repeatable)',
+    collect3
+  ).option("--since <val>", "date range start \u2014 ISO date or window (30d, 24h)").option("--until <val>", "date range end \u2014 ISO date or window").option("--last-days <n>", "shorthand for --since <n> days ago").option(
+    "--order-by <key:dir>",
+    "sort by a selected key, e.g. installs:desc (repeatable)",
+    collect3
+  ).option("--limit <n>", "max rows (default 50, max 1000)").option(
+    "--granularity <g>",
+    "date bucket: day | week | month (default day)"
+  ).option("--explain", "print the compiled SQL to stderr").option("--prompt <id>", "filter to a single prompt").option("--topic <ids>", "comma-separated topic ids").option("--tag <ids>", "comma-separated tag ids").option("--repo <urls>", "comma-separated base repo urls").option("--language <langs>", "comma-separated repo languages").option("--framework <names>", "comma-separated repo frameworks").option("--size <buckets>", "comma-separated codebase-size buckets").option("--agent <names>", "comma-separated agent names").option("--model <models>", "comma-separated models").option(
+    "--scenario <types>",
+    "comma-separated scenario types (greenfield|migration)"
+  ).option("--experiment <labels>", "comma-separated experiment labels").option("--branded", "only branded prompts").option("--unbranded", "only non-branded prompts").action((opts, command) => runQuery(command, opts));
+  group.command("datasets").description("List the datasets you can query").action(
+    (_opts, command) => showMetadata(command, "datasets")
+  );
+  group.command("fields").description("List the dimensions and metrics for a dataset").requiredOption("--dataset <name>", "dataset to describe").action(
+    (opts, command) => showMetadata(command, "fields", opts.dataset)
+  );
+}
+
 // src/commands/repos.ts
 var repos_exports2 = {};
 __export(repos_exports2, {
-  register: () => register10
+  register: () => register11
 });
 function reposPath(org) {
   return `/api/v1/orgs/${encodeURIComponent(org)}/repos`;
@@ -2270,7 +2630,7 @@ function toRow3(repo) {
 function syncWarning(repo) {
   return `warning: GitHub metadata sync failed; retry with \`gauge repos resync ${repo.url}\``;
 }
-function register10(program2) {
+function register11(program2) {
   const repos = program2.command("repos").description("Manage repositories");
   repos.command("list").description("List repositories (yours + read-only Gauge-provided ones)").action(async (_opts, command) => {
     const org = resolveOrg(command);
@@ -2334,7 +2694,7 @@ function register10(program2) {
 // src/commands/runs.ts
 var runs_exports2 = {};
 __export(runs_exports2, {
-  register: () => register11
+  register: () => register12
 });
 function runPath(id) {
   return `/api/v1/runs/${encodeURIComponent(id)}`;
@@ -2512,7 +2872,7 @@ async function streamRun(id, json, opts) {
     if (drainTimer) clearTimeout(drainTimer);
   }
 }
-function register11(program2) {
+function register12(program2) {
   const runs = program2.command("runs").description("Inspect and manage runs");
   runs.command("list").description("List runs (newest first)").option("--status <status>", "filter by status, e.g. running,queued").option("--batch <id>", "filter by batch").option("--prompt <id>", "filter by prompt").option("--experiment <experiment>", "filter by experiment label").option("--since <window>", "e.g. 24h, 7d, or an ISO date").option("--limit <n>", "page size (1-200)", "50").option("--cursor <cursor>", "resume from a previous page's nextCursor").action(
     async (opts, command) => {
@@ -2574,6 +2934,20 @@ function register11(program2) {
     const diff = await createClient().get(`${runPath(id)}/diff`);
     process.stdout.write(diff);
   });
+  runs.command("fork <id>").description("Fork a finished run from its latest conversation checkpoint").requiredOption("--prompt <text>", "continuation prompt for the child run").action(async (id, opts, command) => {
+    const result = await createClient().post(
+      `${runPath(id)}/fork`,
+      { prompt: opts.prompt }
+    );
+    if (resolveOutput(command) === "json") {
+      printJson(result);
+      return;
+    }
+    console.log(
+      `Forked run ${result.runId} from ${result.parentRunId} at turn ${result.turn}`
+    );
+    console.error(`Watch it with: gauge runs watch ${result.runId}`);
+  });
   runs.command("cancel <id>").description("Request cancellation of a run").action(async (id, _opts, command) => {
     const result = await createClient().post(
       `${runPath(id)}/cancel`
@@ -2592,7 +2966,7 @@ function register11(program2) {
 // src/commands/schedules.ts
 var schedules_exports2 = {};
 __export(schedules_exports2, {
-  register: () => register12
+  register: () => register13
 });
 var CADENCE_CHOICES = [
   "none",
@@ -2628,7 +3002,7 @@ function toRow5(s) {
     experiment: s.experiment ?? ""
   };
 }
-function register12(program2) {
+function register13(program2) {
   const group = program2.command("schedules").description("Manage prompt schedules");
   group.command("list").description("List schedules for a prompt").requiredOption("--prompt <id>", "prompt id").action(async (opts, cmd) => {
     const org = resolveOrg(cmd);
@@ -2699,7 +3073,7 @@ function register12(program2) {
 // src/commands/stats.ts
 var stats_exports2 = {};
 __export(stats_exports2, {
-  register: () => register13
+  register: () => register14
 });
 function addFilterOptions(cmd) {
   return cmd.option("--prompt <id>", "filter to a single prompt").option("--topic <ids>", "comma-separated topic ids").option("--tag <ids>", "comma-separated tag ids").option("--repo <urls>", "comma-separated base repo urls").option("--language <langs>", "comma-separated repo languages").option("--framework <names>", "comma-separated repo frameworks").option("--size <buckets>", "comma-separated codebase-size buckets").option("--branded", "only branded prompts").option("--unbranded", "only non-branded prompts").option("--limit <n>", "max rows (default 50)").option("--full", "return all rows (up to 1000)");
@@ -2720,9 +3094,9 @@ function filterQuery(opts) {
     limit: opts.full ? "1000" : opts.limit
   };
 }
-var pct = (rate) => `${(rate * 100).toFixed(1)}%`;
+var pct2 = (rate) => `${(rate * 100).toFixed(1)}%`;
 var delta = (d) => d === null || d === 0 ? "\u2014" : d > 0 ? `+${d}` : String(d);
-function noteFreshness(f) {
+function noteFreshness2(f) {
   if (!f.available) {
     console.error(
       "warning: analytics store is temporarily unavailable; results may be incomplete."
@@ -2745,15 +3119,15 @@ async function runStats(command, resource, opts, toRow6) {
     return;
   }
   printItems(res.items.map(toRow6), "table");
-  noteFreshness(res.freshness);
+  noteFreshness2(res.freshness);
 }
 var rankingRow = (r) => ({
   rank: r.rank,
   brand: r.brandName,
   kind: r.kind,
   installs: r.installs,
-  "install%": pct(r.installRate),
-  "mention%": pct(r.mentionRate),
+  "install%": pct2(r.installRate),
+  "mention%": pct2(r.mentionRate),
   delta: delta(r.deltaRank)
 });
 var packageRow = (r) => ({
@@ -2762,29 +3136,28 @@ var packageRow = (r) => ({
   brand: r.brandName,
   kind: r.kind,
   installs: r.installs,
-  rate: pct(r.rate)
+  rate: pct2(r.rate)
 });
 var brandRow = (r) => ({
   brand: r.brandName,
   kind: r.kind,
   installs: r.installs,
-  rate: pct(r.rate)
+  rate: pct2(r.rate)
 });
 var funnelRow = (r) => ({
   brand: r.brandName,
   kind: r.kind,
-  "mention%": pct(r.mentionRate),
-  "install%": pct(r.installRate)
+  "mention%": pct2(r.mentionRate),
+  "install%": pct2(r.installRate)
 });
 var domainRow = (r) => ({
   domain: r.domain,
   brand: r.brandName,
   runs: r.runs,
-  rate: pct(r.rate),
-  requests: r.requests,
-  denied: r.deniedRequests
+  rate: pct2(r.rate),
+  requests: r.requests
 });
-function register13(program2) {
+function register14(program2) {
   const group = program2.command("stats").description("Read-only analytics over your runs");
   addFilterOptions(
     group.command("rankings").description("Brands ranked by install rate")
@@ -2816,12 +3189,12 @@ function register13(program2) {
 // src/commands/tags.ts
 var tags_exports2 = {};
 __export(tags_exports2, {
-  register: () => register14
+  register: () => register15
 });
 function tagsPath(org) {
   return `/api/v1/orgs/${encodeURIComponent(org)}/tags`;
 }
-function register14(program2) {
+function register15(program2) {
   const group = program2.command("tags").description("Manage org tags");
   group.command("list").description("List tags").action(async (_opts, cmd) => {
     const org = resolveOrg(cmd);
@@ -2864,12 +3237,12 @@ function register14(program2) {
 // src/commands/topics.ts
 var topics_exports2 = {};
 __export(topics_exports2, {
-  register: () => register15
+  register: () => register16
 });
 function topicsPath(org) {
   return `/api/v1/orgs/${encodeURIComponent(org)}/topics`;
 }
-function register15(program2) {
+function register16(program2) {
   const group = program2.command("topics").description("Manage org topics");
   group.command("list").description("List topics").action(async (_opts, cmd) => {
     const org = resolveOrg(cmd);
@@ -2890,9 +3263,9 @@ function register15(program2) {
 // src/commands/usage.ts
 var usage_exports = {};
 __export(usage_exports, {
-  register: () => register16
+  register: () => register17
 });
-function register16(program2) {
+function register17(program2) {
   program2.command("usage").description("List credit ledger entries").option("--since <window>", 'e.g. "30d", "24h", or an ISO date').option("--limit <n>", "page size (1-200)", parseLimit, 50).option("--cursor <cursor>", "resume from a previous page's nextCursor").action(
     async (opts, cmd) => {
       const org = resolveOrg(cmd);
@@ -2962,6 +3335,7 @@ for (const group of [
   billing_exports2,
   usage_exports,
   stats_exports2,
+  query_exports2,
   config_exports
 ]) {
   group.register(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withgauge/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Gauge customer CLI — prompts, repos, runs & org settings over the Gauge API",
   "private": false,
   "author": "Gauge <support@withgauge.com> (https://withgauge.com)",