appwrite-utils-cli 1.7.1 → 1.7.3

package/dist/config/ConfigManager.js

@@ -149,9 +149,26 @@ export class ConfigManager {
         logger.debug(`Config discovered at: ${configPath}`, { prefix: "ConfigManager" });
         // 3. Load config from file
         let config = await this.loaderService.loadFromPath(configPath);
-        // 4. Load session authentication
-        const session = options.sessionOverride ||
-            (await this.sessionService.findSession(config.appwriteEndpoint, config.appwriteProject));
+        // 4. Load session authentication (only if appropriate based on config)
+        // Determine if we should load session:
+        // - Load if authMethod is explicitly "session"
+        // - Load if authMethod is "auto" or undefined AND no API key exists
+        // - Skip if authMethod is "apikey" or if API key is present with "auto" mode
+        const hasApiKey = !!(config.appwriteKey && config.appwriteKey.trim().length > 0);
+        const authMethod = config.authMethod || "auto";
+        const shouldLoadSession = options.sessionOverride !== undefined ||
+            authMethod === "session" ||
+            (authMethod === "auto" && !hasApiKey);
+        logger.debug("Session loading decision", {
+            prefix: "ConfigManager",
+            hasApiKey,
+            authMethod,
+            shouldLoadSession,
+        });
+        const session = shouldLoadSession
+            ? options.sessionOverride ||
+                (await this.sessionService.findSession(config.appwriteEndpoint, config.appwriteProject))
+            : null;
         // 5. Merge session into config
         if (session) {
             logger.debug("Merging session authentication into config", { prefix: "ConfigManager" });

package/dist/config/services/ConfigMergeService.js

@@ -57,7 +57,11 @@ export class ConfigMergeService {
         const merged = cloneDeep(config);
         // Add session authentication (map 'cookie' to 'sessionCookie')
         merged.sessionCookie = session.cookie;
-        merged.authMethod = "session";
+        // Only set authMethod to "session" if not explicitly set to "apikey"
+        // This allows API key authentication to take priority when both are available
+        if (merged.authMethod !== "apikey") {
+            merged.authMethod = "session";
+        }
         // Add session metadata if available
         if (session.email || session.expiresAt) {
             merged.sessionMetadata = {

package/dist/utils/ClientFactory.js

@@ -60,32 +60,75 @@ export class ClientFactory {
         const client = new Client()
             .setEndpoint(config.appwriteEndpoint)
             .setProject(config.appwriteProject);
-        // Apply authentication (priority already resolved by ConfigManager)
-        if (config.sessionCookie) {
-            // Session authentication (from ConfigManager's session loading)
-            client.setSession(config.sessionCookie);
-            logger.debug("Applied session authentication to client", {
+        // Apply authentication based on authMethod preference
+        const authMethod = config.authMethod || "auto";
+        logger.debug("Applying authentication", {
+            prefix: "ClientFactory",
+            authMethod,
+            hasApiKey: !!config.appwriteKey,
+            hasSession: !!config.sessionCookie,
+        });
+        if (authMethod === "apikey") {
+            // Explicit API key preference - use only API key
+            if (!config.appwriteKey || config.appwriteKey.trim().length === 0) {
+                const error = new Error("authMethod set to 'apikey' but no API key provided.\n\n" +
+                    "Either:\n" +
+                    "  - Set appwriteKey in your config file\n" +
+                    "  - Provide --apiKey flag\n" +
+                    "  - Set APPWRITE_API_KEY environment variable");
+                logger.error("Failed to create client - API key required", { prefix: "ClientFactory" });
+                throw error;
+            }
+            client.setKey(config.appwriteKey);
+            logger.debug("Applied API key authentication (explicit preference)", {
                 prefix: "ClientFactory",
-                email: config.sessionMetadata?.email,
             });
         }
-        else if (config.appwriteKey) {
-            // API key authentication (from config file or overrides)
-            client.setKey(config.appwriteKey);
-            logger.debug("Applied API key authentication to client", {
+        else if (authMethod === "session") {
+            // Explicit session preference - use only session
+            if (!config.sessionCookie) {
+                const error = new Error("authMethod set to 'session' but no session cookie available.\n\n" +
+                    "Either:\n" +
+                    "  - Run 'appwrite login' to create a session\n" +
+                    "  - Change authMethod to 'apikey' or 'auto'\n" +
+                    "  - Provide --sessionCookie flag");
+                logger.error("Failed to create client - session required", { prefix: "ClientFactory" });
+                throw error;
+            }
+            client.setSession(config.sessionCookie);
+            logger.debug("Applied session authentication (explicit preference)", {
                 prefix: "ClientFactory",
+                email: config.sessionMetadata?.email,
             });
         }
         else {
-            // No authentication available - this should have been caught by ConfigManager
-            const error = new Error("No authentication method available in configuration.\n\n" +
-                "This should have been resolved by ConfigManager during config loading.\n" +
-                "Expected either:\n" +
-                "  - config.sessionCookie (from session authentication)\n" +
-                "  - config.appwriteKey (from config file or CLI overrides)\n\n" +
-                "Suggestion: Ensure ConfigManager.loadConfig() was called before ClientFactory.createFromConfig().");
-            logger.error("Failed to create client - no authentication", { prefix: "ClientFactory" });
-            throw error;
+            // Auto mode: Prefer API key if present, fallback to session
+            if (config.appwriteKey && config.appwriteKey.trim().length > 0) {
+                client.setKey(config.appwriteKey);
+                logger.debug("Applied API key authentication (auto mode - preferred)", {
+                    prefix: "ClientFactory",
+                });
+            }
+            else if (config.sessionCookie) {
+                client.setSession(config.sessionCookie);
+                logger.debug("Applied session authentication (auto mode - fallback)", {
+                    prefix: "ClientFactory",
+                    email: config.sessionMetadata?.email,
+                });
+            }
+            else {
+                // No authentication available
+                const error = new Error("No authentication method available in configuration.\n\n" +
+                    "Expected either:\n" +
+                    "  - config.appwriteKey (from config file, CLI flags, or environment)\n" +
+                    "  - config.sessionCookie (from session authentication)\n\n" +
+                    "Suggestion:\n" +
+                    "  - Add appwriteKey to your config file, OR\n" +
+                    "  - Run 'appwrite login' to create a session, OR\n" +
+                    "  - Provide --apiKey flag");
+                logger.error("Failed to create client - no authentication", { prefix: "ClientFactory" });
+                throw error;
+            }
         }
         // Create adapter with version detection
         // AdapterFactory uses internal caching, so repeated calls are fast

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appwrite-utils-cli",
   "description": "Appwrite Utility Functions to help with database management, data conversion, data import, migrations, and much more. Meant to be used as a CLI tool, I do not recommend installing this in frontend environments.",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "main": "src/main.ts",
   "type": "module",
   "repository": {

package/src/config/ConfigManager.ts

@@ -249,10 +249,30 @@ export class ConfigManager {
     // 3. Load config from file
     let config = await this.loaderService.loadFromPath(configPath);
 
-    // 4. Load session authentication
-    const session =
-      options.sessionOverride ||
-      (await this.sessionService.findSession(config.appwriteEndpoint, config.appwriteProject));
+    // 4. Load session authentication (only if appropriate based on config)
+    // Determine if we should load session:
+    // - Load if authMethod is explicitly "session"
+    // - Load if authMethod is "auto" or undefined AND no API key exists
+    // - Skip if authMethod is "apikey" or if API key is present with "auto" mode
+    const hasApiKey = !!(config.appwriteKey && config.appwriteKey.trim().length > 0);
+    const authMethod = config.authMethod || "auto";
+
+    const shouldLoadSession =
+      options.sessionOverride !== undefined ||
+      authMethod === "session" ||
+      (authMethod === "auto" && !hasApiKey);
+
+    logger.debug("Session loading decision", {
+      prefix: "ConfigManager",
+      hasApiKey,
+      authMethod,
+      shouldLoadSession,
+    });
+
+    const session = shouldLoadSession
+      ? options.sessionOverride ||
+        (await this.sessionService.findSession(config.appwriteEndpoint, config.appwriteProject))
+      : null;
 
     // 5. Merge session into config
     if (session) {

package/src/config/services/ConfigMergeService.ts

@@ -80,7 +80,12 @@ export class ConfigMergeService {
 
     // Add session authentication (map 'cookie' to 'sessionCookie')
     merged.sessionCookie = session.cookie;
-    merged.authMethod = "session";
+
+    // Only set authMethod to "session" if not explicitly set to "apikey"
+    // This allows API key authentication to take priority when both are available
+    if (merged.authMethod !== "apikey") {
+      merged.authMethod = "session";
+    }
 
     // Add session metadata if available
     if (session.email || session.expiresAt) {

package/src/utils/ClientFactory.ts

@@ -67,32 +67,81 @@ export class ClientFactory {
       .setEndpoint(config.appwriteEndpoint)
       .setProject(config.appwriteProject);
 
-    // Apply authentication (priority already resolved by ConfigManager)
-    if (config.sessionCookie) {
-      // Session authentication (from ConfigManager's session loading)
-      client.setSession(config.sessionCookie);
-      logger.debug("Applied session authentication to client", {
+    // Apply authentication based on authMethod preference
+    const authMethod = config.authMethod || "auto";
+
+    logger.debug("Applying authentication", {
+      prefix: "ClientFactory",
+      authMethod,
+      hasApiKey: !!config.appwriteKey,
+      hasSession: !!config.sessionCookie,
+    });
+
+    if (authMethod === "apikey") {
+      // Explicit API key preference - use only API key
+      if (!config.appwriteKey || config.appwriteKey.trim().length === 0) {
+        const error = new Error(
+          "authMethod set to 'apikey' but no API key provided.\n\n" +
+          "Either:\n" +
+          "  - Set appwriteKey in your config file\n" +
+          "  - Provide --apiKey flag\n" +
+          "  - Set APPWRITE_API_KEY environment variable"
+        );
+        logger.error("Failed to create client - API key required", { prefix: "ClientFactory" });
+        throw error;
+      }
+      client.setKey(config.appwriteKey);
+      logger.debug("Applied API key authentication (explicit preference)", {
         prefix: "ClientFactory",
-        email: config.sessionMetadata?.email,
       });
-    } else if (config.appwriteKey) {
-      // API key authentication (from config file or overrides)
-      client.setKey(config.appwriteKey);
-      logger.debug("Applied API key authentication to client", {
+
+    } else if (authMethod === "session") {
+      // Explicit session preference - use only session
+      if (!config.sessionCookie) {
+        const error = new Error(
+          "authMethod set to 'session' but no session cookie available.\n\n" +
+          "Either:\n" +
+          "  - Run 'appwrite login' to create a session\n" +
+          "  - Change authMethod to 'apikey' or 'auto'\n" +
+          "  - Provide --sessionCookie flag"
+        );
+        logger.error("Failed to create client - session required", { prefix: "ClientFactory" });
+        throw error;
+      }
+      client.setSession(config.sessionCookie);
+      logger.debug("Applied session authentication (explicit preference)", {
         prefix: "ClientFactory",
+        email: config.sessionMetadata?.email,
       });
+
     } else {
-      // No authentication available - this should have been caught by ConfigManager
-      const error = new Error(
-        "No authentication method available in configuration.\n\n" +
-        "This should have been resolved by ConfigManager during config loading.\n" +
-        "Expected either:\n" +
-        "  - config.sessionCookie (from session authentication)\n" +
-        "  - config.appwriteKey (from config file or CLI overrides)\n\n" +
-        "Suggestion: Ensure ConfigManager.loadConfig() was called before ClientFactory.createFromConfig()."
-      );
-      logger.error("Failed to create client - no authentication", { prefix: "ClientFactory" });
-      throw error;
+      // Auto mode: Prefer API key if present, fallback to session
+      if (config.appwriteKey && config.appwriteKey.trim().length > 0) {
+        client.setKey(config.appwriteKey);
+        logger.debug("Applied API key authentication (auto mode - preferred)", {
+          prefix: "ClientFactory",
+        });
+      } else if (config.sessionCookie) {
+        client.setSession(config.sessionCookie);
+        logger.debug("Applied session authentication (auto mode - fallback)", {
+          prefix: "ClientFactory",
+          email: config.sessionMetadata?.email,
+        });
+      } else {
+        // No authentication available
+        const error = new Error(
+          "No authentication method available in configuration.\n\n" +
+          "Expected either:\n" +
+          "  - config.appwriteKey (from config file, CLI flags, or environment)\n" +
+          "  - config.sessionCookie (from session authentication)\n\n" +
+          "Suggestion:\n" +
+          "  - Add appwriteKey to your config file, OR\n" +
+          "  - Run 'appwrite login' to create a session, OR\n" +
+          "  - Provide --apiKey flag"
+        );
+        logger.error("Failed to create client - no authentication", { prefix: "ClientFactory" });
+        throw error;
+      }
     }
 
     // Create adapter with version detection