@sentio/cli 3.6.0-rc.1 → 3.6.0-rc.3

package/lib/index.js

@@ -143006,7 +143006,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 +143017,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 +143640,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
 
@@ -144804,6 +144810,7 @@ import process24 from "process";
 function createDashboardCommand() {
   const dashboardCommand = new Command("dashboard").description("Manage Sentio dashboards");
   dashboardCommand.addCommand(createDashboardListCommand());
+  dashboardCommand.addCommand(createDashboardCreateCommand());
   dashboardCommand.addCommand(createDashboardExportCommand());
   dashboardCommand.addCommand(createDashboardImportCommand());
   dashboardCommand.addCommand(createDashboardAddPanelCommand());
@@ -144820,6 +144827,17 @@ function createDashboardListCommand() {
     }
   });
 }
+function createDashboardCreateCommand() {
+  return withOutputOptions8(
+    withSharedProjectOptions7(withAuthOptions8(new Command("create").description("Create a dashboard for a project")))
+  ).showHelpAfterError().requiredOption("--title <name>", "Dashboard title").option("--file <path>", "Read initial dashboard JSON or YAML from file").option("--stdin", "Read initial dashboard JSON or YAML from stdin").action(async (options, command) => {
+    try {
+      await runDashboardCreate(options);
+    } catch (error) {
+      handleDashboardCommandError(error, command);
+    }
+  });
+}
 function createDashboardExportCommand() {
   return withOutputOptions8(
     withSharedProjectOptions7(
@@ -144862,7 +144880,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",
     `
 
@@ -144899,7 +144923,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 {
@@ -144919,6 +144953,16 @@ async function runDashboardList(options) {
   const data4 = unwrapApiResult(response);
   printOutput8(options, data4);
 }
+async function runDashboardCreate(options) {
+  const context = createApiContext(options);
+  const project = await resolveProjectRef(options, context, { ownerSlug: true });
+  const body = buildDashboardCreateBody(options, project);
+  const data4 = await postApiJson("/v1/dashboards", context, body);
+  printOutput8(options, {
+    message: `Dashboard "${options.title}" created`,
+    dashboard: data4.dashboard ?? data4
+  });
+}
 async function runDashboardExport(dashboardId, options) {
   const context = createApiContext(options);
   const response = await import_api14.WebService.exportDashboard({
@@ -144946,6 +144990,40 @@ async function runDashboardImport(dashboardId, options) {
   const data4 = unwrapApiResult(response);
   printOutput8(options, { message: `Dashboard imported into ${dashboardId}`, dashboard: data4.dashboard });
 }
+function buildDashboardCreateBody(options, project) {
+  const input = loadJsonInput(options);
+  const initialDashboard = normalizeDashboardInit(input);
+  return {
+    name: options.title,
+    projectOwner: project.owner,
+    projectSlug: project.slug,
+    ...initialDashboard
+  };
+}
+function normalizeDashboardInit(input) {
+  const emptyLayouts = {
+    responsiveLayouts: {
+      lg: { layouts: [] },
+      md: { layouts: [] },
+      sm: { layouts: [] },
+      xs: { layouts: [] }
+    }
+  };
+  if (input === void 0) {
+    return {
+      panels: {},
+      layouts: emptyLayouts
+    };
+  }
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new CliError("Dashboard initialization data must be a JSON or YAML object.");
+  }
+  const dashboard = input;
+  return {
+    panels: isRecord(dashboard.panels) ? dashboard.panels : {},
+    layouts: isRecord(dashboard.layouts) ? dashboard.layouts : emptyLayouts
+  };
+}
 async function runDashboardAddPanel(dashboardId, options) {
   const context = createApiContext(options);
   const selectedSources = [Boolean(options.sql), Boolean(options.event), Boolean(options.metric)].filter(Boolean).length;
@@ -144967,11 +145045,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;
@@ -144990,15 +145070,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({
@@ -145016,6 +145098,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;
@@ -145072,6 +145188,9 @@ function collectOption3(value, previous = []) {
   previous.push(value);
   return previous;
 }
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
 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");
 }
@@ -145082,7 +145201,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("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"))) {
     console.error(error.message);
     if (command) {
       console.error();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentio/cli",
-  "version": "3.6.0-rc.1",
+  "version": "3.6.0-rc.3",
   "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

@@ -7,6 +7,7 @@ import {
   createApiContext,
   handleCommandError,
   loadJsonInput,
+  postApiJson,
   resolveProjectRef,
   unwrapApiResult
 } from '../api.js'
@@ -30,6 +31,12 @@ interface DashboardImportOptions extends DashboardOptions {
   overrideLayouts?: boolean
 }
 
+interface DashboardCreateOptions extends DashboardOptions {
+  title?: string
+  file?: string
+  stdin?: boolean
+}
+
 interface AddPanelOptions extends DashboardOptions {
   panelName?: string
   type?: string
@@ -43,11 +50,15 @@ interface AddPanelOptions extends DashboardOptions {
   groupBy?: string[]
   aggr?: string
   func?: string[]
+  timeRangeStart?: string
+  timeRangeEnd?: string
+  timeRangeStep?: string
 }
 
 export function createDashboardCommand() {
   const dashboardCommand = new Command('dashboard').description('Manage Sentio dashboards')
   dashboardCommand.addCommand(createDashboardListCommand())
+  dashboardCommand.addCommand(createDashboardCreateCommand())
   dashboardCommand.addCommand(createDashboardExportCommand())
   dashboardCommand.addCommand(createDashboardImportCommand())
   dashboardCommand.addCommand(createDashboardAddPanelCommand())
@@ -68,6 +79,23 @@ function createDashboardListCommand() {
     })
 }
 
+function createDashboardCreateCommand() {
+  return withOutputOptions(
+    withSharedProjectOptions(withAuthOptions(new Command('create').description('Create a dashboard for a project')))
+  )
+    .showHelpAfterError()
+    .requiredOption('--title <name>', 'Dashboard title')
+    .option('--file <path>', 'Read initial dashboard JSON or YAML from file')
+    .option('--stdin', 'Read initial dashboard JSON or YAML from stdin')
+    .action(async (options, command) => {
+      try {
+        await runDashboardCreate(options)
+      } catch (error) {
+        handleDashboardCommandError(error, command)
+      }
+    })
+}
+
 function createDashboardExportCommand() {
   return withOutputOptions(
     withSharedProjectOptions(
@@ -137,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',
       `
@@ -174,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) => {
@@ -197,6 +244,18 @@ async function runDashboardList(options: DashboardOptions) {
   printOutput(options, data)
 }
 
+async function runDashboardCreate(options: DashboardCreateOptions) {
+  const context = createApiContext(options)
+  const project = await resolveProjectRef(options, context, { ownerSlug: true })
+  const body = buildDashboardCreateBody(options, project)
+  const data = await postApiJson<{ dashboard?: Record<string, unknown> }>('/v1/dashboards', context, body)
+
+  printOutput(options, {
+    message: `Dashboard "${options.title}" created`,
+    dashboard: data.dashboard ?? data
+  })
+}
+
 async function runDashboardExport(dashboardId: string, options: DashboardOptions) {
   const context = createApiContext(options)
   const response = await WebService.exportDashboard({
@@ -229,6 +288,46 @@ async function runDashboardImport(dashboardId: string, options: DashboardImportO
   printOutput(options, { message: `Dashboard imported into ${dashboardId}`, dashboard: data.dashboard })
 }
 
+function buildDashboardCreateBody(options: DashboardCreateOptions, project: { owner: string; slug: string }) {
+  const input = loadJsonInput(options)
+  const initialDashboard = normalizeDashboardInit(input)
+
+  return {
+    name: options.title,
+    projectOwner: project.owner,
+    projectSlug: project.slug,
+    ...initialDashboard
+  }
+}
+
+function normalizeDashboardInit(input: unknown) {
+  const emptyLayouts = {
+    responsiveLayouts: {
+      lg: { layouts: [] },
+      md: { layouts: [] },
+      sm: { layouts: [] },
+      xs: { layouts: [] }
+    }
+  }
+
+  if (input === undefined) {
+    return {
+      panels: {},
+      layouts: emptyLayouts
+    }
+  }
+
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new CliError('Dashboard initialization data must be a JSON or YAML object.')
+  }
+
+  const dashboard = input as Record<string, unknown>
+  return {
+    panels: isRecord(dashboard.panels) ? dashboard.panels : {},
+    layouts: isRecord(dashboard.layouts) ? dashboard.layouts : emptyLayouts
+  }
+}
+
 async function runDashboardAddPanel(dashboardId: string, options: AddPanelOptions) {
   const context = createApiContext(options)
 
@@ -257,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
@@ -286,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
     }
   }
 
@@ -315,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
@@ -378,6 +518,10 @@ function collectOption(value: string, previous: string[] = []) {
   return previous
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
 function withAuthOptions<T extends Command<any, any, any>>(command: T) {
   return command
     .option('--host <host>', 'Override Sentio host')
@@ -404,13 +548,18 @@ function handleDashboardCommandError(error: unknown, command?: Command) {
       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 metric selector') ||
+      error.message.startsWith('Invalid time range value'))
   ) {
     console.error(error.message)
     if (command) {