feat: allow configuring HTTP timeout via APIDRIFT_TIMEOUT_MS env var

README.md

@@ -432,6 +432,59 @@ Options:
 | Schema engine | custom (zero dependencies) |
 | Diff engine   | custom recursive differ    |
 
+## Environment Variables
+
+| Variable | Default | Description |
+| -------- | ------- | ----------- |
+| `STAGING_TOKEN` | — | Auth token interpolated into `${STAGING_TOKEN}` in your config |
+| `PROD_TOKEN` | — | Auth token interpolated into `${PROD_TOKEN}` in your config |
+| `APIDRIFT_TIMEOUT_MS` | `10000` | HTTP request timeout in milliseconds. Increase for slow APIs. |
+
+**Bash / macOS / Linux:**
+```bash
+export APIDRIFT_TIMEOUT_MS=30000
+apidrift snapshot --tag v1.0 --env staging
+```
+
+**PowerShell (Windows):**
+```powershell
+$env:APIDRIFT_TIMEOUT_MS = "30000"
+apidrift snapshot --tag v1.0 --env staging
+```
+
+---
+
+## Troubleshooting
+
+### Requests time out on slow APIs
+
+If you see `ECONNABORTED` or `ETIMEDOUT` errors, your API is responding slower than the default 10-second timeout. Set `APIDRIFT_TIMEOUT_MS` to a larger value:
+
+```bash
+APIDRIFT_TIMEOUT_MS=60000 apidrift snapshot --tag v1.0 --env staging
+```
+
+### `Authorization` header shows `Bearer ` (empty token)
+
+This means your `${STAGING_TOKEN}` or `${PROD_TOKEN}` env var is not set. Verify:
+
+```bash
+# Bash / macOS / Linux
+echo $STAGING_TOKEN
+
+# PowerShell (Windows)
+echo $env:STAGING_TOKEN
+```
+
+If empty, create a `.env` file in your project directory:
+
+```bash
+STAGING_TOKEN=your_actual_token_here
+PROD_TOKEN=your_actual_token_here
+```
+
+Make sure `.env` is listed in your `.gitignore` so tokens are never committed.
+
 ---
 
 ## License

src/commands/init.js

@@ -28,6 +28,21 @@ export async function runInit() {
       initial: false,
     });
     if (!overwrite) {
+      console.log(chalk.yellow("✖ Keeping existing apidrift.config.json"));
+      console.log("");
+      console.log("  Your current config was not modified. Next steps:");
+      console.log(
+        `  1. Make sure you have a ${chalk.cyan(".env")} file with your tokens:`
+      );
+      console.log(`     ${chalk.gray("STAGING_TOKEN=your_token_here")}`);
+      console.log(`     ${chalk.gray("PROD_TOKEN=your_token_here")}`);
+      console.log(
+        `  2. Add ${chalk.cyan(".env")} to your ${chalk.cyan(".gitignore")} to keep tokens out of git`
+      );
+      console.log(
+        `  3. Run: ${chalk.cyan("apidrift snapshot --tag v1.0 --env staging")}`
+      );
+      console.log("");
       return;
     }
   }

src/core/fetcher.js

@@ -7,6 +7,19 @@ const RETRY_DEFAULTS = {
   maxDelay: 8000,
 };
 
+/**
+ * HTTP request timeout in milliseconds.
+ * Override via the APIDRIFT_TIMEOUT_MS environment variable.
+ * Defaults to 10000 (10 seconds) if unset or if the value is not a positive integer.
+ */
+const DEFAULT_TIMEOUT_MS = 10000;
+const TIMEOUT_MS = (() => {
+  const raw = process.env.APIDRIFT_TIMEOUT_MS;
+  if (!raw) return DEFAULT_TIMEOUT_MS;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_TIMEOUT_MS;
+})();
+
 let didWarnEmptyAuth = false;
 
 function isRetryable(err) {
@@ -29,7 +42,7 @@ async function fetchWithRetry(
   config = RETRY_DEFAULTS,
 ) {
   try {
-    return await axios({ ...options, url, timeout: 10000 });
+    return await axios({ ...options, url, timeout: TIMEOUT_MS });
   } catch (err) {
     if (attempt < config.retries && isRetryable(err)) {
       const delay = Math.min(

src/storage/snapshotStore.js

@@ -26,5 +26,6 @@ export function listSnapshots() {
   return fs
     .readdirSync(SNAP_DIR)
     .filter((f) => f.endsWith(".json"))
-    .map((f) => f.replace(".json", ""));
+    .map((f) => f.replace(".json", ""))
+    .sort();
 }