Command Line Interface (CLI)

SpotLift provides a full-featured Command Line Interface (CLI) for running attribution passes, pre-flight data quality audits, constrained budget optimization, and generating production clean-room SQL.

---

1. Quick Reference

# Run the instant interactive terminal demo
spotlift demo

# Run pre-flight schema, cadence, and collision audit
spotlift preflight --spots schaltplan.csv --web ga4_minutes.parquet

# Run causal attribution across broadcast airings, GA4, and Amazon
spotlift run --spots schaltplan.csv --web ga4_minutes.parquet --out results.csv

# Solve constrained budget reallocation with diminishing returns
spotlift optimize --spots results.csv --budget 500000 --max-shift 0.35 --scenarios

# Export period-aligned MMM calibration data (PyMC, Meridian, Robyn)
spotlift mmm --spots results.csv --target all --out-dir ./mmm_export

# Generate BigQuery GA4 or Amazon Marketing Cloud (AMC) extraction SQL
spotlift sql --source ga4 --project my-gcp-project --dataset analytics_12345
spotlift sql --source amc --start 2026-03-01 --end 2026-03-21

# Authenticate SpotLift Pro license
spotlift auth --key SL_PRO_...

---

2. Command Details

spotlift demo

Executes an instant attribution pass on a synthetic benchmark campaign with zero external credentials or API keys required.

spotlift demo --scenario dach --spots 600 --days 14 --out-dir ./demo_data

Flag	Type	Default	Description
--scenario, -sc	String	dach	Scenario: dach (National + 36h AMC lag), amc (Omnichannel Clean Room), or us-state (Regional).
--spots, -s	Integer	600	Number of TV broadcast airings to generate.
--days, -d	Integer	14	Flight duration in days.
--out-dir, -o	Path	./demo_data	Target directory to export benchmark CSVs and parquet files.

---

spotlift preflight / validate-inputs

Performs non-destructive validation of timestamps, UTC normalization, sample rate cadence, zero-gap detection, and collision severity before launching production attribution passes.

spotlift preflight --spots tv_airings.csv --web ga4_minute_sessions.parquet --tz Europe/Berlin

Flag	Type	Default	Description
--spots, -s	Path	Required	Path to TV broadcast schedule (Schaltplan).
--web, -w	Path	Required	Path to GA4 minute-level sessions.
--tz, -z	String	UTC	Timezone fallback if timestamps lack explicit offsets.
--window	Integer	8	Post-spot treatment window in minutes.
--json	Flag	false	Outputs machine-readable JSON summary for AI coding agents.

---

spotlift run

Executes the high-frequency attribution engine across broadcast TV, web sessions, and Amazon sales.

spotlift run \
  --spots /path/to/schaltplan.csv \
  --web /path/to/ga4_minutes.parquet \
  --amazon /path/to/amazon_hourly.csv \
  --format all \
  --out /path/to/attributed_spots.csv

Flag	Type	Default	Description
--spots, -s	Path	Required	Path to broadcast airings CSV or Parquet.
--web, -w	Path	Required	Path to GA4 minute-level session CSV or Parquet.
--amazon, -a	Path	None	Optional path to Amazon hourly telemetry CSV/Parquet.
--amc-conversions	Path	None	Optional path to AMC pre/post spot conversions CSV/Parquet.
--window	Integer	8	Post-spot response window in minutes.
--format, -f	String	csv	Export format: csv, markdown, or all.
--out, -o	Path	None	Destination path for attributed spots CSV.
--markdown-out, -m	Path	None	Destination path for executive Markdown report.
--html	Path	None	Path to export interactive HTML report (SpotLift Pro).
--excel	Path	None	Path to export multi-tab agency Excel deck (SpotLift Pro).
--key, -k	String	None	SpotLift Pro license key (can also use SPOTLIFT_API_KEY).

---

spotlift optimize

Solves constrained budget reallocation using diminishing-returns response curves ($R(s)=\alpha s^{\beta }$) and marginal CPIV ($m\text{CPIV}$) equalization.

spotlift optimize \
  --spots /path/to/attributed_spots.csv \
  --budget 500000 \
  --max-shift 0.35 \
  --scenarios \
  --out /path/to/reallocated_budget.csv

