capture-auth

Capture Web App Authentication

Save reusable authenticated browser sessions for custom web apps (the user's own projects, client apps, staging environments, etc.) using the persistent Chrome profile at ~/.playwright-cli/.

How This Differs from auth-browse

• auth-browse: Preconfigured external services (Cloudflare, Sentry, Vercel, etc.) with known waitFor patterns
• capture-auth: The user's own apps — custom URLs where the post-login URL needs to be discovered

Both use the same ~/.playwright-cli/sign-in.mjs script and shared Chrome profile.

Workflow

Step 1: Gather app details

Ask the user for:

1. A short name for the app (e.g., deckchecker, seatify-staging, client-portal). Used as the identifier for future sign-ins.
2. The login URL (e.g., https://deckchecker.app/login, https://staging.seatify.app/login).
3. The post-login URL pattern (optional). This is a URL substring that appears after successful sign-in — used for auto-detect. Examples:
   • /dashboard — most common
   • /home
   • /events
   • The app's domain alone if login redirects to a different domain

If the user does not know the post-login URL, suggest common patterns or tell them to skip it (the script will use manual Enter instead).

Step 2: Register the site

Run via Bash:

node ~/.playwright-cli/sign-in.mjs add <name> <login-url> <wait-for-pattern>

Example:

node ~/.playwright-cli/sign-in.mjs add deckchecker https://deckchecker.app/login /dashboard

If no waitFor was provided, omit the third argument — the script defaults to the hostname.

Step 3: Sign in

Tell the user to run the sign-in command in a separate terminal:

node ~/.playwright-cli/sign-in.mjs login <name>

The script defaults to Playwright's built-in Chromium, which works while Chrome is open. Custom apps rarely have bot detection, so this is almost always fine. If the user's app uses Google OAuth for login and it gets blocked, retry with --tier chrome (Chrome must be closed first):

node ~/.playwright-cli/sign-in.mjs login <name> --tier chrome

This is interactive — Claude cannot run it. The user signs in manually. The script auto-detects completion using the waitFor pattern (defaults to the hostname when omitted from add). The user can also press Enter at any time to save manually.

Step 4: Validate and test

After the user confirms sign-in is complete, validate the captured auth:

node ~/.playwright-cli/sign-in.mjs check <name>

Review the output:

• Status: HEALTHY — proceed to test browsing.
• Status: EXPIRED — the capture failed or the session expired before saving. Re-run sign-in.
• Status: DEGRADED — check the warnings. Common issues:
  • "No auth-relevant cookies found" — the app may use httpOnly cookies not captured by storageState, or sign-in wasn't completed before saving.
  • "N session-only cookies will not survive state-load" — this app needs --persistent --profile instead.
  • Supabase session expires in <2h — normal for Supabase, but the profile will need frequent refresh.

If the app uses Supabase (look for sb-*-auth-token in the check output), note the real session TTL. Supabase access tokens typically expire in 1 hour — inform the user that profiles will need refresh before each work session.

Then test browsing:

For the user's own apps (no bot detection), use state-load — it injects cookies into the existing headless session without interfering with per-repo session isolation or cli.config.json settings:

playwright-cli open <app-url>
playwright-cli state-load ~/.playwright-cli/auth-<name>.json
playwright-cli reload
playwright-cli snapshot

Take a snapshot to confirm the user is signed in. If the app redirects to the login page, the session may not have saved correctly — re-run sign-in.

Only use --persistent --profile when state-load fails (sites with bot detection like Cloudflare Turnstile or Google OAuth). Note: --browser chrome launches the real Chrome app and can conflict with the user's personal Chrome on macOS — close the session promptly when done.

playwright-cli open <app-url> --headed --browser chrome --persistent --profile ~/.playwright-cli/chrome-profile

Step 5: Confirm and summarize

Tell the user:

• Their app is now registered as <name>
• Future sign-ins: node ~/.playwright-cli/sign-in.mjs login <name>
• To browse authenticated: just ask Claude to "open deckchecker" or "browse seatify"
• Default browsing uses state-load (headless, non-interfering with session isolation)
• Each site gets its own auth file (auth-<name>.json); multiple accounts on the same domain need distinct site names (e.g., seatify-admin, seatify-planner)

Multi-User / QA Profiles

For apps that need multiple authenticated users (e.g., testing admin vs planner roles), use --profile to isolate each user's Chrome session. Without --profile, all sign-ins share a single Chrome profile — meaning a second sign-in to the same domain overwrites the first user's cookies.

Step 1: Register each user as a separate site

node ~/.playwright-cli/sign-in.mjs add seatify-admin https://seatify.app/login /dashboard
node ~/.playwright-cli/sign-in.mjs add seatify-planner https://seatify.app/login /dashboard

Step 2: Sign in with isolated profiles

Tell the user to run each in a separate terminal:

node ~/.playwright-cli/sign-in.mjs login seatify-admin --profile seatify-admin
node ~/.playwright-cli/sign-in.mjs login seatify-planner --profile seatify-planner

The --profile <name> flag creates an isolated Chrome directory at ~/.playwright-cli/chrome-profile-<name>/. Each user's session is completely independent.

Step 3: Browse as a specific user

Multi-user profiles on the same domain share auth files keyed by site name (e.g., auth-seatify-admin.json, auth-seatify-planner.json). Since each role has a distinct site name, state-load works:

playwright-cli open https://seatify.app/dashboard
playwright-cli state-load ~/.playwright-cli/auth-seatify-admin.json
playwright-cli reload

To switch users, load a different auth file:

playwright-cli state-load ~/.playwright-cli/auth-seatify-planner.json
playwright-cli reload

If state-load doesn't work (bot detection), fall back to the persistent profile:

playwright-cli open https://seatify.app/dashboard --headed --browser chrome \
  --persistent --profile ~/.playwright-cli/chrome-profile-seatify-admin

Naming convention

Use <app>-<role> as both the site name and profile name: seatify-admin, seatify-planner, deckchecker-owner, client-portal-reviewer. This keeps auth files and Chrome profiles aligned.

Handling Multiple Environments

For apps with multiple environments (production, staging, dev), register each as a separate site:

node ~/.playwright-cli/sign-in.mjs add seatify https://seatify.app/login /dashboard
node ~/.playwright-cli/sign-in.mjs add seatify-staging https://staging.seatify.app/login /dashboard
node ~/.playwright-cli/sign-in.mjs add seatify-dev http://localhost:3000/login /dashboard

Combine with --profile for multi-user across environments:

node ~/.playwright-cli/sign-in.mjs add seatify-staging-admin https://staging.seatify.app/login /dashboard
node ~/.playwright-cli/sign-in.mjs login seatify-staging-admin --profile seatify-staging-admin

Common Post-Login Patterns

When helping the user determine the waitFor pattern, suggest these common patterns:

Framework / Pattern	Typical post-login URL
Next.js with dashboard	/dashboard
SPA with hash routing	#/home or #/dashboard
Supabase Auth redirect	/dashboard or the redirectTo path
OAuth callback	The final redirect after /auth/callback
Multi-step onboarding	/onboarding or /setup

If unsure, the user can sign in manually (Enter-based) first, then check the browser URL bar to discover the pattern. They can update the site config later with add (same name overwrites).

Using Captured Auth

Once a session is captured, the user can ask Claude to browse the app naturally:

• "Open deckchecker and check the dashboard"
• "Browse seatify staging"
• "Go to the client portal"
• "Browse seatify as admin"
• "Check the planner view on seatify"

Claude should check auth status first, then browse using the two-tier approach:

Tier 1: state-load (default for custom apps)

Injects cookies into the existing headless session. Non-interfering — respects cli.config.json, session isolation, and headless mode.

# Single-user app
playwright-cli open <url>
playwright-cli state-load ~/.playwright-cli/auth-<name>.json
playwright-cli reload

# Multi-user / QA — each role is a separate site name
playwright-cli open <url>
playwright-cli state-load ~/.playwright-cli/auth-seatify-admin.json
playwright-cli reload

When the user mentions a role ("as admin", "as planner"), map it to the corresponding auth file (e.g., auth-deckchecker-admin.json).

Tier 2: --persistent --profile (bot-protected sites only)

Only needed when state-load fails — typically external services with Cloudflare Turnstile or Google OAuth that fingerprint the browser itself.

# Default profile
playwright-cli open <url> --headed --browser chrome \
  --persistent --profile ~/.playwright-cli/chrome-profile

# Named profile (multi-user)
playwright-cli open <url> --headed --browser chrome \
  --persistent --profile ~/.playwright-cli/chrome-profile-<name>

This overrides session isolation and requires headed mode. See the auth-browse skill for details.