@supalytics/cli 0.4.2 → 0.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supalytics/cli",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "CLI for Supalytics web analytics",
   "type": "module",
   "bin": {

package/src/api.ts

@@ -159,7 +159,7 @@ export interface PropertyBreakdownResponse {
  */
 export async function listEvents(
   site: string,
-  period: string = "30d",
+  dateRange: string | [string, string] = "30d",
   limit: number = 100,
   isDev: boolean = false
 ): Promise<EventsResponse> {
@@ -177,7 +177,13 @@ export async function listEvents(
     );
   }
 
-  const params = new URLSearchParams({ period, limit: String(limit), domain: site });
+  const params = new URLSearchParams({ limit: String(limit), domain: site });
+  if (Array.isArray(dateRange)) {
+    params.set("start", dateRange[0]);
+    params.set("end", dateRange[1]);
+  } else {
+    params.set("period", dateRange);
+  }
   if (isDev) {
     params.set("is_dev", "true");
   }
@@ -199,7 +205,7 @@ export async function listEvents(
 export async function getEventProperties(
   site: string,
   eventName: string,
-  period: string = "30d",
+  dateRange: string | [string, string] = "30d",
   isDev: boolean = false
 ): Promise<PropertyKeysResponse> {
   const apiKey = await getApiKeyForSite(site);
@@ -208,7 +214,13 @@ export async function getEventProperties(
     throw new Error(`Not authenticated. Run \`supalytics login\` first.`);
   }
 
-  const params = new URLSearchParams({ period, domain: site });
+  const params = new URLSearchParams({ domain: site });
+  if (Array.isArray(dateRange)) {
+    params.set("start", dateRange[0]);
+    params.set("end", dateRange[1]);
+  } else {
+    params.set("period", dateRange);
+  }
   if (isDev) {
     params.set("is_dev", "true");
   }
@@ -232,7 +244,7 @@ export async function getPropertyBreakdown(
   site: string,
   eventName: string,
   propertyKey: string,
-  period: string = "30d",
+  dateRange: string | [string, string] = "30d",
   limit: number = 100,
   includeRevenue: boolean = false,
   isDev: boolean = false
@@ -244,11 +256,16 @@ export async function getPropertyBreakdown(
   }
 
   const params = new URLSearchParams({
-    period,
     limit: String(limit),
     include_revenue: String(includeRevenue),
     domain: site,
   });
+  if (Array.isArray(dateRange)) {
+    params.set("start", dateRange[0]);
+    params.set("end", dateRange[1]);
+  } else {
+    params.set("period", dateRange);
+  }
   if (isDev) {
     params.set("is_dev", "true");
   }
@@ -351,7 +368,7 @@ export interface AnnotationsResponse {
  */
 export async function listAnnotations(
   site: string,
-  period: string = "30d"
+  dateRange: string | [string, string] = "30d"
 ): Promise<AnnotationsResponse> {
   const apiKey = await getApiKeyForSite(site);
 
@@ -367,36 +384,13 @@ export async function listAnnotations(
     );
   }
 
-  // Valid periods
-  const validPeriods = ["7d", "14d", "30d", "90d", "12mo", "all"] as const;
-  if (!validPeriods.includes(period as typeof validPeriods[number])) {
-    throw new Error(`Invalid period "${period}". Valid periods: ${validPeriods.join(", ")}`);
-  }
-
-  // Calculate date range from period
-  const endDate = new Date();
-  let startDate = new Date();
-
-  if (period === "7d") {
-    startDate.setDate(endDate.getDate() - 7);
-  } else if (period === "14d") {
-    startDate.setDate(endDate.getDate() - 14);
-  } else if (period === "30d") {
-    startDate.setDate(endDate.getDate() - 30);
-  } else if (period === "90d") {
-    startDate.setDate(endDate.getDate() - 90);
-  } else if (period === "12mo") {
-    startDate.setMonth(endDate.getMonth() - 12);
-  } else if (period === "all") {
-    startDate = new Date("2020-01-01");
+  const params = new URLSearchParams({ domain: site });
+  if (Array.isArray(dateRange)) {
+    params.set("start_date", dateRange[0]);
+    params.set("end_date", dateRange[1]);
   }
-
-  const formatDate = (d: Date) => d.toISOString().split("T")[0];
-  const params = new URLSearchParams({
-    domain: site,
-    start_date: formatDate(startDate),
-    end_date: formatDate(endDate),
-  });
+  // Annotations API only supports start_date/end_date, not period.
+  // String values like "all" are left without date params so the API returns everything.
 
   const response = await fetch(`${API_BASE}/v1/annotations?${params}`, {
     headers: { Authorization: `Bearer ${apiKey}` },
@@ -734,6 +728,235 @@ export async function getJourneyStats(
   return response.json();
 }
 
+// Funnels API types
+export interface FunnelStep {
+  id: string;
+  step_order: number;
+  name: string;
+  type: string; // 'page' | 'event' | 'purchase' | 'trial'
+  match_type?: string | null;
+  match_value?: string | null;
+  property_key?: string | null;
+  property_value?: string | null;
+}
+
+export interface FunnelItem {
+  id: string;
+  name: string;
+  description?: string | null;
+  mode: string; // 'ordered' | 'unordered'
+  steps: FunnelStep[];
+  created_at: string;
+  updated_at: string;
+}
+
+export interface FunnelsListResponse {
+  data: FunnelItem[];
+  meta: { domain: string };
+}
+
+export interface FunnelResponse {
+  data: FunnelItem;
+  meta: { domain: string };
+}
+
+export interface FunnelAnalysisRow {
+  step_order: number;
+  step_type: string;
+  match_type: string | null;
+  match_value: string | null;
+  property_key: string | null;
+  property_value: string | null;
+  visitors: number;
+  conversion_rate_from_start: number;
+  conversion_rate_from_prev: number;
+}
+
+export interface FunnelAnalysisResponse {
+  data: FunnelAnalysisRow[];
+  meta: {
+    domain: string;
+    date_range: [string, string];
+    query_ms: number;
+  };
+}
+
+export interface FunnelStepInput {
+  name: string;
+  type: string;
+  match_type?: string;
+  match_value?: string;
+  property_key?: string;
+  property_value?: string;
+}
+
+/**
+ * List all funnels for a site
+ */
+export async function listFunnels(site: string): Promise<FunnelsListResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    const sites = await getSites();
+    if (sites.length === 0) {
+      throw new Error(
+        "No sites configured. Run `supalytics login` to authenticate."
+      );
+    }
+    throw new Error(
+      `Not authenticated or site '${site}' not found. Available sites: ${sites.join(", ")}`
+    );
+  }
+
+  const params = new URLSearchParams({ domain: site });
+  const response = await fetch(`${API_BASE}/v1/funnels?${params}`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Get a single funnel
+ */
+export async function getFunnel(
+  site: string,
+  funnelId: string
+): Promise<FunnelResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    throw new Error(`Not authenticated. Run \`supalytics login\` first.`);
+  }
+
+  const params = new URLSearchParams({ domain: site });
+  const response = await fetch(`${API_BASE}/v1/funnels/${funnelId}?${params}`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Create a funnel
+ */
+export async function createFunnel(
+  site: string,
+  data: {
+    name: string;
+    description?: string;
+    mode?: string;
+    steps: FunnelStepInput[];
+  }
+): Promise<FunnelResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    throw new Error(`Not authenticated. Run \`supalytics login\` first.`);
+  }
+
+  const response = await fetch(`${API_BASE}/v1/funnels`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ ...data, domain: site }),
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Update a funnel
+ */
+export async function updateFunnel(
+  site: string,
+  funnelId: string,
+  data: {
+    name?: string;
+    description?: string;
+    mode?: string;
+    steps?: FunnelStepInput[];
+  }
+): Promise<FunnelResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    throw new Error(`Not authenticated. Run \`supalytics login\` first.`);
+  }
+
+  const response = await fetch(`${API_BASE}/v1/funnels/${funnelId}`, {
+    method: "PUT",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ ...data, domain: site }),
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Run funnel analysis
+ */
+export async function analyzeFunnel(
+  site: string,
+  funnelId: string,
+  dateRange: string | [string, string] = "30d",
+  isDev: boolean = false
+): Promise<FunnelAnalysisResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    throw new Error(`Not authenticated. Run \`supalytics login\` first.`);
+  }
+
+  const body: Record<string, unknown> = { domain: site, is_dev: isDev };
+  if (Array.isArray(dateRange)) {
+    body.date_range = dateRange;
+  } else {
+    body.date_range = dateRange;
+  }
+
+  const response = await fetch(`${API_BASE}/v1/funnels/${funnelId}/analyze`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
 /**
  * Format revenue in cents to dollars
  */

package/src/commands/annotations.ts

@@ -2,6 +2,23 @@ import chalk from "chalk"
 import { Command } from "commander"
 import { createAnnotation, deleteAnnotation, listAnnotations } from "../api"
 import { getDefaultSite } from "../config"
+import { parsePeriod } from "../ui"
+
+/**
+ * Merge subcommand options with parent command options.
+ * Commander doesn't propagate options like -s/--site and --json
+ * from parent to subcommands, so we check both.
+ */
+function mergedOpts(cmd: Command): Record<string, unknown> {
+	const parentOpts = cmd.parent?.opts() || {}
+	const ownOpts = cmd.opts()
+	return { ...parentOpts, ...ownOpts }
+}
+
+async function resolveSiteOption(cmd: Command): Promise<string | undefined> {
+	const opts = mergedOpts(cmd)
+	return (opts.site as string) || (await getDefaultSite())
+}
 
 const annotationsExamples = `
 Examples:
@@ -23,10 +40,10 @@ Examples:
 export const annotationsCommand = new Command("annotations")
 	.description("Manage chart annotations")
 	.addHelpText("after", annotationsExamples)
-	.argument("[period]", "Time period: 7d, 14d, 30d, 90d, 12mo, all", "30d")
 	.option("-s, --site <site>", "Site to query")
+	.option("-p, --period <period>", "Time period: 7d, 14d, 30d, 90d, 12mo, all", "30d")
 	.option("--json", "Output as JSON")
-	.action(async (period, options) => {
+	.action(async (options) => {
 		const site = options.site || (await getDefaultSite())
 
 		if (!site) {
@@ -39,7 +56,7 @@ export const annotationsCommand = new Command("annotations")
 		}
 
 		try {
-			const response = await listAnnotations(site, period)
+			const response = await listAnnotations(site, parsePeriod(options.period))
 
 			if (options.json) {
 				console.log(JSON.stringify(response, null, 2))
@@ -80,8 +97,9 @@ annotationsCommand
 	.option("-s, --site <site>", "Site to query")
 	.option("-d, --description <text>", "Optional description")
 	.option("--json", "Output as JSON")
-	.action(async (date, title, options) => {
-		const site = options.site || (await getDefaultSite())
+	.action(async (date, title, _options, cmd) => {
+		const options = mergedOpts(cmd)
+		const site = await resolveSiteOption(cmd)
 
 		if (!site) {
 			console.error(
@@ -99,7 +117,7 @@ annotationsCommand
 		}
 
 		try {
-			const annotation = await createAnnotation(site, date, title, options.description)
+			const annotation = await createAnnotation(site, date, title, options.description as string | undefined)
 
 			if (options.json) {
 				console.log(JSON.stringify(annotation, null, 2))
@@ -126,8 +144,8 @@ annotationsCommand
 	.command("remove <id>")
 	.description("Remove an annotation")
 	.option("-s, --site <site>", "Site to query")
-	.action(async (id, options) => {
-		const site = options.site || (await getDefaultSite())
+	.action(async (id, _options, cmd) => {
+		const site = await resolveSiteOption(cmd)
 
 		if (!site) {
 			console.error(

package/src/commands/completions.ts

@@ -10,7 +10,7 @@ _supalytics_completions() {
     cur="\${COMP_WORDS[COMP_CWORD]}"
     prev="\${COMP_WORDS[COMP_CWORD-1]}"
 
-    commands="init login logout sites default remove stats pages referrers countries trend query events realtime completions help"
+    commands="init login logout sites default remove stats pages referrers countries trend query events annotations realtime completions help"
 
     # Main command completion
     if [[ \${COMP_CWORD} -eq 1 ]]; then
@@ -21,7 +21,7 @@ _supalytics_completions() {
     # Subcommand options
     case "\${COMP_WORDS[1]}" in
         stats)
-            opts="today yesterday week month year 7d 14d 30d 90d 12mo all --site --start --end --filter --all --no-revenue --json"
+            opts="--site --period --start --end --filter --all --no-revenue --json"
             ;;
         pages|referrers|countries)
             opts="--site --period --start --end --limit --filter --no-revenue --json"
@@ -35,6 +35,9 @@ _supalytics_completions() {
         events)
             opts="--site --period --property --limit --no-revenue --json"
             ;;
+        annotations)
+            opts="--site --period --json add remove"
+            ;;
         realtime)
             opts="--site --json --watch"
             ;;
@@ -86,6 +89,7 @@ _supalytics() {
         'trend:Daily visitor trend'
         'query:Flexible query with custom metrics and dimensions'
         'events:List and explore custom events'
+        'annotations:Manage chart annotations'
         'realtime:Live visitors on your site right now'
         'completions:Generate shell completions'
         'help:Display help for command'
@@ -118,19 +122,14 @@ _supalytics() {
             case \$words[1] in
                 stats)
                     _arguments \\
-                        '1: :->period' \\
                         '--site[Site to query]:domain:' \\
+                        '--period[Time period]:period:(today yesterday week month year 7d 14d 30d 90d 12mo all)' \\
                         '--start[Start date]:date:' \\
                         '--end[End date]:date:' \\
                         '*--filter[Filter]:filter:' \\
                         '--all[Show detailed breakdown]' \\
                         '--no-revenue[Exclude revenue metrics]' \\
                         '--json[Output as JSON]'
-                    case \$state in
-                        period)
-                            _describe 'period' period_opts
-                            ;;
-                    esac
                     ;;
                 pages|referrers|countries)
                     _arguments \\
@@ -180,6 +179,12 @@ _supalytics() {
                         '--no-revenue[Exclude revenue]' \\
                         '--json[Output as JSON]'
                     ;;
+                annotations)
+                    _arguments \\
+                        '--site[Site to query]:domain:' \\
+                        '--period[Time period]:period:(7d 14d 30d 90d 12mo all)' \\
+                        '--json[Output as JSON]'
+                    ;;
                 realtime)
                     _arguments \\
                         '--site[Site to query]:domain:' \\
@@ -236,13 +241,14 @@ complete -c supalytics -n "__fish_use_subcommand" -a "countries" -d "Traffic by
 complete -c supalytics -n "__fish_use_subcommand" -a "trend" -d "Daily visitor trend"
 complete -c supalytics -n "__fish_use_subcommand" -a "query" -d "Flexible query with custom metrics"
 complete -c supalytics -n "__fish_use_subcommand" -a "events" -d "List and explore custom events"
+complete -c supalytics -n "__fish_use_subcommand" -a "annotations" -d "Manage chart annotations"
 complete -c supalytics -n "__fish_use_subcommand" -a "realtime" -d "Live visitors right now"
 complete -c supalytics -n "__fish_use_subcommand" -a "completions" -d "Generate shell completions"
 complete -c supalytics -n "__fish_use_subcommand" -a "help" -d "Display help for command"
 
 # Stats options
-complete -c supalytics -n "__fish_seen_subcommand_from stats" -a "today yesterday week month year 7d 14d 30d 90d 12mo all"
 complete -c supalytics -n "__fish_seen_subcommand_from stats" -l site -s s -d "Site to query"
+complete -c supalytics -n "__fish_seen_subcommand_from stats" -l period -s p -d "Time period" -a "today yesterday week month year 7d 14d 30d 90d 12mo all"
 complete -c supalytics -n "__fish_seen_subcommand_from stats" -l start -d "Start date"
 complete -c supalytics -n "__fish_seen_subcommand_from stats" -l end -d "End date"
 complete -c supalytics -n "__fish_seen_subcommand_from stats" -l filter -s f -d "Filter"
@@ -293,6 +299,11 @@ complete -c supalytics -n "__fish_seen_subcommand_from events" -l limit -s l -d
 complete -c supalytics -n "__fish_seen_subcommand_from events" -l no-revenue -d "Exclude revenue"
 complete -c supalytics -n "__fish_seen_subcommand_from events" -l json -d "Output as JSON"
 
+# Annotations options
+complete -c supalytics -n "__fish_seen_subcommand_from annotations" -l site -s s -d "Site to query"
+complete -c supalytics -n "__fish_seen_subcommand_from annotations" -l period -s p -d "Time period" -a "7d 14d 30d 90d 12mo all"
+complete -c supalytics -n "__fish_seen_subcommand_from annotations" -l json -d "Output as JSON"
+
 # Realtime options
 complete -c supalytics -n "__fish_seen_subcommand_from realtime" -l site -s s -d "Site to query"
 complete -c supalytics -n "__fish_seen_subcommand_from realtime" -l json -d "Output as JSON"

package/src/commands/countries.ts

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import chalk from "chalk";
 import { query, formatNumber } from "../api";
 import { getDefaultSite } from "../config";
-import { sparkBar, formatRevenue } from "../ui";
+import { sparkBar, formatRevenue, parsePeriod } from "../ui";
 
 export const countriesCommand = new Command("countries")
   .description("Traffic by country")
@@ -25,7 +25,7 @@ export const countriesCommand = new Command("countries")
 
     const dateRange = options.start && options.end
       ? [options.start, options.end] as [string, string]
-      : options.period;
+      : parsePeriod(options.period);
 
     const filters = options.filter
       ? options.filter.map((f: string) => {

package/src/commands/events.ts

@@ -8,6 +8,7 @@ import {
 	type PropertyKeysResponse,
 } from "../api"
 import { getDefaultSite } from "../config"
+import { parsePeriod } from "../ui"
 
 const eventsExamples = `
 Examples:
@@ -20,6 +21,10 @@ Examples:
   # Get breakdown of a property
   supalytics events signup --property plan
 
+  # With custom date range
+  supalytics events --start 2026-01-01 --end 2026-01-31
+  supalytics events signup --start 2026-01-01 --end 2026-01-31
+
   # Without revenue
   supalytics events signup --property plan --no-revenue`
 
@@ -52,6 +57,8 @@ export const eventsCommand = new Command("events")
 	.argument("[event]", "Event name to explore")
 	.option("-s, --site <site>", "Site to query")
 	.option("-p, --period <period>", "Time period: 7d, 14d, 30d, 90d, 12mo, all", "30d")
+	.option("--start <date>", "Start date (YYYY-MM-DD)")
+	.option("--end <date>", "End date (YYYY-MM-DD)")
 	.option("--property <key>", "Get breakdown for a specific property")
 	.option("-l, --limit <number>", "Number of results", "20")
 	.option("--no-revenue", "Exclude revenue metrics")
@@ -59,6 +66,9 @@ export const eventsCommand = new Command("events")
 	.option("-t, --test", "Test mode: query localhost data instead of production")
 	.action(async (event, options) => {
 		const site = options.site || (await getDefaultSite())
+		const dateRange = options.start && options.end
+			? [options.start, options.end] as [string, string]
+			: parsePeriod(options.period)
 
 		if (!site) {
 			console.error(
@@ -74,7 +84,7 @@ export const eventsCommand = new Command("events")
 			if (!event) {
 				const response = await listEvents(
 					site,
-					options.period,
+					dateRange,
 					parseInt(options.limit),
 					options.test || false
 				)
@@ -110,7 +120,7 @@ export const eventsCommand = new Command("events")
 					site,
 					event,
 					options.property,
-					options.period,
+					dateRange,
 					parseInt(options.limit),
 					options.revenue !== false,
 					options.test || false
@@ -146,8 +156,8 @@ export const eventsCommand = new Command("events")
 
 			// If just event name, show event stats + properties
 			const [eventsResponse, propsResponse] = await Promise.all([
-				listEvents(site, options.period, 100, options.test || false), // Get all events to find this one
-				getEventProperties(site, event, options.period, options.test || false),
+				listEvents(site, dateRange, 100, options.test || false), // Get all events to find this one
+				getEventProperties(site, event, dateRange, options.test || false),
 			])
 
 			// Find the specific event stats

package/src/commands/funnels.ts

@@ -0,0 +1,471 @@
+import chalk from "chalk"
+import { Command } from "commander"
+import {
+	listFunnels,
+	getFunnel,
+	createFunnel,
+	updateFunnel,
+	analyzeFunnel,
+	formatNumber,
+	formatPercent,
+	type FunnelStepInput,
+	type FunnelAnalysisRow,
+} from "../api"
+import { getDefaultSite } from "../config"
+import { parsePeriod, sparkBar } from "../ui"
+
+/**
+ * Merge subcommand options with parent command options.
+ * Commander doesn't propagate options like -s/--site and --json
+ * from parent to subcommands, so we check both.
+ */
+function mergedOpts(cmd: Command): Record<string, unknown> {
+	const parentOpts = cmd.parent?.opts() || {}
+	const ownOpts = cmd.opts()
+	// Own opts take priority, but fall back to parent for unset values
+	return { ...parentOpts, ...ownOpts }
+}
+
+async function resolveSiteOption(cmd: Command): Promise<string | undefined> {
+	const opts = mergedOpts(cmd)
+	return (opts.site as string) || (await getDefaultSite())
+}
+
+const funnelsExamples = `
+Examples:
+  # List all funnels
+  supalytics funnels
+
+  # View a funnel with conversion analysis
+  supalytics funnels <id>
+
+  # View with custom date range
+  supalytics funnels <id> -p 90d
+
+  # Create a funnel
+  supalytics funnels create "Signup Flow" --step "page:/pricing" --step "event:signup_clicked" --step "purchase"
+
+  # Create with page matching
+  supalytics funnels create "Blog to Signup" --step "page:starts_with:/blog" --step "page:/signup" --step "event:account_created"
+
+  # Create an ordered funnel
+  supalytics funnels create "Checkout" --mode ordered --step "page:/cart" --step "page:/checkout" --step "purchase"
+
+  # Update funnel name
+  supalytics funnels update <id> --name "New Name"
+
+  # Update funnel steps
+  supalytics funnels update <id> --step "page:/pricing" --step "purchase"`
+
+/**
+ * Parse a step definition string into a FunnelStepInput.
+ *
+ * Formats:
+ *   page:/pricing              → page, exact, /pricing
+ *   page:starts_with:/blog     → page, starts_with, /blog
+ *   page:contains:pricing      → page, contains, pricing
+ *   page:regex:^/blog/.*       → page, regex, ^/blog/.*
+ *   event:signup_clicked       → event, match_value=signup_clicked
+ *   event:signup:plan:pro      → event, match_value=signup, property_key=plan, property_value=pro
+ *   purchase                   → purchase type
+ *   trial                      → trial type
+ */
+function parseStep(definition: string): FunnelStepInput {
+	const parts = definition.split(":")
+
+	// Simple types: "purchase" or "trial"
+	if (parts.length === 1) {
+		const type = parts[0].toLowerCase()
+		if (type === "purchase" || type === "trial") {
+			return { name: type === "purchase" ? "Purchase" : "Trial start", type }
+		}
+		throw new Error(
+			`Invalid step: "${definition}". Use "page:<path>", "event:<name>", "purchase", or "trial"`
+		)
+	}
+
+	const type = parts[0].toLowerCase()
+
+	if (type === "page") {
+		// Check for explicit match type: page:starts_with:/blog
+		const matchTypes = ["exact", "starts_with", "contains", "regex"]
+		if (parts.length >= 3 && matchTypes.includes(parts[1])) {
+			const matchType = parts[1]
+			const matchValue = parts.slice(2).join(":")
+			return {
+				name: `Visit ${matchValue}`,
+				type: "page",
+				match_type: matchType,
+				match_value: matchValue,
+			}
+		}
+		// Default: page:/pricing → exact match
+		const matchValue = parts.slice(1).join(":")
+		return {
+			name: `Visit ${matchValue}`,
+			type: "page",
+			match_type: "exact",
+			match_value: matchValue,
+		}
+	}
+
+	if (type === "event") {
+		const eventName = parts[1]
+		// event:signup:plan:pro → event with property filter
+		if (parts.length >= 4) {
+			return {
+				name: eventName,
+				type: "event",
+				match_value: eventName,
+				property_key: parts[2],
+				property_value: parts.slice(3).join(":"),
+			}
+		}
+		return {
+			name: eventName,
+			type: "event",
+			match_value: eventName,
+		}
+	}
+
+	throw new Error(
+		`Invalid step type "${type}". Use "page", "event", "purchase", or "trial"`
+	)
+}
+
+/**
+ * Get a human-readable label for a step
+ */
+function stepLabel(step: { type: string; match_type?: string | null; match_value?: string | null; name?: string }): string {
+	if (step.type === "purchase") return "Purchase"
+	if (step.type === "trial") return "Trial start"
+	if (step.type === "page") {
+		const prefix = step.match_type && step.match_type !== "exact" ? `${step.match_type}: ` : ""
+		return `${prefix}${step.match_value || step.name || "page"}`
+	}
+	if (step.type === "event") {
+		return step.match_value || step.name || "event"
+	}
+	return step.name || step.type
+}
+
+/**
+ * Render funnel analysis results
+ */
+function renderAnalysis(rows: FunnelAnalysisRow[], funnel: { name: string; description?: string | null; mode: string; steps: Array<{ name: string; type: string; match_type?: string | null; match_value?: string | null }> }) {
+	console.log()
+	console.log(chalk.bold(funnel.name))
+	if (funnel.description) {
+		console.log(chalk.dim(`  ${funnel.description}`))
+	}
+	console.log(chalk.dim(`  Mode: ${funnel.mode}`))
+	console.log()
+
+	if (rows.length === 0) {
+		console.log(chalk.dim("  No data for the selected period"))
+		console.log()
+		return
+	}
+
+	const maxVisitors = Math.max(...rows.map((r) => r.visitors))
+
+	for (const row of rows) {
+		// ClickHouse may return "ps.<col>" instead of "<col>" for joined columns
+		const rawRow = row as Record<string, unknown>
+		const stepOrder = row.step_order ?? (rawRow["ps.step_order"] as number)
+		const stepType = row.step_type ?? (rawRow["ps.step_type"] as string)
+		const matchType = row.match_type ?? (rawRow["ps.match_type"] as string | null)
+		const matchValue = row.match_value ?? (rawRow["ps.match_value"] as string | null)
+		const stepNum = `Step ${stepOrder}:`
+		const label = stepLabel({
+			type: stepType,
+			match_type: matchType,
+			match_value: matchValue,
+			name: funnel.steps[stepOrder - 1]?.name,
+		})
+		const visitors = formatNumber(row.visitors)
+		const bar = sparkBar(row.visitors, maxVisitors, 16)
+		const pct = formatPercent(row.conversion_rate_from_start)
+
+		let dropoff = ""
+		if (stepOrder > 1) {
+			const drop = row.conversion_rate_from_prev - 100
+			dropoff = chalk.red(` (${drop >= 0 ? "+" : ""}${drop.toFixed(1)}%)`)
+		}
+
+		console.log(
+			`  ${chalk.dim(stepNum.padEnd(8))} ${label.padEnd(30)} ${visitors.padStart(10)} visitors  ${bar}  ${pct.padStart(6)}${dropoff}`
+		)
+	}
+
+	// Overall conversion
+	if (rows.length >= 2) {
+		const first = rows[0]
+		const last = rows[rows.length - 1]
+		const overall = first.visitors > 0 ? (last.visitors / first.visitors) * 100 : 0
+		console.log()
+		console.log(
+			chalk.bold(`  Overall conversion: ${formatPercent(overall)}`) +
+				chalk.dim(` (${formatNumber(first.visitors)} → ${formatNumber(last.visitors)})`)
+		)
+	}
+	console.log()
+}
+
+export const funnelsCommand = new Command("funnels")
+	.description("Manage and analyze conversion funnels")
+	.addHelpText("after", funnelsExamples)
+	.argument("[id]", "Funnel ID to view details and conversion analysis")
+	.option("-s, --site <site>", "Site to query")
+	.option("-p, --period <period>", "Time period: 7d, 14d, 30d, 90d, 12mo, all", "30d")
+	.option("--start <date>", "Start date (YYYY-MM-DD)")
+	.option("--end <date>", "End date (YYYY-MM-DD)")
+	.option("--json", "Output as JSON")
+	.action(async (id, options) => {
+		const site = options.site || (await getDefaultSite())
+
+		if (!site) {
+			console.error(
+				chalk.red(
+					"Error: No site specified. Use --site or set a default with `supalytics login --site`"
+				)
+			)
+			process.exit(1)
+		}
+
+		// If an ID is provided, show funnel details + analysis
+		if (id) {
+			try {
+				const dateRange =
+					options.start && options.end
+						? ([options.start, options.end] as [string, string])
+						: parsePeriod(options.period as string)
+
+				// Fetch funnel definition and run analysis in parallel
+				const [funnelResponse, analysisResponse] = await Promise.all([
+					getFunnel(site, id),
+					analyzeFunnel(site, id, dateRange),
+				])
+
+				if (options.json) {
+					console.log(
+						JSON.stringify(
+							{
+								funnel: funnelResponse.data,
+								analysis: analysisResponse.data,
+								meta: analysisResponse.meta,
+							},
+							null,
+							2
+						)
+					)
+					return
+				}
+
+				const [startDate, endDate] = analysisResponse.meta.date_range
+				console.log(chalk.dim(`  ${startDate} → ${endDate}  (${analysisResponse.meta.query_ms}ms)`))
+
+				renderAnalysis(analysisResponse.data, funnelResponse.data)
+			} catch (error) {
+				console.error(chalk.red(`Error: ${(error as Error).message}`))
+				process.exit(1)
+			}
+			return
+		}
+
+		// No ID — list all funnels
+		try {
+			const response = await listFunnels(site)
+
+			if (options.json) {
+				console.log(JSON.stringify(response, null, 2))
+				return
+			}
+
+			console.log()
+			console.log(chalk.bold("Funnels"))
+			console.log()
+
+			if (response.data.length === 0) {
+				console.log(chalk.dim("  No funnels found"))
+				console.log()
+				console.log(
+					chalk.dim(
+						'  Create one with: supalytics funnels create "Name" --step "page:/pricing" --step "purchase"'
+					)
+				)
+				console.log()
+				return
+			}
+
+			for (const funnel of response.data) {
+				const stepCount = funnel.steps?.length || 0
+				const created = new Date(funnel.created_at).toISOString().split("T")[0]
+				console.log(
+					`  ${chalk.cyan(funnel.name.padEnd(30))} ${String(stepCount).padStart(2)} steps  ${funnel.mode.padEnd(10)}  ${chalk.dim(created)}`
+				)
+				if (funnel.description) {
+					console.log(`  ${chalk.dim(funnel.description)}`)
+				}
+				console.log(chalk.dim(`  id: ${funnel.id}`))
+				console.log()
+			}
+		} catch (error) {
+			console.error(chalk.red(`Error: ${(error as Error).message}`))
+			process.exit(1)
+		}
+	})
+
+// Subcommand: create
+funnelsCommand
+	.command("create <name>")
+	.description("Create a new funnel")
+	.option("-s, --site <site>", "Site to query")
+	.option("--step <definition>", "Step definition (repeatable)", (val: string, prev: string[]) => prev.concat(val), [] as string[])
+	.option("--mode <mode>", "Funnel mode: ordered or unordered", "unordered")
+	.option("-d, --description <text>", "Optional description")
+	.option("--json", "Output as JSON")
+	.action(async (name, _options, cmd) => {
+		const options = mergedOpts(cmd)
+		const site = await resolveSiteOption(cmd)
+
+		if (!site) {
+			console.error(
+				chalk.red(
+					"Error: No site specified. Use --site or set a default with `supalytics login --site`"
+				)
+			)
+			process.exit(1)
+		}
+
+		const steps = options.step as string[] | undefined
+		if (!steps || steps.length === 0) {
+			console.error(chalk.red("Error: At least one --step is required"))
+			console.error(
+				chalk.dim('  Example: --step "page:/pricing" --step "event:signup" --step "purchase"')
+			)
+			process.exit(1)
+		}
+
+		if (!["ordered", "unordered"].includes(options.mode as string)) {
+			console.error(chalk.red("Error: --mode must be 'ordered' or 'unordered'"))
+			process.exit(1)
+		}
+
+		try {
+			const parsedSteps: FunnelStepInput[] = steps.map((s: string) => parseStep(s))
+
+			const response = await createFunnel(site, {
+				name,
+				description: options.description as string | undefined,
+				mode: options.mode as string | undefined,
+				steps: parsedSteps,
+			})
+
+			if (options.json) {
+				console.log(JSON.stringify(response, null, 2))
+				return
+			}
+
+			console.log()
+			console.log(chalk.green("Funnel created"))
+			console.log()
+			console.log(`  ${chalk.bold(response.data.name)}`)
+			if (response.data.description) {
+				console.log(`  ${chalk.dim(response.data.description)}`)
+			}
+			console.log(chalk.dim(`  Mode: ${response.data.mode}`))
+			console.log()
+
+			for (const step of response.data.steps) {
+				console.log(
+					`  ${chalk.dim(`Step ${step.step_order}:`)} ${stepLabel(step)}`
+				)
+			}
+			console.log()
+			console.log(chalk.dim(`  id: ${response.data.id}`))
+			console.log()
+		} catch (error) {
+			console.error(chalk.red(`Error: ${(error as Error).message}`))
+			process.exit(1)
+		}
+	})
+
+// Subcommand: update
+funnelsCommand
+	.command("update <id>")
+	.description("Update an existing funnel")
+	.option("-s, --site <site>", "Site to query")
+	.option("--name <name>", "New funnel name")
+	.option("-d, --description <text>", "New description")
+	.option("--mode <mode>", "Funnel mode: ordered or unordered")
+	.option("--step <definition>", "Replace steps (repeatable)", (val: string, prev: string[]) => prev.concat(val), [] as string[])
+	.option("--json", "Output as JSON")
+	.action(async (id, _options, cmd) => {
+		const options = mergedOpts(cmd)
+		const site = await resolveSiteOption(cmd)
+
+		if (!site) {
+			console.error(
+				chalk.red(
+					"Error: No site specified. Use --site or set a default with `supalytics login --site`"
+				)
+			)
+			process.exit(1)
+		}
+
+		if (options.mode && !["ordered", "unordered"].includes(options.mode as string)) {
+			console.error(chalk.red("Error: --mode must be 'ordered' or 'unordered'"))
+			process.exit(1)
+		}
+
+		const updateData: {
+			name?: string
+			description?: string
+			mode?: string
+			steps?: FunnelStepInput[]
+		} = {}
+
+		if (options.name) updateData.name = options.name as string
+		if (options.description) updateData.description = options.description as string
+		if (options.mode) updateData.mode = options.mode as string
+		const updateSteps = options.step as string[] | undefined
+		if (updateSteps && updateSteps.length > 0) {
+			updateData.steps = updateSteps.map((s: string) => parseStep(s))
+		}
+
+		if (Object.keys(updateData).length === 0) {
+			console.error(chalk.red("Error: No updates specified"))
+			console.error(chalk.dim("  Use --name, --description, --mode, or --step"))
+			process.exit(1)
+		}
+
+		try {
+			const response = await updateFunnel(site, id, updateData)
+
+			if (options.json) {
+				console.log(JSON.stringify(response, null, 2))
+				return
+			}
+
+			console.log()
+			console.log(chalk.green("Funnel updated"))
+			console.log()
+			console.log(`  ${chalk.bold(response.data.name)}`)
+			if (response.data.description) {
+				console.log(`  ${chalk.dim(response.data.description)}`)
+			}
+			console.log(chalk.dim(`  Mode: ${response.data.mode}`))
+			console.log()
+
+			for (const step of response.data.steps) {
+				console.log(
+					`  ${chalk.dim(`Step ${step.step_order}:`)} ${stepLabel(step)}`
+				)
+			}
+			console.log()
+		} catch (error) {
+			console.error(chalk.red(`Error: ${(error as Error).message}`))
+			process.exit(1)
+		}
+	})

package/src/commands/pages.ts

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import chalk from "chalk";
 import { query, formatNumber } from "../api";
 import { getDefaultSite } from "../config";
-import { sparkBar, truncate, formatRevenue } from "../ui";
+import { sparkBar, truncate, formatRevenue, parsePeriod } from "../ui";
 
 export const pagesCommand = new Command("pages")
   .description("Top pages by visitors")
@@ -25,7 +25,7 @@ export const pagesCommand = new Command("pages")
 
     const dateRange = options.start && options.end
       ? [options.start, options.end] as [string, string]
-      : options.period;
+      : parsePeriod(options.period);
 
     const filters = options.filter
       ? options.filter.map((f: string) => {

package/src/commands/query.ts

@@ -2,7 +2,7 @@ import chalk from "chalk"
 import { Command } from "commander"
 import { formatDuration, formatNumber, formatPercent, query } from "../api"
 import { getDefaultSite } from "../config"
-import { type TableColumn, table } from "../ui"
+import { type TableColumn, table, parsePeriod } from "../ui"
 
 const queryExamples = `
 Examples:
@@ -75,7 +75,7 @@ export const queryCommand = new Command("query")
 		const dateRange =
 			options.start && options.end
 				? ([options.start, options.end] as [string, string])
-				: options.period
+				: parsePeriod(options.period)
 
 		// Parse metrics
 		const metrics = options.metrics.split(",").map((m: string) => m.trim())

package/src/commands/referrers.ts

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import chalk from "chalk";
 import { query, formatNumber } from "../api";
 import { getDefaultSite } from "../config";
-import { sparkBar, truncate, formatRevenue } from "../ui";
+import { sparkBar, truncate, formatRevenue, parsePeriod } from "../ui";
 
 export const referrersCommand = new Command("referrers")
   .description("Top referrers")
@@ -25,7 +25,7 @@ export const referrersCommand = new Command("referrers")
 
     const dateRange = options.start && options.end
       ? [options.start, options.end] as [string, string]
-      : options.period;
+      : parsePeriod(options.period);
 
     const filters = options.filter
       ? options.filter.map((f: string) => {

package/src/commands/stats.ts

@@ -6,8 +6,8 @@ import { logo, parsePeriod, truncate } from "../ui";
 
 export const statsCommand = new Command("stats")
   .description("Overview stats: pageviews, visitors, bounce rate, revenue")
-  .argument("[period]", "Time period: today, yesterday, week, month, year, 7d, 30d, 90d, 12mo, all", "30d")
   .option("-s, --site <site>", "Site to query")
+  .option("-p, --period <period>", "Time period: today, yesterday, week, month, year, 7d, 30d, 90d, 12mo, all", "30d")
   .option("--start <date>", "Start date (YYYY-MM-DD)")
   .option("--end <date>", "End date (YYYY-MM-DD)")
   .option("-f, --filter <filters...>", "Filters in format 'field:operator:value'")
@@ -15,7 +15,7 @@ export const statsCommand = new Command("stats")
   .option("--no-revenue", "Exclude revenue metrics")
   .option("--json", "Output as JSON")
   .option("-t, --test", "Test mode: query localhost data instead of production")
-  .action(async (period, options) => {
+  .action(async (options) => {
     const site = options.site || (await getDefaultSite());
 
     if (!site) {
@@ -25,7 +25,7 @@ export const statsCommand = new Command("stats")
 
     const dateRange = options.start && options.end
       ? [options.start, options.end] as [string, string]
-      : parsePeriod(period);
+      : parsePeriod(options.period);
 
     const filters = options.filter
       ? options.filter.map((f: string) => {
@@ -65,7 +65,7 @@ export const statsCommand = new Command("stats")
           query(site, { metrics: ["visitors"], dimensions: ["country"], ...breakdownOpts }),
           query(site, { metrics: ["visitors"], dimensions: ["browser"], ...breakdownOpts }),
           query(site, { metrics: ["visitors"], dimensions: ["utm_source"], ...breakdownOpts }),
-          listEvents(site, typeof dateRange === "string" ? dateRange : "30d", 10, options.test || false)
+          listEvents(site, dateRange, 10, options.test || false)
         );
       }
 

package/src/commands/trend.ts

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import chalk from "chalk";
 import { query, formatNumber } from "../api";
 import { getDefaultSite } from "../config";
-import { coloredSparkline } from "../ui";
+import { coloredSparkline, parsePeriod } from "../ui";
 
 export const trendCommand = new Command("trend")
   .description("Daily visitor trend")
@@ -25,7 +25,7 @@ export const trendCommand = new Command("trend")
 
     const dateRange = options.start && options.end
       ? [options.start, options.end] as [string, string]
-      : options.period;
+      : parsePeriod(options.period);
 
     // Parse filters
     const filters = options.filter

package/src/index.ts

@@ -5,6 +5,7 @@ import { annotationsCommand } from "./commands/annotations"
 import { completionsCommand } from "./commands/completions"
 import { countriesCommand } from "./commands/countries"
 import { eventsCommand } from "./commands/events"
+import { funnelsCommand } from "./commands/funnels"
 import { initCommand } from "./commands/init"
 import { journeysCommand } from "./commands/journeys"
 import { loginCommand } from "./commands/login"
@@ -60,6 +61,7 @@ program.addCommand(countriesCommand)
 program.addCommand(trendCommand)
 program.addCommand(queryCommand)
 program.addCommand(eventsCommand)
+program.addCommand(funnelsCommand)
 program.addCommand(journeysCommand)
 program.addCommand(realtimeCommand)
 program.addCommand(annotationsCommand)

package/src/ui.ts

@@ -44,9 +44,25 @@ export function parsePeriod(period: string): string | [string, string] {
       const endOfLastMonth = new Date(today.getFullYear(), today.getMonth(), 0);
       return [yyyy(startOfLastMonth), yyyy(endOfLastMonth)];
     }
-    default:
-      // Return as-is for 7d, 30d, etc.
+    default: {
+      // Parse arbitrary periods: Nd (days), Nmo (months)
+      const daysMatch = period.match(/^(\d+)d$/i);
+      if (daysMatch) {
+        const days = parseInt(daysMatch[1]);
+        const start = new Date(today);
+        start.setDate(today.getDate() - days);
+        return [yyyy(start), yyyy(today)];
+      }
+      const moMatch = period.match(/^(\d+)mo$/i);
+      if (moMatch) {
+        const months = parseInt(moMatch[1]);
+        const start = new Date(today);
+        start.setMonth(today.getMonth() - months);
+        return [yyyy(start), yyyy(today)];
+      }
+      // "all" or API-recognized strings
       return period;
+    }
   }
 }