diff --git a/README.md b/README.md
index d066004..3eb2684 100644
--- a/README.md
+++ b/README.md
@@ -207,7 +207,7 @@ python3 -m pip install google-api-python-client google-auth-oauthlib python-dote
 
 ### First run (OAuth)
 
-Run once manually to complete OAuth2 login and create `token.json` in the repo root:
+Run once manually to complete OAuth2 login (local server flow) and create `token.json` in the repo root. When prompted, open the printed `http://localhost:<port>/` URL in a browser on the same machine (or via SSH port forwarding), approve access, and wait for the terminal to confirm the token was saved:
 
 ```sh
 python3 scripts/calendash-api.py
diff --git a/scripts/calendash-api.py b/scripts/calendash-api.py
index fe88371..35f34c1 100755
--- a/scripts/calendash-api.py
+++ b/scripts/calendash-api.py
@@ -109,12 +109,16 @@ def get_credentials(client_id: str, client_secret: str, token_path: Path) -> Cre
         save_credentials(creds, token_path)
         return creds
 
-    logging.info("Starting first-run OAuth flow (console mode).")
+    logging.info("Starting first-run OAuth flow.")
     flow = InstalledAppFlow.from_client_config(
         build_client_config(client_id, client_secret),
         SCOPES,
     )
-    creds = flow.run_console()
+    try:
+        creds = flow.run_local_server(port=0, open_browser=False)
+    except Exception as exc:
+        logging.info("Local server auth failed (%s); falling back to console flow.", exc)
+        creds = flow.run_console()
     save_credentials(creds, token_path)
     return creds