@sentio/cli 3.6.0-rc.2 → 3.6.0-rc.4

package/lib/index.js

@@ -141137,6 +141137,59 @@ function formatDebugBody(body) {
 
 // src/commands/data.ts
 var DEFAULT_RANGE_STEP = 3600;
+var VALID_METRIC_FUNCTIONS = /* @__PURE__ */ new Set([
+  // Math
+  "abs",
+  "ceil",
+  "floor",
+  "round",
+  "log2",
+  "log10",
+  "ln",
+  // Rollup
+  "rollup_avg",
+  "rollup_count",
+  "rollup_last",
+  "rollup_max",
+  "rollup_min",
+  "rollup_sum",
+  "rollup_delta",
+  // Aggregate Over Time
+  "avg_over_time",
+  "count_over_time",
+  "last_over_time",
+  "max_over_time",
+  "min_over_time",
+  "sum_over_time",
+  "delta_over_time",
+  // Rate
+  "rate",
+  "irate",
+  "delta",
+  "moving_delta",
+  // Rank
+  "topk",
+  "bottomk",
+  // Time
+  "timestamp",
+  "day_of_year",
+  "day_of_month",
+  "day_of_week",
+  "year",
+  "month",
+  "hour",
+  "minute",
+  // TimeShift
+  "before",
+  "after"
+]);
+var VALID_EVENT_FUNCTIONS = /* @__PURE__ */ new Set([
+  // Rank
+  "topk",
+  "bottomk",
+  // Delta
+  "delta"
+]);
 function createDataCommand() {
   const dataCommand = new Command("data").description("Retrieve data from Sentio");
   dataCommand.addCommand(createDataQueryCommand());
@@ -141173,7 +141226,7 @@ function buildEventsInsightQueryBody(search, options) {
           aggregation: buildEventAggregation(options.aggr),
           selectorExpr: buildSelectorExpr(options.filter),
           groupBy: normalizeListOption(options.groupBy),
-          functions: buildFunctions(options.func),
+          functions: buildFunctions(options.func, VALID_EVENT_FUNCTIONS),
           disabled: false
         }
       }
@@ -141197,7 +141250,7 @@ function buildMetricsInsightQueryBody(query, options) {
           query,
           labelSelector: buildMetricLabelSelector(options.filter),
           aggregate: buildMetricAggregate(options.aggr, options.groupBy),
-          functions: buildFunctions(options.func),
+          functions: buildFunctions(options.func, VALID_METRIC_FUNCTIONS),
           disabled: false
         }
       }
