Skip to main content

culvii login

Log in to the Culvii CLI via OAuth.

Synopsis​

culvii login
culvii auth login  # alias

Description​

Opens your browser to the Culvii login page (Cognito, federated through Google) using OAuth 2.0 + PKCE. A local loopback listener catches the redirect, exchanges the code for tokens over HTTPS, and writes them atomically to ~/.culvii/tokens.json (mode 0600).

Then fetches the tenants you belong to - if more than one, you'll pick the active one. All are saved to ~/.culvii/config; use culvii switch to change the active tenant later without logging in again.

No flags. Interactive only.

Behaviour​

  • 5-minute timeout. No completed browser flow within 5 minutes exits with "Login failed: Callback timeout." Rerun culvii login.
  • State mismatch (possible CSRF). A callback state that doesn't match exits with "Auth response mismatch - possible CSRF, aborting" instead of completing login.
  • Tokens are deleted only on invalid_grant (rejected/reused code), never on network errors - a flaky connection never silently logs out a session you already had.

If your connection drops mid-login​

Three points can fail on a bad connection, each visibly rather than hanging:

  • Can't start the local listener (sandboxed environment, firewall blocking loopback ports): "Login failed: Couldn't start local listener - check firewall or sandbox restrictions." Browser never opens.
  • Token exchange can't reach Cognito after you approve: "Login failed: Could not reach auth server - check your connection." No tokens written; rerun once you're back online.
  • Identity check fails after a successful token exchange: you're still logged in - tokens are on disk - but the CLI shows "Logged in - could not verify identity with backend" instead of your summary. Run culvii whoami once connectivity returns.

Staying signed in​

You don't log in again just because time passed. Access tokens last about an hour; any command that needs one silently refreshes it from the stored refresh token when it's within 30 seconds of expiring, and retries once on a stray 401. Invisible unless the refresh itself fails:

  • No network during a refresh: "Refresh failed: Cannot reach auth server - check your connection," command exits - retry once you're online, nothing is lost.
  • Refresh token itself invalid (revoked or expired): "Session expired - run culvii login to authenticate." Tokens are deleted; log in again.

culvii dev refreshes differently since it's long-running - see Connectivity and reconnection.

Examples​

culvii login
# → Opens browser
# → (if multiple tenants) You belong to multiple tenants. Please select one:
# →   [1] Culvii Dev
# →   [2] Acme Corp
# → 1
# → ✓ Authenticated
# →   alice@acme.com
# →   Culvii Dev · owner
culvii logoutculvii whoamiculvii switch