Flag	Type	Default	Description
--spots, -s	Path	Required	Path to attributed spots CSV/Parquet (or raw airings if --web is provided).
--web, -w	Path	None	Optional GA4 telemetry path if spots file is not yet attributed.
--mmm	Path	None	Optional path to MMM posterior contributions CSV/Parquet/JSON (Direction 2: MMM → SpotLift Optimizer).
--mmm-adstock	Float	0.0	MMM geometric adstock retention $\lambda \in [0,1)$ when --mmm is provided.
--risk-aversion	Float	0.0	Posterior uncertainty penalty weight ($\ge 0$) when --mmm is provided.
--outcome-overlap	String	unknown	Outcome provenance vs MMM: unknown, independent_stream, or shared_same_series.
--budget, -b	Float	Current Spend	Target total budget (budget-neutral by default).
--max-shift, -m	Float	0.35	Maximum relative budget reallocation allowed per channel ($\pm 35\mathrm{\%}$).
--elasticity, -e	Float	0.70	Diminishing returns elasticity parameter $\beta$ ($0<\beta <1$).
--scenarios	Flag	false	Displays multi-scenario comparison (Conservative, Balanced, Aggressive).
--export-mmm	Path	None	Optional directory to export pymc_causal_lower_bound.csv and pymc_lift_test.csv alongside recommendations.
--json	Flag	false	Outputs machine-readable JSON summary for AI coding agents.
--out, -o	Path	None	Destination path to export recommended budget CSV.

---

spotlift mmm

Exports causal lower-bound datasets (pymc_causal_lower_bound.csv), PyMC potential/latent-share adapters (pymc_lower_bound_model.py), provenance metadata (calibration_provenance.json), and support-matched priors for PyMC-Marketing, Google Meridian, and Meta Robyn.

# Export PyMC causal lower-bound & potential snippet (weekly W-MON grain)
spotlift mmm --spots attributed_spots.csv --target lower-bound --out-dir ./mmm_export

# Export all frameworks with explicit latent-share PyMC adapter & finite-horizon carryover
spotlift mmm \
  --spots attributed_spots.csv \
  --target all \
  --freq W-MON \
  --pymc-mode latent_share \
  --adstock-retention 0.35 \
  --carryover-mode finite_horizon \
  --mmm-channel-name tv_broadcast \
  --out-dir ./mmm_export

Flag	Type	Default	Description
--spots, -s	Path	Required	Path to attributed spots CSV/Parquet (or raw airings if --web is provided).
--web, -w	Path	None	Optional GA4 telemetry path if spots file is not yet attributed.
--target, -t	String	pymc	Target MMM framework: pymc, lower-bound, meridian, robyn, or all.
--out-dir, -o	Path	./mmm_export	Destination folder for calibration files and prior specs.
--freq, -f	String	W-MON	MMM time period frequency (W-MON for weekly or D for daily).
--lift-col, -l	String	incremental_lift	Lift metric (incremental_lift for sessions or key_event_response for conversions).
--adstock-retention, -a	Float	0.0	Optional adstock decay $\lambda \in [0,1)$ (paired with --carryover-mode; default 0.0).
--carryover-mode	String	none	Carryover conversion mode: none (default causal floor), finite_horizon, or infinite_horizon.
--pymc-mode	String	lower_bound	PyMC snippet likelihood: lower_bound (asymmetric floor) or latent_share (learned $\rho$).
--outcome-overlap	String	unknown	Outcome provenance vs MMM: unknown, independent_stream, or shared_same_series.
--mmm-channel-name	String	None	Optional unified TV media column name (e.g. tv_broadcast) to pool collinear stations.
--key, -k	String	None	SpotLift Pro key (for Meridian interchange YAML & Robyn calibration exports).
--json	Flag	false	Outputs machine-readable JSON summary for CI/CD pipelines.

---

spotlift sql

Generates production-tested SQL templates for extracting digital telemetry from Google BigQuery or Amazon Marketing Cloud (AMC).

# GA4 BigQuery SQL
spotlift sql --source ga4 --project my-gcp-project --dataset analytics_12345 --out ga4.sql

# AMC Athena SQL
spotlift sql --source amc --start 2026-03-01 --end 2026-03-21 --out amc.sql

---

spotlift auth

Authenticates and caches your SpotLift Pro license key with Polar.sh and activates compiled engine extensions.

spotlift auth --key SL_PRO_...