@@ -141504,7 +141557,7 @@ function handleDataCommandError(error, command) {
 function shouldShowHelpForDataCommandError(error) {
   return error.message.startsWith("Project is required.") || error.message.startsWith(
     "Provide --file, --stdin, or exactly one of --event, --metric, or --price for data query"
-  ) || error.message.startsWith("Use exactly one of --event, --metric, or --price for data query.") || error.message.startsWith("Price queries only support --price") || error.message.startsWith("Provide --query, --result, --file, or --stdin.") || error.message.startsWith("Use only one of --query or --result.") || error.message.startsWith("--async only works with --query.") || error.message.startsWith("Execution id is required.");
+  ) || error.message.startsWith("Use exactly one of --event, --metric, or --price for data query.") || error.message.startsWith("Price queries only support --price") || error.message.startsWith("Provide --query, --result, --file, or --stdin.") || error.message.startsWith("Use only one of --query or --result.") || error.message.startsWith("--async only works with --query.") || error.message.startsWith("Execution id is required.") || error.message.startsWith('Unknown function "');
 }
 function buildEventAggregation(aggregationName = "total") {
   switch (aggregationName.toUpperCase()) {
@@ -141633,8 +141686,14 @@ function parseAnyValue(rawValue) {
   }
   return { stringValue: unquotedValue };
 }
-function buildFunctions(functions) {
-  return normalizeListOption(functions).map(parseFunctionCall);
+function buildFunctions(functions, validNames) {
+  return normalizeListOption(functions).map((f14) => {
+    const parsed = parseFunctionCall(f14);
+    if (validNames && !validNames.has(parsed.name)) {
+      throw new CliError(`Unknown function "${parsed.name}". Valid functions: ${[...validNames].sort().join(", ")}.`);
+    }
+    return parsed;
+  });
 }
 function parseFunctionCall(value) {
   const trimmed = value.trim();
@@ -142476,7 +142535,11 @@ function createProcessorCommand() {
 function createProcessorStatusCommand() {
   return withOutputOptions3(
     withSharedProjectOptions3(withAuthOptions3(new Command("status").description("Get processor status")))
-  ).showHelpAfterError().option("--version <selector>", "Version selector: active, pending, or all").action(async (options, command) => {
+  ).showHelpAfterError().option(
+    "--version <selector>",
+    "Version selector: active, pending, all, or a numeric version number",
+    parseVersionSelector
+  ).action(async (options, command) => {
     try {
       await runProcessorStatus(options);
     } catch (error) {
@@ -142556,22 +142619,19 @@ async function runProcessorStatus(options) {
   const context = createApiContext(options);
   const project = await resolveProjectRef(options, context, { ownerSlug: true });
   const requestedVersion = normalizeVersionSelector(options.version);
+  const apiVersion = typeof requestedVersion === "number" ? "ALL" : requestedVersion ?? "ALL";
   const response = await import_api5.ProcessorService.getProcessorStatusV2({
     path: {
       owner: project.owner,
       slug: project.slug
     },
     query: {
-      version: requestedVersion ?? "ALL"
+      version: apiVersion
     },
     headers: context.headers
   });
   const data4 = unwrapApiResult(response);
-  if (!options.json) {
-    printOutput3(options, shapeProcessorStatusOutput(data4, requestedVersion));
-    return;
-  }
-  printOutput3(options, data4);
+  printOutput3(options, shapeProcessorStatusOutput(data4, requestedVersion));
 }
 async function runProcessorSource(options) {
   const context = createApiContext(options);
@@ -142810,7 +142870,7 @@ function withOutputOptions3(command) {
   return command.option("--json", "Print raw JSON response").option("--yaml", "Print raw YAML response");
 }
 function handleProcessorCommandError(error, command) {
-  if (error instanceof CliError && (error.message.startsWith("Project is required.") || error.message.startsWith("Invalid project ") || error.message.startsWith("Invalid version selector ") || error.message.startsWith("Source file not found:"))) {
+  if (error instanceof CliError && (error.message.startsWith("Project is required.") || error.message.startsWith("Invalid project ") || error.message.startsWith("Invalid version selector") || error.message.startsWith("Source file not found:"))) {
     console.error(error.message);
     if (command) {
       console.error();
@@ -142904,14 +142964,24 @@ function formatOutput2(data4) {
   return JSON.stringify(data4, null, 2);
 }
 function normalizeVersionSelector(value) {
-  if (!value) {
+  if (value === void 0) {
     return void 0;
   }
+  if (typeof value === "number") {
+    return value;
+  }
   const normalized = value.toUpperCase();
   if (normalized === "ACTIVE" || normalized === "PENDING" || normalized === "ALL") {
     return normalized;
   }
-  throw new CliError(`Invalid version selector "${value}". Use active, pending, or all.`);
+  throw new CliError(`Invalid version selector "${value}". Use active, pending, all, or a version number.`);
+}
+function parseVersionSelector(value) {
+  const num = Number.parseInt(value, 10);
+  if (!Number.isNaN(num) && String(num) === value) {
+    return num;
+  }
+  return value;
 }
 function parseInteger2(value) {
   const parsedValue = Number.parseInt(value, 10);
@@ -142937,6 +143007,12 @@ function shapeProcessorStatusOutput(data4, versionSelector) {
       processors: processors.filter((processor) => asString3(processor.versionState) === versionSelector)
     };
   }
+  if (typeof versionSelector === "number") {
+    return {
+      ...data4,
+      processors: processors.filter((processor) => asNumber(processor.version) === versionSelector)
+    };
+  }
   return {
     ...data4,
     processors: processors.filter((processor) => {
@@ -143006,7 +143082,10 @@ function createAlertGetCommand() {
 function createAlertCreateCommand() {
   return withOutputOptions4(
     withSharedProjectOptions4(withAuthOptions4(new Command("create").description("Create an alert rule")))
-  ).showHelpAfterError().option("--file <path>", "Read request JSON or YAML from file. Use --doc to show the full alert request format").option("--stdin", "Read request JSON or YAML from stdin. Use --doc to show the full alert request format").option("--doc", "Print the full alert request file format and exit").option("--type <type>", "Alert type: METRIC, LOG, or SQL").option("--subject <text>", "Alert subject/title").option("--message <text>", "Optional alert message template").option("--query <text>", "Inline log query or SQL when not using --file/--stdin").option("--event <name>", "Inline event query for METRIC alerts").option("--metric <name>", "Inline metric query for METRIC alerts").option("--alias <alias>", "Alias for the inline METRIC query").option("--source-name <name>", "Optional source name for the inline METRIC query").option("--filter <selector>", "Inline METRIC query filter like amount>0 or meta.chain=1", collectOption2, []).option("--group-by <field>", "Inline METRIC query group-by field", collectOption2, []).option(
+  ).showHelpAfterError().option("--file <path>", "Read request JSON or YAML from file. Use --doc to show the full alert request format").option("--stdin", "Read request JSON or YAML from stdin. Use --doc to show the full alert request format").option("--doc", "Print the full alert request file format and exit").option("--type <type>", "Alert type: METRIC, LOG, or SQL").option("--subject <text>", "Alert subject/title").option("--message <text>", "Optional alert message template").option(
+    "--query <text>",
+    "Inline query. LOG: Elasticsearch query-string syntax (e.g. amount:>1000, status:error). SQL: full SQL statement."
+  ).option("--event <name>", "Inline event query for METRIC alerts").option("--metric <name>", "Inline metric query for METRIC alerts").option("--alias <alias>", "Alias for the inline METRIC query").option("--source-name <name>", "Optional source name for the inline METRIC query").option("--filter <selector>", "Inline METRIC query filter like amount>0 or meta.chain=1", collectOption2, []).option("--group-by <field>", "Inline METRIC query group-by field", collectOption2, []).option(
     "--aggr <aggregation>",
     "Inline aggregation. METRIC: avg|sum|min|max|count. EVENTS: total|unique|AAU|DAU|WAU|MAU"
   ).option("--func <function>", "Inline function like topk(1), bottomk(1), delta(1m)", collectOption2, []).option("--op <operator>", "Condition operator like >, >=, ==, !=, <, <=, between").option("--threshold <value>", "Condition threshold", parseNumber).option("--threshold2 <value>", "Second threshold for between", parseNumber).option("--for <duration>", "Evaluate over the last duration, for example 5m or 1h").option("--interval <duration>", "Alert evaluation interval, for example 1m or 5m").option("--time-column <column>", "SQL alert time column for column-based conditions").option("--value-column <column>", "SQL alert value column for column-based conditions").option("--sql-aggr <aggregation>", "SQL aggregation: COUNT, SUM, AVG, MAX, MIN, LAST").addHelpText(
@@ -143014,7 +143093,7 @@ function createAlertCreateCommand() {
     `
 
 Examples:
-  $ sentio alert create --project sentio/coinbase --type LOG --subject "Large transfer logs" --query 'amount > 1000' --op '>' --threshold 0
+  $ sentio alert create --project sentio/coinbase --type LOG --subject "Large transfer logs" --query 'amount:>1000' --op '>' --threshold 0
   $ sentio alert create --project sentio/coinbase --type SQL --subject "Large transfer(SQL demo)" --query 'select timestamp, amount from transfer where amount > 1000' --time-column timestamp --value-column amount --sql-aggr MAX --op '>' --threshold 1000
   $ sentio alert create --project sentio/coinbase --type METRIC --subject "Burn spike" --metric burn --filter meta.chain=1 --aggr avg --group-by meta.address --op '>' --threshold 100
   $ sentio alert create --project sentio/coinbase --type METRIC --subject "Transfer anomaly" --event Transfer --filter amount>0 --aggr total --func 'delta(1m)' --op '>' --threshold 100
@@ -143637,11 +143716,14 @@ Metric alert example:
             disabled: false
 
 Log alert example:
+  NOTE: logCondition.query uses Elasticsearch query-string syntax.
+  Ranges MUST use field:>value form \u2014 C-style "field > value" is rejected at evaluation time.
+  Examples: amount:>1000000  timestamp:>=2024-01-01  amount:[1000 TO 9999]  status:error
   rule:
     alertType: LOG
     subject: large transfer logs
     logCondition:
-      query: amount > 1000
+      query: amount:>1000
       comparisonOp: ">"
       threshold: 0
 
@@ -144874,7 +144956,13 @@ function createDashboardAddPanelCommand() {
     "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(
+  ).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, []).option(
+    "--time-range-start <value>",
+    "Panel time range start: relative (e.g. -24h, -7d, -30m) or ISO date (e.g. 2024-01-01T00:00:00Z)"
+  ).option(
+    "--time-range-end <value>",
+    "Panel time range end: relative (e.g. now, -1h) or ISO date. Defaults to now when --time-range-start is set."
+  ).option("--time-range-step <seconds>", "Panel time range step in seconds (e.g. 3600)").addHelpText(
     "after",
     `
 
@@ -144911,7 +144999,17 @@ Metric insights panel examples:
       --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 
+      --metric burn --aggr sum
+
+Panel time range override examples:
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Last 24h Transfers" --type LINE \\
+      --event Transfer --aggr total \\
+      --time-range-start -24h --time-range-end now --time-range-step 3600
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Jan 2024 Volume" --type BAR \\
+      --sql "SELECT date, sum(amount) FROM Transfer GROUP BY date" \\
+      --time-range-start 2024-01-01T00:00:00Z --time-range-end 2024-02-01T00:00:00Z
 `
   ).action(async (dashboardId, options, command) => {
     try {
@@ -144979,14 +145077,18 @@ function buildDashboardCreateBody(options, project) {
   };
 }
 function normalizeDashboardInit(input) {
+  const emptyLayouts = {
+    responsiveLayouts: {
+      lg: { layouts: [] },
+      md: { layouts: [] },
+      sm: { layouts: [] },
+      xs: { layouts: [] }
+    }
+  };
   if (input === void 0) {
     return {
       panels: {},
-      layouts: {
-        responsiveLayouts: {
-          lg: { layouts: [] }
-        }
-      }
+      layouts: emptyLayouts
     };
   }
   if (!input || typeof input !== "object" || Array.isArray(input)) {
@@ -144995,11 +145097,7 @@ function normalizeDashboardInit(input) {
   const dashboard = input;
   return {
     panels: isRecord(dashboard.panels) ? dashboard.panels : {},
-    layouts: isRecord(dashboard.layouts) ? dashboard.layouts : {
-      responsiveLayouts: {
-        lg: { layouts: [] }
-      }
-    }
+    layouts: isRecord(dashboard.layouts) ? dashboard.layouts : emptyLayouts
   };
 }
 async function runDashboardAddPanel(dashboardId, options) {
@@ -145023,11 +145121,13 @@ async function runDashboardAddPanel(dashboardId, options) {
   const chartType = normalizeChartType(options.type);
   const panelId = generatePanelId();
   const chart = buildPanelChart(chartType, options);
+  const timeRangeOverride = buildTimeRangeOverride(options);
   const newPanel = {
     id: panelId,
     name: options.panelName,
     dashboardId,
-    chart
+    chart,
+    ...timeRangeOverride ? { timeRangeOverride } : {}
   };
   const existingLayouts = dashboard.layouts?.responsiveLayouts?.lg?.layouts ?? [];
   let maxBottom = 0;
@@ -145046,15 +145146,17 @@ async function runDashboardAddPanel(dashboardId, options) {
   };
   const panels = { ...dashboard.panels ?? {} };
   panels[panelId] = newPanel;
-  const updatedLayouts = [...existingLayouts, newLayout];
+  const existingResponsive = dashboard.layouts?.responsiveLayouts ?? {};
+  const updatedResponsive = { ...existingResponsive };
+  for (const bp2 of ["lg", "md", "sm", "xs"]) {
+    const existing = existingResponsive[bp2]?.layouts ?? [];
+    updatedResponsive[bp2] = { layouts: [...existing, newLayout] };
+  }
   const dashboardJson = {
     ...dashboard,
     panels,
     layouts: {
-      responsiveLayouts: {
-        ...dashboard.layouts?.responsiveLayouts ?? {},
-        lg: { layouts: updatedLayouts }
-      }
+      responsiveLayouts: updatedResponsive
     }
   };
   const importResponse = await import_api14.WebService.importDashboard({
@@ -145072,6 +145174,40 @@ async function runDashboardAddPanel(dashboardId, options) {
     dashboard: importData.dashboard
   });
 }
+function buildTimeRangeLike(value) {
+  const relMatch = value.match(/^(-?\d+)\s*([smhdwMy])$/);
+  if (relMatch) {
+    return { relativeTime: { unit: relMatch[2], value: Number(relMatch[1]) } };
+  }
+  if (value === "now" || value === "0") {
+    return { relativeTime: { unit: "h", value: 0 } };
+  }
+  const ts2 = Date.parse(value);
+  if (!Number.isNaN(ts2)) {
+    return { absoluteTime: String(ts2) };
+  }
+  throw new CliError(
+    `Invalid time range value "${value}". Use a relative offset (e.g. -24h, -7d, -30m, now) or an ISO date string.`
+  );
+}
+function buildTimeRangeOverride(options) {
+  if (!options.timeRangeStart && !options.timeRangeEnd) {
+    return void 0;
+  }
+  const timeRange = {};
+  if (options.timeRangeStart) {
+    timeRange.start = buildTimeRangeLike(options.timeRangeStart);
+  }
+  if (options.timeRangeEnd) {
+    timeRange.end = buildTimeRangeLike(options.timeRangeEnd);
+  } else {
+    timeRange.end = { relativeTime: { unit: "h", value: 0 } };
+  }
+  if (options.timeRangeStep) {
+    timeRange.step = options.timeRangeStep;
+  }
+  return { enabled: true, timeRange };
+}
 function buildPanelChart(chartType, options) {
   if (options.sql) {
     const sqlSize = Number.parseInt(String(options.size ?? "100"), 10) || 100;
@@ -145141,7 +145277,7 @@ 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("Use either --file or --stdin") || error.message.startsWith("Expected JSON or YAML") || error.message.startsWith("Invalid JSON or YAML") || error.message.startsWith("Dashboard initialization data") || 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"))) {
+  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("Use either --file or --stdin") || error.message.startsWith("Expected JSON or YAML") || error.message.startsWith("Invalid JSON or YAML") || error.message.startsWith("Dashboard initialization data") || 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") || error.message.startsWith("Invalid time range value") || error.message.startsWith('Unknown function "'))) {
     console.error(error.message);
     if (command) {
       console.error();
@@ -145239,6 +145375,10 @@ await printVersions();
 if (process.argv.includes("--debug")) {
   enableApiDebug();
 }
+if (process.argv.length === 3 && process.argv[2] === "--version") {
+  version();
+  process.exit(0);
+}
 program2.addCommand(createLoginCommand());
 program2.addCommand(createCreateCommand());
 program2.addCommand(createVersionCommand());

package/package.json

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

package/src/commands/alert.ts

@@ -136,7 +136,10 @@ function createAlertCreateCommand() {
     .option('--type <type>', 'Alert type: METRIC, LOG, or SQL')
     .option('--subject <text>', 'Alert subject/title')
     .option('--message <text>', 'Optional alert message template')
-    .option('--query <text>', 'Inline log query or SQL when not using --file/--stdin')
+    .option(
+      '--query <text>',
+      'Inline query. LOG: Elasticsearch query-string syntax (e.g. amount:>1000, status:error). SQL: full SQL statement.'
+    )
     .option('--event <name>', 'Inline event query for METRIC alerts')
     .option('--metric <name>', 'Inline metric query for METRIC alerts')
     .option('--alias <alias>', 'Alias for the inline METRIC query')
@@ -161,7 +164,7 @@ function createAlertCreateCommand() {
       `
 
 Examples:
-  $ sentio alert create --project sentio/coinbase --type LOG --subject "Large transfer logs" --query 'amount > 1000' --op '>' --threshold 0
+  $ sentio alert create --project sentio/coinbase --type LOG --subject "Large transfer logs" --query 'amount:>1000' --op '>' --threshold 0
   $ sentio alert create --project sentio/coinbase --type SQL --subject "Large transfer(SQL demo)" --query 'select timestamp, amount from transfer where amount > 1000' --time-column timestamp --value-column amount --sql-aggr MAX --op '>' --threshold 1000
   $ sentio alert create --project sentio/coinbase --type METRIC --subject "Burn spike" --metric burn --filter meta.chain=1 --aggr avg --group-by meta.address --op '>' --threshold 100
   $ sentio alert create --project sentio/coinbase --type METRIC --subject "Transfer anomaly" --event Transfer --filter amount>0 --aggr total --func 'delta(1m)' --op '>' --threshold 100
@@ -916,11 +919,14 @@ Metric alert example:
             disabled: false
 
 Log alert example:
+  NOTE: logCondition.query uses Elasticsearch query-string syntax.
+  Ranges MUST use field:>value form — C-style "field > value" is rejected at evaluation time.
+  Examples: amount:>1000000  timestamp:>=2024-01-01  amount:[1000 TO 9999]  status:error
   rule:
     alertType: LOG
     subject: large transfer logs
     logCondition:
-      query: amount > 1000
+      query: amount:>1000
       comparisonOp: ">"
       threshold: 0
 

package/src/commands/dashboard.ts

@@ -50,6 +50,9 @@ interface AddPanelOptions extends DashboardOptions {
   groupBy?: string[]
   aggr?: string
   func?: string[]
+  timeRangeStart?: string
+  timeRangeEnd?: string
+  timeRangeStep?: string
 }
 
 export function createDashboardCommand() {
@@ -162,6 +165,15 @@ function createDashboardAddPanelCommand() {
     .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, [])
+    .option(
+      '--time-range-start <value>',
+      'Panel time range start: relative (e.g. -24h, -7d, -30m) or ISO date (e.g. 2024-01-01T00:00:00Z)'
+    )
+    .option(
+      '--time-range-end <value>',
+      'Panel time range end: relative (e.g. now, -1h) or ISO date. Defaults to now when --time-range-start is set.'
+    )
+    .option('--time-range-step <seconds>', 'Panel time range step in seconds (e.g. 3600)')
     .addHelpText(
       'after',
       `
@@ -199,7 +211,17 @@ Metric insights panel examples:
       --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 
+      --metric burn --aggr sum
+
+Panel time range override examples:
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Last 24h Transfers" --type LINE \\
+      --event Transfer --aggr total \\
+      --time-range-start -24h --time-range-end now --time-range-step 3600
+  $ sentio dashboard add-panel abc123 --project owner/slug \\
+      --panel-name "Jan 2024 Volume" --type BAR \\
+      --sql "SELECT date, sum(amount) FROM Transfer GROUP BY date" \\
+      --time-range-start 2024-01-01T00:00:00Z --time-range-end 2024-02-01T00:00:00Z
 `
     )
     .action(async (dashboardId, options, command) => {
@@ -279,14 +301,19 @@ function buildDashboardCreateBody(options: DashboardCreateOptions, project: { ow
 }
 
 function normalizeDashboardInit(input: unknown) {
+  const emptyLayouts = {
+    responsiveLayouts: {
+      lg: { layouts: [] },
+      md: { layouts: [] },
+      sm: { layouts: [] },
+      xs: { layouts: [] }
+    }
+  }
+
   if (input === undefined) {
     return {
       panels: {},
-      layouts: {
-        responsiveLayouts: {
-          lg: { layouts: [] }
-        }
-      }
+      layouts: emptyLayouts
     }
   }
 
@@ -297,13 +324,7 @@ function normalizeDashboardInit(input: unknown) {
   const dashboard = input as Record<string, unknown>
   return {
     panels: isRecord(dashboard.panels) ? dashboard.panels : {},
-    layouts: isRecord(dashboard.layouts)
-      ? dashboard.layouts
-      : {
-          responsiveLayouts: {
-            lg: { layouts: [] }
-          }
-        }
+    layouts: isRecord(dashboard.layouts) ? dashboard.layouts : emptyLayouts
   }
 }
 
@@ -335,11 +356,13 @@ async function runDashboardAddPanel(dashboardId: string, options: AddPanelOption
   const panelId = generatePanelId()
   const chart = buildPanelChart(chartType, options)
 
-  const newPanel = {
+  const timeRangeOverride = buildTimeRangeOverride(options)
+  const newPanel: Record<string, unknown> = {
     id: panelId,
     name: options.panelName,
     dashboardId,
-    chart
+    chart,
+    ...(timeRangeOverride ? { timeRangeOverride } : {})
   }
 
   // 3. Compute layout position: place below all existing panels
@@ -364,16 +387,18 @@ async function runDashboardAddPanel(dashboardId: string, options: AddPanelOption
   const panels = { ...(dashboard.panels ?? {}) }
   panels[panelId] = newPanel as never
 
-  const updatedLayouts = [...existingLayouts, newLayout]
+  const existingResponsive = dashboard.layouts?.responsiveLayouts ?? {}
+  const updatedResponsive: Record<string, unknown> = { ...existingResponsive }
+  for (const bp of ['lg', 'md', 'sm', 'xs'] as const) {
+    const existing = (existingResponsive as Record<string, { layouts?: unknown[] } | undefined>)[bp]?.layouts ?? []
+    updatedResponsive[bp] = { layouts: [...existing, newLayout] }
+  }
 
   const dashboardJson: Record<string, unknown> = {
     ...dashboard,
     panels,
     layouts: {
-      responsiveLayouts: {
-        ...(dashboard.layouts?.responsiveLayouts ?? {}),
-        lg: { layouts: updatedLayouts }
-      }
+      responsiveLayouts: updatedResponsive
     }
   }
 
@@ -393,6 +418,43 @@ async function runDashboardAddPanel(dashboardId: string, options: AddPanelOption
   })
 }
 
+function buildTimeRangeLike(value: string): Record<string, unknown> {
+  const relMatch = value.match(/^(-?\d+)\s*([smhdwMy])$/)
+  if (relMatch) {
+    return { relativeTime: { unit: relMatch[2], value: Number(relMatch[1]) } }
+  }
+  if (value === 'now' || value === '0') {
+    return { relativeTime: { unit: 'h', value: 0 } }
+  }
+  const ts = Date.parse(value)
+  if (!Number.isNaN(ts)) {
+    return { absoluteTime: String(ts) }
+  }
+  throw new CliError(
+    `Invalid time range value "${value}". Use a relative offset (e.g. -24h, -7d, -30m, now) or an ISO date string.`
+  )
+}
+
+function buildTimeRangeOverride(options: AddPanelOptions): Record<string, unknown> | undefined {
+  if (!options.timeRangeStart && !options.timeRangeEnd) {
+    return undefined
+  }
+  const timeRange: Record<string, unknown> = {}
+  if (options.timeRangeStart) {
+    timeRange.start = buildTimeRangeLike(options.timeRangeStart)
+  }
+  if (options.timeRangeEnd) {
+    timeRange.end = buildTimeRangeLike(options.timeRangeEnd)
+  } else {
+    // default end to "now" when start is provided
+    timeRange.end = { relativeTime: { unit: 'h', value: 0 } }
+  }
+  if (options.timeRangeStep) {
+    timeRange.step = options.timeRangeStep
+  }
+  return { enabled: true, timeRange }
+}
+
 function buildPanelChart(chartType: string, options: AddPanelOptions) {
   if (options.sql) {
     const sqlSize = Number.parseInt(String(options.size ?? '100'), 10) || 100
@@ -496,7 +558,9 @@ function handleDashboardCommandError(error: unknown, command?: Command) {
       error.message.startsWith('Invalid aggregation') ||
       error.message.startsWith('Invalid metric aggregation') ||
       error.message.startsWith('Invalid filter') ||
-      error.message.startsWith('Invalid metric selector'))
+      error.message.startsWith('Invalid metric selector') ||
+      error.message.startsWith('Invalid time range value') ||
+      error.message.startsWith('Unknown function "'))
   ) {
     console.error(error.message)
     if (command) {

package/src/commands/data.ts

@@ -16,6 +16,62 @@ import {
 } from '../api.js'
 
 const DEFAULT_RANGE_STEP = 3600
+
+// Valid function names sourced from sentio/app/lib/functions.ts
+const VALID_METRIC_FUNCTIONS: ReadonlySet<string> = new Set([
+  // Math
+  'abs',
+  'ceil',
+  'floor',
+  'round',
+  'log2',
+  'log10',
+  'ln',
+  // Rollup
+  'rollup_avg',
+  'rollup_count',
+  'rollup_last',
+  'rollup_max',
+  'rollup_min',
+  'rollup_sum',
+  'rollup_delta',
+  // Aggregate Over Time
+  'avg_over_time',
+  'count_over_time',
+  'last_over_time',
+  'max_over_time',
+  'min_over_time',
+  'sum_over_time',
+  'delta_over_time',
+  // Rate
+  'rate',
+  'irate',
+  'delta',
+  'moving_delta',
+  // Rank
+  'topk',
+  'bottomk',
+  // Time
+  'timestamp',
+  'day_of_year',
+  'day_of_month',
+  'day_of_week',
+  'year',
+  'month',
+  'hour',
+  'minute',
+  // TimeShift
+  'before',
+  'after'
+])
+
+const VALID_EVENT_FUNCTIONS: ReadonlySet<string> = new Set([
+  // Rank
+  'topk',
+  'bottomk',
+  // Delta
+  'delta'
+])
 interface CommonDataOptions {
   host?: string
   apiKey?: string
@@ -113,7 +169,7 @@ export function buildEventsInsightQueryBody(
           aggregation: buildEventAggregation(options.aggr),
           selectorExpr: buildSelectorExpr(options.filter),
           groupBy: normalizeListOption(options.groupBy),
-          functions: buildFunctions(options.func),
+          functions: buildFunctions(options.func, VALID_EVENT_FUNCTIONS),
           disabled: false
         }
       }
@@ -148,7 +204,7 @@ export function buildMetricsInsightQueryBody(
           query,
           labelSelector: buildMetricLabelSelector(options.filter),
           aggregate: buildMetricAggregate(options.aggr, options.groupBy),
-          functions: buildFunctions(options.func),
+          functions: buildFunctions(options.func, VALID_METRIC_FUNCTIONS),
           disabled: false
         }
       }
@@ -584,7 +640,8 @@ function shouldShowHelpForDataCommandError(error: CliError) {
     error.message.startsWith('Provide --query, --result, --file, or --stdin.') ||
     error.message.startsWith('Use only one of --query or --result.') ||
     error.message.startsWith('--async only works with --query.') ||
-    error.message.startsWith('Execution id is required.')
+    error.message.startsWith('Execution id is required.') ||
+    error.message.startsWith('Unknown function "')
   )
 }
 
@@ -730,8 +787,14 @@ function parseAnyValue(rawValue: string) {
   return { stringValue: unquotedValue }
 }
 
-function buildFunctions(functions?: string[]) {
-  return normalizeListOption(functions).map(parseFunctionCall)
+function buildFunctions(functions?: string[], validNames?: ReadonlySet<string>) {
+  return normalizeListOption(functions).map((f) => {
+    const parsed = parseFunctionCall(f)
+    if (validNames && !validNames.has(parsed.name)) {
+      throw new CliError(`Unknown function "${parsed.name}". Valid functions: ${[...validNames].sort().join(', ')}.`)
+    }
+    return parsed
+  })
 }
 
 function parseFunctionCall(value: string) {

package/src/commands/processor.ts

@@ -27,7 +27,7 @@ interface ProcessorOptions {
 }
 
 interface ProcessorStatusOptions extends ProcessorOptions {
-  version?: string
+  version?: string | number
 }
 
 interface ProcessorSourceOptions extends ProcessorOptions {
@@ -60,7 +60,11 @@ function createProcessorStatusCommand() {
     withSharedProjectOptions(withAuthOptions(new Command('status').description('Get processor status')))
   )
     .showHelpAfterError()
-    .option('--version <selector>', 'Version selector: active, pending, or all')
+    .option(
+      '--version <selector>',
+      'Version selector: active, pending, all, or a numeric version number',
+      parseVersionSelector
+    )
     .action(async (options, command) => {
       try {
         await runProcessorStatus(options)
@@ -176,22 +180,19 @@ async function runProcessorStatus(options: ProcessorStatusOptions) {
   const context = createApiContext(options)
   const project = await resolveProjectRef(options, context, { ownerSlug: true })
   const requestedVersion = normalizeVersionSelector(options.version)
+  const apiVersion = typeof requestedVersion === 'number' ? 'ALL' : (requestedVersion ?? 'ALL')
   const response = await ProcessorService.getProcessorStatusV2({
     path: {
       owner: project.owner,
       slug: project.slug
     },
     query: {
-      version: requestedVersion ?? 'ALL'
+      version: apiVersion
     },
     headers: context.headers
   })
   const data = unwrapApiResult(response)
-  if (!options.json) {
-    printOutput(options, shapeProcessorStatusOutput(data, requestedVersion))
-    return
-  }
-  printOutput(options, data)
+  printOutput(options, shapeProcessorStatusOutput(data, requestedVersion))
 }
 
 async function runProcessorSource(options: ProcessorSourceOptions) {
@@ -501,7 +502,7 @@ function handleProcessorCommandError(error: unknown, command?: Command) {
     error instanceof CliError &&
     (error.message.startsWith('Project is required.') ||
       error.message.startsWith('Invalid project ') ||
-      error.message.startsWith('Invalid version selector ') ||
+      error.message.startsWith('Invalid version selector') ||
       error.message.startsWith('Source file not found:'))
   ) {
     console.error(error.message)
@@ -610,15 +611,26 @@ function formatOutput(data: unknown) {
   return JSON.stringify(data, null, 2)
 }
 
-function normalizeVersionSelector(value?: string): 'ACTIVE' | 'PENDING' | 'ALL' | undefined {
-  if (!value) {
+function normalizeVersionSelector(value?: string | number): 'ACTIVE' | 'PENDING' | 'ALL' | number | undefined {
+  if (value === undefined) {
     return undefined
   }
+  if (typeof value === 'number') {
+    return value
+  }
   const normalized = value.toUpperCase()
   if (normalized === 'ACTIVE' || normalized === 'PENDING' || normalized === 'ALL') {
     return normalized
   }
-  throw new CliError(`Invalid version selector "${value}". Use active, pending, or all.`)
+  throw new CliError(`Invalid version selector "${value}". Use active, pending, all, or a version number.`)
+}
+
+function parseVersionSelector(value: string): string | number {
+  const num = Number.parseInt(value, 10)
+  if (!Number.isNaN(num) && String(num) === value) {
+    return num
+  }
+  return value
 }
 
 function parseInteger(value: string) {
@@ -639,7 +651,7 @@ function asNumber(value: unknown) {
 
 function shapeProcessorStatusOutput(
   data: { processors?: Array<Record<string, unknown>> },
-  versionSelector?: 'ACTIVE' | 'PENDING' | 'ALL'
+  versionSelector?: 'ACTIVE' | 'PENDING' | 'ALL' | number
 ) {
   const processors = Array.isArray(data.processors) ? data.processors : []
   if (versionSelector === 'ALL') {
@@ -651,6 +663,12 @@ function shapeProcessorStatusOutput(
       processors: processors.filter((processor) => asString(processor.versionState) === versionSelector)
     }
   }
+  if (typeof versionSelector === 'number') {
+    return {
+      ...data,
+      processors: processors.filter((processor) => asNumber(processor.version) === versionSelector)
+    }
+  }
   return {
     ...data,
     processors: processors.filter((processor) => {

package/src/commands/version.ts

@@ -7,7 +7,7 @@ export function createVersionCommand() {
   })
 }
 
-function version() {
+export function version() {
   console.log('CLI Version: ', getCliVersion())
   const sdkVersion = getSdkVersion()
   if (sdkVersion) {

package/src/index.ts

@@ -3,7 +3,7 @@
 import { Command } from '@commander-js/extra-typings'
 import { createLoginCommand } from './commands/login.js'
 import { createCreateCommand } from './commands/create.js'
-import { createVersionCommand } from './commands/version.js'
+import { createVersionCommand, version } from './commands/version.js'
 import { createTestCommand } from './commands/test.js'
 import { createAddCommand } from './commands/add.js'
 import { createCompileCommand } from './commands/compile.js'
@@ -34,6 +34,11 @@ if (process.argv.includes('--debug')) {
   enableApiDebug()
 }
 
+if (process.argv.length === 3 && process.argv[2] === '--version') {
+  version()
+  process.exit(0)
+}
+
 program.addCommand(createLoginCommand())
 program.addCommand(createCreateCommand())
 program.addCommand(createVersionCommand())