@sentio/cli 3.5.0-rc.1 → 3.5.0-rc.2

package/lib/index.js

@@ -1220,7 +1220,7 @@ var require_command = __commonJS({
     var childProcess4 = __require("node:child_process");
     var path16 = __require("node:path");
     var fs20 = __require("node:fs");
-    var process24 = __require("node:process");
+    var process25 = __require("node:process");
     var { Argument: Argument7, humanReadableArgName } = require_argument();
     var { CommanderError: CommanderError2 } = require_error();
     var { Help: Help2, stripColor } = require_help();
@@ -1267,13 +1267,13 @@ var require_command = __commonJS({
         this._showSuggestionAfterError = true;
         this._savedState = null;
         this._outputConfiguration = {
-          writeOut: (str) => process24.stdout.write(str),
-          writeErr: (str) => process24.stderr.write(str),
+          writeOut: (str) => process25.stdout.write(str),
+          writeErr: (str) => process25.stderr.write(str),
           outputError: (str, write) => write(str),
-          getOutHelpWidth: () => process24.stdout.isTTY ? process24.stdout.columns : void 0,
-          getErrHelpWidth: () => process24.stderr.isTTY ? process24.stderr.columns : void 0,
-          getOutHasColors: () => useColor() ?? (process24.stdout.isTTY && process24.stdout.hasColors?.()),
-          getErrHasColors: () => useColor() ?? (process24.stderr.isTTY && process24.stderr.hasColors?.()),
+          getOutHelpWidth: () => process25.stdout.isTTY ? process25.stdout.columns : void 0,
+          getErrHelpWidth: () => process25.stderr.isTTY ? process25.stderr.columns : void 0,
+          getOutHasColors: () => useColor() ?? (process25.stdout.isTTY && process25.stdout.hasColors?.()),
+          getErrHasColors: () => useColor() ?? (process25.stderr.isTTY && process25.stderr.hasColors?.()),
           stripColor: (str) => stripColor(str)
         };
         this._hidden = false;
@@ -1668,7 +1668,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (this._exitCallback) {
           this._exitCallback(new CommanderError2(exitCode, code, message));
         }
-        process24.exit(exitCode);
+        process25.exit(exitCode);
       }
       /**
        * Register callback `fn` for the command.
@@ -2068,16 +2068,16 @@ Expecting one of '${allowedValues.join("', '")}'`);
         }
         parseOptions = parseOptions || {};
         if (argv === void 0 && parseOptions.from === void 0) {
-          if (process24.versions?.electron) {
+          if (process25.versions?.electron) {
             parseOptions.from = "electron";
           }
-          const execArgv = process24.execArgv ?? [];
+          const execArgv = process25.execArgv ?? [];
           if (execArgv.includes("-e") || execArgv.includes("--eval") || execArgv.includes("-p") || execArgv.includes("--print")) {
             parseOptions.from = "eval";
           }
         }
         if (argv === void 0) {
-          argv = process24.argv;
+          argv = process25.argv;
         }
         this.rawArgs = argv.slice();
         let userArgs;
@@ -2088,7 +2088,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
             userArgs = argv.slice(2);
             break;
           case "electron":
-            if (process24.defaultApp) {
+            if (process25.defaultApp) {
               this._scriptPath = argv[1];
               userArgs = argv.slice(2);
             } else {
@@ -2275,11 +2275,11 @@ Expecting one of '${allowedValues.join("', '")}'`);
         }
         launchWithNode = sourceExt.includes(path16.extname(executableFile));
         let proc;
-        if (process24.platform !== "win32") {
+        if (process25.platform !== "win32") {
           if (launchWithNode) {
             args.unshift(executableFile);
-            args = incrementNodeInspectorPort(process24.execArgv).concat(args);
-            proc = childProcess4.spawn(process24.argv[0], args, { stdio: "inherit" });
+            args = incrementNodeInspectorPort(process25.execArgv).concat(args);
+            proc = childProcess4.spawn(process25.argv[0], args, { stdio: "inherit" });
           } else {
             proc = childProcess4.spawn(executableFile, args, { stdio: "inherit" });
           }
@@ -2290,13 +2290,13 @@ Expecting one of '${allowedValues.join("', '")}'`);
             subcommand._name
           );
           args.unshift(executableFile);
-          args = incrementNodeInspectorPort(process24.execArgv).concat(args);
-          proc = childProcess4.spawn(process24.execPath, args, { stdio: "inherit" });
+          args = incrementNodeInspectorPort(process25.execArgv).concat(args);
+          proc = childProcess4.spawn(process25.execPath, args, { stdio: "inherit" });
         }
         if (!proc.killed) {
           const signals = ["SIGUSR1", "SIGUSR2", "SIGTERM", "SIGINT", "SIGHUP"];
           signals.forEach((signal) => {
-            process24.on(signal, () => {
+            process25.on(signal, () => {
               if (proc.killed === false && proc.exitCode === null) {
                 proc.kill(signal);
               }
@@ -2307,7 +2307,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         proc.on("close", (code) => {
           code = code ?? 1;
           if (!exitCallback) {
-            process24.exit(code);
+            process25.exit(code);
           } else {
             exitCallback(
               new CommanderError2(
@@ -2329,7 +2329,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
             throw new Error(`'${executableFile}' not executable`);
           }
           if (!exitCallback) {
-            process24.exit(1);
+            process25.exit(1);
           } else {
             const wrappedError = new CommanderError2(
               1,
@@ -2830,13 +2830,13 @@ Expecting one of '${allowedValues.join("', '")}'`);
        */
       _parseOptionsEnv() {
         this.options.forEach((option2) => {
-          if (option2.envVar && option2.envVar in process24.env) {
+          if (option2.envVar && option2.envVar in process25.env) {
             const optionKey = option2.attributeName();
             if (this.getOptionValue(optionKey) === void 0 || ["default", "config", "env"].includes(
               this.getOptionValueSource(optionKey)
             )) {
               if (option2.required || option2.optional) {
-                this.emit(`optionEnv:${option2.name()}`, process24.env[option2.envVar]);
+                this.emit(`optionEnv:${option2.name()}`, process25.env[option2.envVar]);
               } else {
                 this.emit(`optionEnv:${option2.name()}`);
               }
@@ -3360,7 +3360,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        */
       help(contextOptions) {
         this.outputHelp(contextOptions);
-        let exitCode = Number(process24.exitCode ?? 0);
+        let exitCode = Number(process25.exitCode ?? 0);
         if (exitCode === 0 && contextOptions && typeof contextOptions !== "function" && contextOptions.error) {
           exitCode = 1;
         }
@@ -3450,9 +3450,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
       });
     }
     function useColor() {
-      if (process24.env.NO_COLOR || process24.env.FORCE_COLOR === "0" || process24.env.FORCE_COLOR === "false")
+      if (process25.env.NO_COLOR || process25.env.FORCE_COLOR === "0" || process25.env.FORCE_COLOR === "false")
         return false;
-      if (process24.env.FORCE_COLOR || process24.env.CLICOLOR_FORCE !== void 0)
+      if (process25.env.FORCE_COLOR || process25.env.CLICOLOR_FORCE !== void 0)
         return true;
       return void 0;
     }
@@ -5903,10 +5903,10 @@ var require_directives = __commonJS({
     };
     var escapeTagName = (tn2) => tn2.replace(/[!,[\]{}]/g, (ch) => escapeChars[ch]);
     var Directives = class _Directives {
-      constructor(yaml12, tags) {
+      constructor(yaml13, tags) {
         this.docStart = null;
         this.docEnd = false;
-        this.yaml = Object.assign({}, _Directives.defaultYaml, yaml12);
+        this.yaml = Object.assign({}, _Directives.defaultYaml, yaml13);
         this.tags = Object.assign({}, _Directives.defaultTags, tags);
       }
       clone() {
@@ -41614,15 +41614,15 @@ var require_streams2 = __commonJS({
     var POOL_SIZE2 = 65536;
     if (!globalThis.ReadableStream) {
       try {
-        const process24 = __require("node:process");
-        const { emitWarning } = process24;
+        const process25 = __require("node:process");
+        const { emitWarning } = process25;
         try {
-          process24.emitWarning = () => {
+          process25.emitWarning = () => {
           };
           Object.assign(globalThis, __require("node:stream/web"));
-          process24.emitWarning = emitWarning;
+          process25.emitWarning = emitWarning;
         } catch (error) {
-          process24.emitWarning = emitWarning;
+          process25.emitWarning = emitWarning;
           throw error;
         }
       } catch (error) {
@@ -141911,7 +141911,7 @@ var require_sdk_gen = __commonJS({
       }
     };
     exports.DataService = DataService2;
-    var WebService = class {
+    var WebService2 = class {
       /**
        * List all dashboards in a project
        */
@@ -142094,7 +142094,7 @@ var require_sdk_gen = __commonJS({
         });
       }
     };
-    exports.WebService = WebService;
+    exports.WebService = WebService2;
     var MoveService = class {
       /**
        * Get Aptos transaction call trace
@@ -154267,6 +154267,347 @@ function parseInteger6(value) {
   return parsedValue;
 }
 
+// src/commands/dashboard.ts
+init_cjs_shim();
+var import_api14 = __toESM(require_src5(), 1);
+var import_yaml12 = __toESM(require_dist(), 1);
+import process24 from "process";
+function createDashboardCommand() {
+  const dashboardCommand = new Command("dashboard").description("Manage Sentio dashboards");
+  dashboardCommand.addCommand(createDashboardListCommand());
+  dashboardCommand.addCommand(createDashboardExportCommand());
+  dashboardCommand.addCommand(createDashboardImportCommand());
+  dashboardCommand.addCommand(createDashboardAddPanelCommand());
+  return dashboardCommand;
+}
+function createDashboardListCommand() {
+  return withOutputOptions8(
+    withSharedProjectOptions7(withAuthOptions8(new Command("list").description("List dashboards for a project")))
+  ).showHelpAfterError().action(async (options, command) => {
+    try {
+      await runDashboardList(options);
+    } catch (error) {
+      handleDashboardCommandError(error, command);
+    }
+  });
+}
+function createDashboardExportCommand() {
+  return withOutputOptions8(
+    withSharedProjectOptions7(
+      withAuthOptions8(
+        new Command("export").description("Export a dashboard as JSON").argument("<dashboardId>", "Dashboard ID")
+      )
+    )
+  ).showHelpAfterError().action(async (dashboardId, options, command) => {
+    try {
+      await runDashboardExport(dashboardId, options);
+    } catch (error) {
+      handleDashboardCommandError(error, command);
+    }
+  });
+}
+function createDashboardImportCommand() {
+  return withOutputOptions8(
+    withSharedProjectOptions7(
+      withAuthOptions8(
+        new Command("import").description("Import dashboard data from a JSON file into an existing dashboard").argument("<dashboardId>", "Target dashboard ID to import into")
+      )
+    )
+  ).showHelpAfterError().option("--file <path>", "Read dashboard JSON from file").option("--stdin", "Read dashboard JSON from stdin").option("--override-layouts", "Override the layout of the target dashboard").action(async (dashboardId, options, command) => {
+    try {
+      await runDashboardImport(dashboardId, options);
+    } catch (error) {
+      handleDashboardCommandError(error, command);
+    }
+  });
+}
+function createDashboardAddPanelCommand() {
+  return withOutputOptions8(
+    withSharedProjectOptions7(
+      withAuthOptions8(
+        new Command("add-panel").description("Add a panel to a dashboard (SQL or insights query)").argument("<dashboardId>", "Dashboard ID")
+      )
+    )
+  ).showHelpAfterError().requiredOption("--panel-name <name>", "Panel name").requiredOption("--type <type>", "Chart type: TABLE, LINE, BAR, PIE, QUERY_VALUE, AREA, BAR_GAUGE, SCATTER").option("--sql <query>", "SQL query (plain SQL \u2014 automatically wrapped into the required format)").option("--size <count>", "SQL query result size limit (default: 100)").option("--event <name>", "Event name for an insights panel (mutually exclusive with --sql and --metric)").option("--metric <name>", "Metric name for an insights panel (mutually exclusive with --sql and --event)").option("--alias <alias>", "Alias for the insights query").option("--source-name <name>", "Source name for the insights query").option(
+    "--filter <selector>",
+    "Event filter or metric label selector like field:value or amount>0",
+    collectOption3,
+    []
+  ).option("--group-by <field>", "Group by event property or metric label", collectOption3, []).option("--aggr <aggregation>", "Event: total|unique|AAU|DAU|WAU|MAU. Metric: avg|sum|min|max|count").option("--func <function>", "Function like topk(1), bottomk(1)", collectOption3, []).addHelpText(
+    "after",
+    `
+
+Data source: use exactly one of --sql, --event, or --metric.
+
+SQL panel examples:
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Top Holders" --type TABLE \\
+      --sql "SELECT * FROM CoinBalance ORDER BY balance DESC LIMIT 50"
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Daily Volume" --type LINE \\
+      --sql "SELECT toStartOfDay(timestamp) as date, sum(amount) as volume FROM Transfer GROUP BY date ORDER BY date"
+
+Event insights panel examples:
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Transfer Count" --type LINE \\
+      --event Transfer --aggr total
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Large Transfers" --type TABLE \\
+      --event Transfer --filter amount>1000 --aggr total --group-by meta.address
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Top 5 Senders" --type BAR \\
+      --event Transfer --aggr unique --group-by from --func 'topk(5)'
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "DAU" --type LINE \\
+      --event Transfer --aggr DAU
+
+Metric insights panel examples:
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "ETH Price" --type LINE \\
+      --metric cbETH_price
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Avg Burn by Chain" --type BAR \\
+      --metric burn --filter meta.chain=1 --aggr avg --group-by meta.address
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Burn Rate Delta" --type LINE \\
+      --metric burn --aggr sum 
+`
+  ).action(async (dashboardId, options, command) => {
+    try {
+      await runDashboardAddPanel(dashboardId, options);
+    } catch (error) {
+      handleDashboardCommandError(error, command);
+    }
+  });
+}
+async function runDashboardList(options) {
+  const context = createApiContext(options);
+  const project = await resolveProjectRef(options, context, { ownerSlug: true });
+  const response = await import_api14.WebService.listDashboards2({
+    path: { owner: project.owner, slug: project.slug },
+    headers: context.headers
+  });
+  const data = unwrapApiResult(response);
+  printOutput8(options, data);
+}
+async function runDashboardExport(dashboardId, options) {
+  const context = createApiContext(options);
+  const response = await import_api14.WebService.exportDashboard({
+    path: { dashboardId },
+    headers: context.headers
+  });
+  const data = unwrapApiResult(response);
+  console.log(JSON.stringify(data.dashboardJson ?? data, null, 2));
+}
+async function runDashboardImport(dashboardId, options) {
+  const context = createApiContext(options);
+  const input = loadJsonInput(options);
+  if (!input) {
+    throw new CliError("Provide --file or --stdin with the dashboard JSON to import.");
+  }
+  const dashboardJson = typeof input === "object" ? input : {};
+  const response = await import_api14.WebService.importDashboard({
+    body: {
+      dashboardId,
+      dashboardJson,
+      overrideLayouts: options.overrideLayouts
+    },
+    headers: context.headers
+  });
+  const data = unwrapApiResult(response);
+  printOutput8(options, { message: `Dashboard imported into ${dashboardId}`, dashboard: data.dashboard });
+}
+async function runDashboardAddPanel(dashboardId, options) {
+  const context = createApiContext(options);
+  const selectedSources = [Boolean(options.sql), Boolean(options.event), Boolean(options.metric)].filter(Boolean).length;
+  if (selectedSources === 0) {
+    throw new CliError("Provide exactly one data source: --sql, --event, or --metric.");
+  }
+  if (selectedSources > 1) {
+    throw new CliError("Use exactly one of --sql, --event, or --metric.");
+  }
+  const getResponse = await import_api14.WebService.getDashboard({
+    path: { dashboardId },
+    headers: context.headers
+  });
+  const dashboardData = unwrapApiResult(getResponse);
+  const dashboard = dashboardData.dashboards?.[0];
+  if (!dashboard) {
+    throw new CliError(`Dashboard ${dashboardId} not found.`);
+  }
+  const chartType = normalizeChartType(options.type);
+  const panelId = generatePanelId();
+  const chart = buildPanelChart(chartType, options);
+  const newPanel = {
+    id: panelId,
+    name: options.panelName,
+    dashboardId,
+    chart
+  };
+  const existingLayouts = dashboard.layouts?.responsiveLayouts?.lg?.layouts ?? [];
+  let maxBottom = 0;
+  for (const layout of existingLayouts) {
+    const bottom = (layout.y ?? 0) + (layout.h ?? 0);
+    if (bottom > maxBottom) {
+      maxBottom = bottom;
+    }
+  }
+  const newLayout = {
+    i: panelId,
+    x: 0,
+    y: maxBottom,
+    w: 12,
+    h: 6
+  };
+  const panels = { ...dashboard.panels ?? {} };
+  panels[panelId] = newPanel;
+  const updatedLayouts = [...existingLayouts, newLayout];
+  const dashboardJson = {
+    ...dashboard,
+    panels,
+    layouts: {
+      responsiveLayouts: {
+        ...dashboard.layouts?.responsiveLayouts ?? {},
+        lg: { layouts: updatedLayouts }
+      }
+    }
+  };
+  const importResponse = await import_api14.WebService.importDashboard({
+    body: {
+      dashboardId,
+      dashboardJson,
+      overrideLayouts: true
+    },
+    headers: context.headers
+  });
+  const importData = unwrapApiResult(importResponse);
+  printOutput8(options, {
+    message: `Panel "${options.panelName}" added to dashboard ${dashboardId}`,
+    panelId,
+    dashboard: importData.dashboard
+  });
+}
+function buildPanelChart(chartType, options) {
+  if (options.sql) {
+    const sqlSize = Number.parseInt(String(options.size ?? "100"), 10) || 100;
+    return {
+      type: chartType,
+      datasourceType: "SQL",
+      sqlQuery: JSON.stringify({ sql: options.sql, size: sqlSize })
+    };
+  }
+  if (options.event) {
+    const queryBody = buildEventsInsightQueryBody(options.event, {
+      alias: options.alias,
+      sourceName: options.sourceName,
+      filter: options.filter,
+      groupBy: options.groupBy,
+      aggr: options.aggr,
+      func: options.func
+    });
+    return {
+      type: chartType,
+      datasourceType: "INSIGHTS",
+      insightsQueries: queryBody.queries
+    };
+  }
+  if (options.metric) {
+    const queryBody = buildMetricsInsightQueryBody(options.metric, {
+      alias: options.alias,
+      sourceName: options.sourceName,
+      filter: options.filter,
+      groupBy: options.groupBy,
+      aggr: options.aggr,
+      func: options.func
+    });
+    return {
+      type: chartType,
+      datasourceType: "INSIGHTS",
+      insightsQueries: queryBody.queries
+    };
+  }
+  throw new CliError("Provide exactly one data source: --sql, --event, or --metric.");
+}
+function normalizeChartType(value) {
+  const normalized = value.toUpperCase();
+  const valid = ["LINE", "AREA", "BAR", "BAR_GAUGE", "TABLE", "QUERY_VALUE", "PIE", "NOTE", "SCATTER"];
+  if (valid.includes(normalized)) {
+    return normalized;
+  }
+  throw new CliError(`Invalid chart type "${value}". Use one of: ${valid.join(", ")}`);
+}
+function generatePanelId() {
+  return `panel_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function collectOption3(value, previous = []) {
+  previous.push(value);
+  return previous;
+}
+function withAuthOptions8(command) {
+  return command.option("--host <host>", "Override Sentio host").option("--api-key <key>", "Use an explicit API key instead of saved credentials").option("--token <token>", "Use an explicit bearer token instead of saved credentials");
+}
+function withSharedProjectOptions7(command) {
+  return command.option("--project <project>", "Sentio project as <owner>/<slug> or <slug>").option("--owner <owner>", "Sentio project owner").option("--name <name>", "Sentio project name").option("--project-id <id>", "Sentio project id");
+}
+function withOutputOptions8(command) {
+  return command.option("--json", "Print raw JSON response").option("--yaml", "Print raw YAML response");
+}
+function handleDashboardCommandError(error, command) {
+  if (error instanceof CliError && (error.message.startsWith("Project is required.") || error.message.startsWith("Invalid project ") || error.message.startsWith("Dashboard ") || error.message.startsWith("Provide --file or --stdin") || error.message.startsWith("Provide exactly one data source") || error.message.startsWith("Use exactly one of --sql") || error.message.startsWith("Invalid chart type") || error.message.startsWith("Invalid aggregation") || error.message.startsWith("Invalid metric aggregation") || error.message.startsWith("Invalid filter") || error.message.startsWith("Invalid metric selector"))) {
+    console.error(error.message);
+    if (command) {
+      console.error();
+      command.outputHelp();
+    }
+    process24.exit(1);
+  }
+  handleCommandError(error);
+}
+function printOutput8(options, data) {
+  if (options.json && options.yaml) {
+    throw new CliError("Choose only one structured output format: --json or --yaml.");
+  }
+  if (options.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  if (options.yaml) {
+    console.log(import_yaml12.default.stringify(data).trimEnd());
+    return;
+  }
+  console.log(formatOutput7(data));
+}
+function formatOutput7(data) {
+  if (data && typeof data === "object" && "message" in data) {
+    return String(data.message ?? "");
+  }
+  if (data && typeof data === "object" && "dashboards" in data) {
+    const dashboards = data.dashboards ?? [];
+    const lines = [`Dashboards (${dashboards.length})`];
+    for (const db of dashboards) {
+      const id = db.id ?? "<id>";
+      const name = db.name ?? "<unnamed>";
+      const panelCount = db.panels ? Object.keys(db.panels).length : 0;
+      const visibility = db.visibility ?? "";
+      const updated = formatTimestamp3(db.updatedAt);
+      lines.push(
+        `- ${id} "${name}" [${panelCount} panels]${visibility ? ` ${visibility}` : ""}${updated ? ` updated ${updated}` : ""}`
+      );
+    }
+    return lines.join("\n");
+  }
+  return JSON.stringify(data, null, 2);
+}
+function formatTimestamp3(value) {
+  if (!value) {
+    return "";
+  }
+  if (/^\d{13}$/.test(value)) {
+    return new Date(Number.parseInt(value, 10)).toISOString();
+  }
+  return value;
+}
+
 // src/index.ts
 var program2 = new Command();
 program2.name("sentio").description("Login & Manage your project files to Sentio.");
@@ -154293,6 +154634,7 @@ program2.addCommand(createAlertCommand());
 program2.addCommand(createPriceCommand());
 program2.addCommand(createSimulationCommand());
 program2.addCommand(createEndpointCommand());
+program2.addCommand(createDashboardCommand());
 program2.parse();
 /*! Bundled license information:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentio/cli",
-  "version": "3.5.0-rc.1",
+  "version": "3.5.0-rc.2",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {

package/src/commands/dashboard.ts

@@ -0,0 +1,472 @@
+import { WebService } from '@sentio/api'
+import { Command } from '@commander-js/extra-typings'
+import process from 'process'
+import yaml from 'yaml'
+import {
+  CliError,
+  createApiContext,
+  handleCommandError,
+  loadJsonInput,
+  resolveProjectRef,
+  unwrapApiResult
+} from '../api.js'
+import { buildEventsInsightQueryBody, buildMetricsInsightQueryBody } from './data.js'
+
+interface DashboardOptions {
+  host?: string
+  apiKey?: string
+  token?: string
+  project?: string
+  owner?: string
+  name?: string
+  projectId?: string
+  json?: boolean
+  yaml?: boolean
+}
+
+interface DashboardImportOptions extends DashboardOptions {
+  file?: string
+  stdin?: boolean
+  overrideLayouts?: boolean
+}
+
+interface AddPanelOptions extends DashboardOptions {
+  panelName?: string
+  type?: string
+  sql?: string
+  size?: number
+  event?: string
+  metric?: string
+  alias?: string
+  sourceName?: string
+  filter?: string[]
+  groupBy?: string[]
+  aggr?: string
+  func?: string[]
+}
+
+export function createDashboardCommand() {
+  const dashboardCommand = new Command('dashboard').description('Manage Sentio dashboards')
+  dashboardCommand.addCommand(createDashboardListCommand())
+  dashboardCommand.addCommand(createDashboardExportCommand())
+  dashboardCommand.addCommand(createDashboardImportCommand())
+  dashboardCommand.addCommand(createDashboardAddPanelCommand())
+  return dashboardCommand
+}
+
+function createDashboardListCommand() {
+  return withOutputOptions(
+    withSharedProjectOptions(withAuthOptions(new Command('list').description('List dashboards for a project')))
+  )
+    .showHelpAfterError()
+    .action(async (options, command) => {
+      try {
+        await runDashboardList(options)
+      } catch (error) {
+        handleDashboardCommandError(error, command)
+      }
+    })
+}
+
+function createDashboardExportCommand() {
+  return withOutputOptions(
+    withSharedProjectOptions(
+      withAuthOptions(
+        new Command('export').description('Export a dashboard as JSON').argument('<dashboardId>', 'Dashboard ID')
+      )
+    )
+  )
+    .showHelpAfterError()
+    .action(async (dashboardId, options, command) => {
+      try {
+        await runDashboardExport(dashboardId, options)
+      } catch (error) {
+        handleDashboardCommandError(error, command)
+      }
+    })
+}
+
+function createDashboardImportCommand() {
+  return withOutputOptions(
+    withSharedProjectOptions(
+      withAuthOptions(
+        new Command('import')
+          .description('Import dashboard data from a JSON file into an existing dashboard')
+          .argument('<dashboardId>', 'Target dashboard ID to import into')
+      )
+    )
+  )
+    .showHelpAfterError()
+    .option('--file <path>', 'Read dashboard JSON from file')
+    .option('--stdin', 'Read dashboard JSON from stdin')
+    .option('--override-layouts', 'Override the layout of the target dashboard')
+    .action(async (dashboardId, options, command) => {
+      try {
+        await runDashboardImport(dashboardId, options)
+      } catch (error) {
+        handleDashboardCommandError(error, command)
+      }
+    })
+}
+
+function createDashboardAddPanelCommand() {
+  return withOutputOptions(
+    withSharedProjectOptions(
+      withAuthOptions(
+        new Command('add-panel')
+          .description('Add a panel to a dashboard (SQL or insights query)')
+          .argument('<dashboardId>', 'Dashboard ID')
+      )
+    )
+  )
+    .showHelpAfterError()
+    .requiredOption('--panel-name <name>', 'Panel name')
+    .requiredOption('--type <type>', 'Chart type: TABLE, LINE, BAR, PIE, QUERY_VALUE, AREA, BAR_GAUGE, SCATTER')
+    .option('--sql <query>', 'SQL query (plain SQL — automatically wrapped into the required format)')
+    .option('--size <count>', 'SQL query result size limit (default: 100)')
+    .option('--event <name>', 'Event name for an insights panel (mutually exclusive with --sql and --metric)')
+    .option('--metric <name>', 'Metric name for an insights panel (mutually exclusive with --sql and --event)')
+    .option('--alias <alias>', 'Alias for the insights query')
+    .option('--source-name <name>', 'Source name for the insights query')
+    .option(
+      '--filter <selector>',
+      'Event filter or metric label selector like field:value or amount>0',
+      collectOption,
+      []
+    )
+    .option('--group-by <field>', 'Group by event property or metric label', collectOption, [])
+    .option('--aggr <aggregation>', 'Event: total|unique|AAU|DAU|WAU|MAU. Metric: avg|sum|min|max|count')
+    .option('--func <function>', 'Function like topk(1), bottomk(1)', collectOption, [])
+    .addHelpText(
+      'after',
+      `
+
+Data source: use exactly one of --sql, --event, or --metric.
+
+SQL panel examples:
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Top Holders" --type TABLE \\
+      --sql "SELECT * FROM CoinBalance ORDER BY balance DESC LIMIT 50"
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Daily Volume" --type LINE \\
+      --sql "SELECT toStartOfDay(timestamp) as date, sum(amount) as volume FROM Transfer GROUP BY date ORDER BY date"
+
+Event insights panel examples:
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Transfer Count" --type LINE \\
+      --event Transfer --aggr total
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Large Transfers" --type TABLE \\
+      --event Transfer --filter amount>1000 --aggr total --group-by meta.address
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Top 5 Senders" --type BAR \\
+      --event Transfer --aggr unique --group-by from --func 'topk(5)'
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "DAU" --type LINE \\
+      --event Transfer --aggr DAU
+
+Metric insights panel examples:
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "ETH Price" --type LINE \\
+      --metric cbETH_price
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Avg Burn by Chain" --type BAR \\
+      --metric burn --filter meta.chain=1 --aggr avg --group-by meta.address
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Burn Rate Delta" --type LINE \\
+      --metric burn --aggr sum 
+`
+    )
+    .action(async (dashboardId, options, command) => {
+      try {
+        await runDashboardAddPanel(dashboardId, options)
+      } catch (error) {
+        handleDashboardCommandError(error, command)
+      }
+    })
+}
+
+async function runDashboardList(options: DashboardOptions) {
+  const context = createApiContext(options)
+  const project = await resolveProjectRef(options, context, { ownerSlug: true })
+  const response = await WebService.listDashboards2({
+    path: { owner: project.owner, slug: project.slug },
+    headers: context.headers
+  })
+  const data = unwrapApiResult(response)
+  printOutput(options, data)
+}
+
+async function runDashboardExport(dashboardId: string, options: DashboardOptions) {
+  const context = createApiContext(options)
+  const response = await WebService.exportDashboard({
+    path: { dashboardId },
+    headers: context.headers
+  })
+  const data = unwrapApiResult(response)
+  // Export always outputs JSON regardless of --yaml flag, since the exported data is meant to be re-imported
+  console.log(JSON.stringify(data.dashboardJson ?? data, null, 2))
+}
+
+async function runDashboardImport(dashboardId: string, options: DashboardImportOptions) {
+  const context = createApiContext(options)
+  const input = loadJsonInput(options)
+  if (!input) {
+    throw new CliError('Provide --file or --stdin with the dashboard JSON to import.')
+  }
+
+  const dashboardJson = typeof input === 'object' ? (input as Record<string, unknown>) : {}
+
+  const response = await WebService.importDashboard({
+    body: {
+      dashboardId,
+      dashboardJson,
+      overrideLayouts: options.overrideLayouts
+    },
+    headers: context.headers
+  })
+  const data = unwrapApiResult(response)
+  printOutput(options, { message: `Dashboard imported into ${dashboardId}`, dashboard: data.dashboard })
+}
+
+async function runDashboardAddPanel(dashboardId: string, options: AddPanelOptions) {
+  const context = createApiContext(options)
+
+  // Validate: exactly one data source
+  const selectedSources = [Boolean(options.sql), Boolean(options.event), Boolean(options.metric)].filter(Boolean).length
+  if (selectedSources === 0) {
+    throw new CliError('Provide exactly one data source: --sql, --event, or --metric.')
+  }
+  if (selectedSources > 1) {
+    throw new CliError('Use exactly one of --sql, --event, or --metric.')
+  }
+
+  // 1. Fetch current dashboard to determine layout positions
+  const getResponse = await WebService.getDashboard({
+    path: { dashboardId },
+    headers: context.headers
+  })
+  const dashboardData = unwrapApiResult(getResponse)
+  const dashboard = dashboardData.dashboards?.[0]
+  if (!dashboard) {
+    throw new CliError(`Dashboard ${dashboardId} not found.`)
+  }
+
+  // 2. Build the new panel chart
+  const chartType = normalizeChartType(options.type!)
+  const panelId = generatePanelId()
+  const chart = buildPanelChart(chartType, options)
+
+  const newPanel = {
+    id: panelId,
+    name: options.panelName,
+    dashboardId,
+    chart
+  }
+
+  // 3. Compute layout position: place below all existing panels
+  const existingLayouts = dashboard.layouts?.responsiveLayouts?.lg?.layouts ?? []
+  let maxBottom = 0
+  for (const layout of existingLayouts) {
+    const bottom = (layout.y ?? 0) + (layout.h ?? 0)
+    if (bottom > maxBottom) {
+      maxBottom = bottom
+    }
+  }
+
+  const newLayout = {
+    i: panelId,
+    x: 0,
+    y: maxBottom,
+    w: 12,
+    h: 6
+  }
+
+  // 4. Build updated dashboard JSON and import it
+  const panels = { ...(dashboard.panels ?? {}) }
+  panels[panelId] = newPanel as never
+
+  const updatedLayouts = [...existingLayouts, newLayout]
+
+  const dashboardJson: Record<string, unknown> = {
+    ...dashboard,
+    panels,
+    layouts: {
+      responsiveLayouts: {
+        ...(dashboard.layouts?.responsiveLayouts ?? {}),
+        lg: { layouts: updatedLayouts }
+      }
+    }
+  }
+
+  const importResponse = await WebService.importDashboard({
+    body: {
+      dashboardId,
+      dashboardJson,
+      overrideLayouts: true
+    },
+    headers: context.headers
+  })
+  const importData = unwrapApiResult(importResponse)
+  printOutput(options, {
+    message: `Panel "${options.panelName}" added to dashboard ${dashboardId}`,
+    panelId,
+    dashboard: importData.dashboard
+  })
+}
+
+function buildPanelChart(chartType: string, options: AddPanelOptions) {
+  if (options.sql) {
+    const sqlSize = Number.parseInt(String(options.size ?? '100'), 10) || 100
+    return {
+      type: chartType,
+      datasourceType: 'SQL' as const,
+      sqlQuery: JSON.stringify({ sql: options.sql, size: sqlSize })
+    }
+  }
+
+  if (options.event) {
+    const queryBody = buildEventsInsightQueryBody(options.event, {
+      alias: options.alias,
+      sourceName: options.sourceName,
+      filter: options.filter,
+      groupBy: options.groupBy,
+      aggr: options.aggr,
+      func: options.func
+    })
+    return {
+      type: chartType,
+      datasourceType: 'INSIGHTS' as const,
+      insightsQueries: queryBody.queries
+    }
+  }
+
+  if (options.metric) {
+    const queryBody = buildMetricsInsightQueryBody(options.metric, {
+      alias: options.alias,
+      sourceName: options.sourceName,
+      filter: options.filter,
+      groupBy: options.groupBy,
+      aggr: options.aggr,
+      func: options.func
+    })
+    return {
+      type: chartType,
+      datasourceType: 'INSIGHTS' as const,
+      insightsQueries: queryBody.queries
+    }
+  }
+
+  throw new CliError('Provide exactly one data source: --sql, --event, or --metric.')
+}
+
+function normalizeChartType(value: string) {
+  const normalized = value.toUpperCase()
+  const valid = ['LINE', 'AREA', 'BAR', 'BAR_GAUGE', 'TABLE', 'QUERY_VALUE', 'PIE', 'NOTE', 'SCATTER']
+  if (valid.includes(normalized)) {
+    return normalized
+  }
+  throw new CliError(`Invalid chart type "${value}". Use one of: ${valid.join(', ')}`)
+}
+
+function generatePanelId() {
+  return `panel_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+}
+
+function collectOption(value: string, previous: string[] = []) {
+  previous.push(value)
+  return previous
+}
+
+function withAuthOptions<T extends Command<any, any, any>>(command: T) {
+  return command
+    .option('--host <host>', 'Override Sentio host')
+    .option('--api-key <key>', 'Use an explicit API key instead of saved credentials')
+    .option('--token <token>', 'Use an explicit bearer token instead of saved credentials')
+}
+
+function withSharedProjectOptions<T extends Command<any, any, any>>(command: T) {
+  return command
+    .option('--project <project>', 'Sentio project as <owner>/<slug> or <slug>')
+    .option('--owner <owner>', 'Sentio project owner')
+    .option('--name <name>', 'Sentio project name')
+    .option('--project-id <id>', 'Sentio project id')
+}
+
+function withOutputOptions<T extends Command<any, any, any>>(command: T) {
+  return command.option('--json', 'Print raw JSON response').option('--yaml', 'Print raw YAML response')
+}
+
+function handleDashboardCommandError(error: unknown, command?: Command) {
+  if (
+    error instanceof CliError &&
+    (error.message.startsWith('Project is required.') ||
+      error.message.startsWith('Invalid project ') ||
+      error.message.startsWith('Dashboard ') ||
+      error.message.startsWith('Provide --file or --stdin') ||
+      error.message.startsWith('Provide exactly one data source') ||
+      error.message.startsWith('Use exactly one of --sql') ||
+      error.message.startsWith('Invalid chart type') ||
+      error.message.startsWith('Invalid aggregation') ||
+      error.message.startsWith('Invalid metric aggregation') ||
+      error.message.startsWith('Invalid filter') ||
+      error.message.startsWith('Invalid metric selector'))
+  ) {
+    console.error(error.message)
+    if (command) {
+      console.error()
+      command.outputHelp()
+    }
+    process.exit(1)
+  }
+  handleCommandError(error)
+}
+
+function printOutput(options: DashboardOptions, data: unknown) {
+  if (options.json && options.yaml) {
+    throw new CliError('Choose only one structured output format: --json or --yaml.')
+  }
+  if (options.json) {
+    console.log(JSON.stringify(data, null, 2))
+    return
+  }
+  if (options.yaml) {
+    console.log(yaml.stringify(data).trimEnd())
+    return
+  }
+  console.log(formatOutput(data))
+}
+
+function formatOutput(data: unknown) {
+  if (data && typeof data === 'object' && 'message' in (data as Record<string, unknown>)) {
+    return String((data as { message?: string }).message ?? '')
+  }
+
+  if (data && typeof data === 'object' && 'dashboards' in (data as Record<string, unknown>)) {
+    const dashboards = ((data as { dashboards?: unknown[] }).dashboards ?? []) as Array<Record<string, unknown>>
+    const lines = [`Dashboards (${dashboards.length})`]
+    for (const db of dashboards) {
+      const id = db.id ?? '<id>'
+      const name = db.name ?? '<unnamed>'
+      const panelCount = db.panels ? Object.keys(db.panels as Record<string, unknown>).length : 0
+      const visibility = db.visibility ?? ''
+      const updated = formatTimestamp(db.updatedAt as string | undefined)
+      lines.push(
+        `- ${id} "${name}" [${panelCount} panels]${visibility ? ` ${visibility}` : ''}${updated ? ` updated ${updated}` : ''}`
+      )
+    }
+    return lines.join('\n')
+  }
+
+  return JSON.stringify(data, null, 2)
+}
+
+function formatTimestamp(value?: string) {
+  if (!value) {
+    return ''
+  }
+  if (/^\d{13}$/.test(value)) {
+    return new Date(Number.parseInt(value, 10)).toISOString()
+  }
+  return value
+}

package/src/index.ts

@@ -18,6 +18,7 @@ import { createAlertCommand } from './commands/alert.js'
 import { createPriceCommand } from './commands/price.js'
 import { createSimulationCommand } from './commands/simulation.js'
 import { createEndpointCommand } from './commands/endpoint.js'
+import { createDashboardCommand } from './commands/dashboard.js'
 import { enableApiDebug } from './api.js'
 import { printVersions } from './utils.js'
 
@@ -50,5 +51,6 @@ program.addCommand(createAlertCommand())
 program.addCommand(createPriceCommand())
 program.addCommand(createSimulationCommand())
 program.addCommand(createEndpointCommand())
+program.addCommand(createDashboardCommand())
 
 program.parse()