Skip to main content

culvii login

Log in to the Culvii CLI via OAuth.

Synopsis​

culvii login

Description​

Opens the user's browser to the Culvii hosted login page (AWS Cognito, federated through Google). Uses OAuth 2.0 Authorization Code flow with PKCE (RFC 7636). The CLI starts a one-shot loopback HTTP server on 127.0.0.1 to receive the authorization code, then exchanges it directly with Cognito over HTTPS. The resulting access token, refresh token, and ID token are written atomically to ~/.culvii/config.json (mode 0600).

After token exchange, the CLI calls GET /auth/me on the Culvii backend to fetch the user's organisation, roles, and scopes, then prints an identity summary.

No flags. Interactive only — cannot be called from a script using an existing API key.

Behaviour​

  • Binds to 127.0.0.1 only (not 0.0.0.0). Port is OS-assigned.
  • Accepts exactly one HTTP request then shuts the local server down.
  • 5-minute timeout: if the user does not complete the browser flow, the CLI prints "Authentication timed out, try again" and exits 1.
  • If the browser does not open automatically, the CLI prints the URL for manual use.
  • On success: tokens written, identity summary printed, exit 0.
  • On user denying consent: exit 1, message "Access denied."
  • On state mismatch (possible CSRF): exit 1, message "Authentication response mismatch. Possible CSRF — aborting."

Tokens are never deleted due to network errors. They are only deleted when Cognito returns invalid_grant (expired, revoked, or reuse detected).

Examples​

culvii login
# → Opens browser → "✓ Logged in as alice@acme.com (acme)"

culvii logout, culvii whoami