Improve e2e-cli setup: Python resolution and devbox docs

- Resolve python via activated venv/devbox, fall back to python3 - Use $PYTHON -m pip instead of bare pip (fixes macOS/nix where pip is not on PATH) - Add devbox setup as recommended path in README, with venv fallback instructions
MichaelGHSeg · Sep 23, 2026 · Feb 12, 2026 · Feb 12, 2026 · Feb 12, 2026 · Feb 18, 2026
commit 8c5680a2c43da8b339a56f74a71a140221c2871d
diff --git a/e2e-cli/README.md b/e2e-cli/README.md
@@ -2,17 +2,35 @@
 
 E2E test CLI for the [analytics-python](https://github.com/segmentio/analytics-python) SDK. Accepts a JSON input describing events and SDK configuration, sends them through the real SDK, and outputs results as JSON.
 
-## Setup
+## Running E2E tests
+
+### With devbox (recommended)
+
+```bash
+# From repo root — activates Python 3.12 and installs deps automatically
+devbox shell
+
+# Then from e2e-cli dir:
+./run-e2e.sh
+```
+
+### Without devbox
+
+Requires Python 3.9+ and Node.js 18+. Using a virtualenv is strongly recommended since macOS system Python is externally managed.
 
 ```bash
-cd e2e-cli
 python3 -m venv .venv
 source .venv/bin/activate
-pip install -r requirements.txt
-pip install -e .
+./run-e2e.sh
+```
+
+### Override sdk-e2e-tests location
+
+```bash
+E2E_TESTS_DIR=../my-e2e-tests ./run-e2e.sh
 ```
 
-## Usage
+## Manual CLI usage
 
 ```bash
 e2e-cli --input '{"writeKey":"...", ...}'
@@ -21,7 +39,7 @@ e2e-cli --input '{"writeKey":"...", ...}'
 Or without installing:
 
 ```bash
-python3 -m src.cli --input '{"writeKey":"...", ...}'
+python3 src/cli.py --input '{"writeKey":"...", ...}'
 ```
 
 ## Input Format

diff --git a/e2e-cli/run-e2e.sh b/e2e-cli/run-e2e.sh
@@ -2,7 +2,9 @@
 #
 # Run E2E tests for analytics-python
 #
-# Prerequisites: Python 3, pip, Node.js 18+
+# Prerequisites: Node.js 18+ and one of:
+#   - devbox (recommended): run `devbox shell` first, then ./run-e2e.sh
+#   - Python 3.9+ with a virtualenv already activated
 #
 # Usage:
 #   ./run-e2e.sh [extra args passed to run-tests.sh]
@@ -17,15 +19,25 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 SDK_ROOT="$SCRIPT_DIR/.."
 E2E_DIR="${E2E_TESTS_DIR:-$SDK_ROOT/../sdk-e2e-tests}"
 
+# Resolve python and pip — prefer activated venv/devbox python, fall back to python3
+PYTHON="${PYTHON:-$(command -v python || command -v python3)}"
+PIP="$PYTHON -m pip"
+
+if [[ -z "$PYTHON" ]]; then
+    echo "Error: Python not found. Run 'devbox shell' first or activate a virtualenv."
+    exit 1
+fi
+
 echo "=== Building analytics-python e2e-cli ==="
+echo "Using Python: $PYTHON"
 
 # Install SDK
 cd "$SDK_ROOT"
-pip install -e .
+$PIP install -e . -q
 
 # Install e2e-cli
 cd "$SCRIPT_DIR"
-pip install -e .
+$PIP install -e . -q
 
 echo ""