feature(Preview): Add --preview flag for free preview dataset access

README.md

@@ -42,6 +42,8 @@ export APERIODIC_API_KEY=your_api_key
 
 Get your API key at [aperiodic.io](https://aperiodic.io).
 
+For [preview data](#preview-data) (`--preview`), no API key is required — the CLI uses the shared public demo key automatically.
+
 ## Usage
 
 ```
@@ -104,6 +106,7 @@ The first argument is the metric name. Use `symbols` to list available symbols f
 | `--output-dir`     |                   | Output directory for Parquet files (required) |
 | `--timestamp`      | `exchange`        | Timestamp source (`exchange` or `true`)       |
 | `--max-concurrent` | `10`              | Maximum concurrent downloads                  |
+| `--preview`        | `false`           | Query the free preview dataset (no subscription; whitelisted parameters only) |
 
 ## Examples
 
@@ -145,6 +148,21 @@ aperiodic basis \
   --output-dir ./data
 ```
 
+**Preview data (no API key required):**
+```bash
+aperiodic ohlcv --preview \
+  --exchange binance-futures \
+  --symbol perpetual-BTC-USDT:USDT \
+  --interval 5m \
+  --start-date 2025-05-01 \
+  --end-date 2025-05-31 \
+  --output-dir ./data
+```
+
+## Preview data
+
+`--preview` fetches a free, curated slice of data from the preview endpoint — no subscription and no API key required (the shared public demo key is used automatically). Requests must match one of the whitelisted parameter combinations (exchange, symbol, interval, timestamp, date range) listed at [aperiodic.io/catalog](https://aperiodic.io/catalog#preview).
+
 ## Supported Exchanges
 
 | Exchange              | ID                   |

cli.go

@@ -33,14 +33,6 @@ func (c *CLI) Run(args []string) int {
 		return 0
 	}
 
-	apiKey := c.Env("APERIODIC_API_KEY")
-	if apiKey == "" {
-		fmt.Fprintln(c.Stderr, "Error: APERIODIC_API_KEY environment variable not set")
-		return 1
-	}
-
-	client := NewAperiodicClient(apiKey)
-
 	fs := flag.NewFlagSet("aperiodic", flag.ContinueOnError)
 	fs.SetOutput(c.Stderr)
 
@@ -52,11 +44,25 @@ func (c *CLI) Run(args []string) int {
 	maxConcurrentFlag := fs.Int("max-concurrent", 10, "Maximum concurrent downloads")
 	timestampFlag := fs.String("timestamp", "exchange", "Timestamp source (exchange, true)")
 	outputDirFlag := fs.String("output-dir", "", "Output directory for Parquet files (mandatory)")
+	previewFlag := fs.Bool("preview", false, "Query the free preview dataset (no subscription; whitelisted parameters only)")
 
 	if err := fs.Parse(args[1:]); err != nil {
 		return 2
 	}
 
+	apiKey := c.Env("APERIODIC_API_KEY")
+	if apiKey == "" {
+		if *previewFlag {
+			// Preview data is served against the shared demo key, so no key is required.
+			apiKey = DemoAPIKey
+		} else {
+			fmt.Fprintln(c.Stderr, "Error: APERIODIC_API_KEY environment variable not set (pass --preview to use the shared demo key)")
+			return 1
+		}
+	}
+
+	client := NewAperiodicClient(apiKey)
+
 	if cmd == "symbols" {
 		return c.handleSymbols(client, *exchangeFlag)
 	}
@@ -66,7 +72,7 @@ func (c *CLI) Run(args []string) int {
 		return 1
 	}
 
-	return c.handleData(client, cmd, *timestampFlag, *intervalFlag, *exchangeFlag, *symbolFlag, *startDateFlag, *endDateFlag, *maxConcurrentFlag, *outputDirFlag)
+	return c.handleData(client, cmd, *timestampFlag, *intervalFlag, *exchangeFlag, *symbolFlag, *startDateFlag, *endDateFlag, *maxConcurrentFlag, *outputDirFlag, *previewFlag)
 }
 
 func (c *CLI) printUsage() {
@@ -102,7 +108,7 @@ func (c *CLI) printUsage() {
 	fmt.Fprintln(c.Stdout, "  help     Show this help")
 	fmt.Fprintln(c.Stdout)
 	fmt.Fprintln(c.Stdout, "Environment:")
-	fmt.Fprintln(c.Stdout, "  APERIODIC_API_KEY  Aperiodic API key (required)")
+	fmt.Fprintln(c.Stdout, "  APERIODIC_API_KEY  Aperiodic API key (required, except with --preview)")
 	fmt.Fprintln(c.Stdout)
 	fmt.Fprintln(c.Stdout, "Flags:")
 	fmt.Fprintln(c.Stdout, "  -end-date string")
@@ -115,6 +121,8 @@ func (c *CLI) printUsage() {
 	fmt.Fprintln(c.Stdout, "        Maximum concurrent downloads (default 10)")
 	fmt.Fprintln(c.Stdout, "  -output-dir string")
 	fmt.Fprintln(c.Stdout, "        Output directory for Parquet files (mandatory)")
+	fmt.Fprintln(c.Stdout, "  -preview")
+	fmt.Fprintln(c.Stdout, "        Query the free preview dataset (no subscription; whitelisted parameters only)")
 	fmt.Fprintln(c.Stdout, "  -start-date string")
 	fmt.Fprintln(c.Stdout, "        Start date (YYYY-MM-DD)")
 	fmt.Fprintln(c.Stdout, "  -symbol string")
@@ -137,7 +145,7 @@ func (c *CLI) handleSymbols(client *AperiodicClient, exchange string) int {
 	return 0
 }
 
-func (c *CLI) handleData(client *AperiodicClient, metric, timestamp, interval, exchange, symbol, startDate, endDate string, maxConcurrent int, outputDir string) int {
+func (c *CLI) handleData(client *AperiodicClient, metric, timestamp, interval, exchange, symbol, startDate, endDate string, maxConcurrent int, outputDir string, preview bool) int {
 	if symbol == "" {
 		fmt.Fprintln(c.Stderr, "Error: --symbol is required")
 		return 1
@@ -147,7 +155,7 @@ func (c *CLI) handleData(client *AperiodicClient, metric, timestamp, interval, e
 		return 1
 	}
 
-	resp, err := client.FetchPresignedUrls(metric, TimestampType(timestamp), Interval(interval), exchange, symbol, startDate, endDate)
+	resp, err := client.FetchPresignedUrls(metric, TimestampType(timestamp), Interval(interval), exchange, symbol, startDate, endDate, preview)
 	if err != nil {
 		fmt.Fprintf(c.Stderr, "Error fetching file URLs: %v\n", err)
 		return 1

client.go

@@ -13,6 +13,10 @@ import (
 const (
 	DefaultBaseURL = "https://aperiodic.io/api/v1"
 	DefaultTimeout = 60 * time.Second
+
+	// DemoAPIKey is the shared public demo key. Preview data is served against
+	// it, so users can query the whitelisted preview slice without signing up.
+	DemoAPIKey = "DEMO-KEY"
 )
 
 type APIError struct {
@@ -130,8 +134,13 @@ func (c *AperiodicClient) GetSymbols(exchange string) ([]string, error) {
 	return symResp.Symbols, nil
 }
 
-func (c *AperiodicClient) FetchPresignedUrls(bucket string, timestamp TimestampType, interval Interval, exchange string, symbol string, startDate string, endDate string) (*AggregateDataResponse, error) {
-	u, err := url.Parse(fmt.Sprintf("%s/data/%s", c.BaseURL, bucket))
+func (c *AperiodicClient) FetchPresignedUrls(bucket string, timestamp TimestampType, interval Interval, exchange string, symbol string, startDate string, endDate string, preview bool) (*AggregateDataResponse, error) {
+	dataPath := fmt.Sprintf("%s/data/%s", c.BaseURL, bucket)
+	if preview {
+		dataPath = fmt.Sprintf("%s/data/preview/%s", c.BaseURL, bucket)
+	}
+
+	u, err := url.Parse(dataPath)
 	if err != nil {
 		return nil, err
 	}

client_test.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"strings"
@@ -127,6 +128,82 @@ func TestCLI_MetricMissingOutputDir(t *testing.T) {
 	}
 }
 
+// captureCLIRequest runs the CLI against a stub server and reports the request
+// path and X-API-KEY header it received. --output-dir is appended for the
+// caller. APERIODIC_API_KEY is set to apiKeyEnv (use "" for an unset key).
+func captureCLIRequest(t *testing.T, apiKeyEnv string, args ...string) (path, key string, exitCode int, stderr string) {
+	t.Helper()
+
+	var gotPath, gotKey string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		gotKey = r.Header.Get("X-API-KEY")
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"files": []}`))
+	}))
+	defer srv.Close()
+
+	t.Setenv("APERIODIC_API_URL", srv.URL)
+	t.Setenv("APERIODIC_API_KEY", apiKeyEnv)
+
+	fullArgs := append(args, "-output-dir", t.TempDir())
+	_, errStr, code := runCLI(fullArgs...)
+	return gotPath, gotKey, code, errStr
+}
+
+var previewArgs = []string{
+	"ohlcv", "-preview",
+	"-exchange", "binance-futures",
+	"-symbol", "perpetual-BTC-USDT:USDT",
+	"-interval", "5m",
+	"-start-date", "2025-05-01",
+	"-end-date", "2025-05-31",
+}
+
+func TestCLI_Preview_NoAPIKeyUsesDemoKey(t *testing.T) {
+	path, key, code, stderr := captureCLIRequest(t, "", previewArgs...)
+	if code != 0 {
+		t.Fatalf("expected exit code 0, got %d; stderr: %s", code, stderr)
+	}
+	if key != DemoAPIKey {
+		t.Errorf("expected X-API-KEY %q, got %q", DemoAPIKey, key)
+	}
+	if path != "/data/preview/ohlcv" {
+		t.Errorf("expected preview path, got %q", path)
+	}
+}
+
+func TestCLI_Preview_KeepsProvidedAPIKey(t *testing.T) {
+	path, key, code, stderr := captureCLIRequest(t, "real-key", previewArgs...)
+	if code != 0 {
+		t.Fatalf("expected exit code 0, got %d; stderr: %s", code, stderr)
+	}
+	if key != "real-key" {
+		t.Errorf("expected provided key to be used, got %q", key)
+	}
+	if path != "/data/preview/ohlcv" {
+		t.Errorf("expected preview path, got %q", path)
+	}
+}
+
+func TestCLI_NoPreviewUsesDataPath(t *testing.T) {
+	args := []string{
+		"ohlcv",
+		"-exchange", "binance-futures",
+		"-symbol", "perpetual-BTC-USDT:USDT",
+		"-interval", "5m",
+		"-start-date", "2025-05-01",
+		"-end-date", "2025-05-31",
+	}
+	path, _, code, stderr := captureCLIRequest(t, "real-key", args...)
+	if code != 0 {
+		t.Fatalf("expected exit code 0, got %d; stderr: %s", code, stderr)
+	}
+	if path != "/data/ohlcv" {
+		t.Errorf("expected non-preview path, got %q", path)
+	}
+}
+
 // Tests that always run (no API key needed) — match Python client pattern
 // where invalid-key tests run unconditionally and assert specific error codes.