Skip to content
Cosine

Login Experience

The Cosine CLI provides a seamless login experience with automatic authentication checks and visual feedback through your browser.

Login Flow

Section titled “Login Flow”

Starting the Login

Section titled “Starting the Login”

When you run `cos login`, the CLI:

  1. Opens your default browser to the Cosine authentication page
  2. Displays the URL in the terminal in case the browser doesn’t open
  3. Waits for you to complete authentication
  4. Listens on `localhost:9793` for the callback

Browser Experience

Section titled “Browser Experience”

After clicking the link or having your browser opened automatically:

Success Page - When login succeeds, you’ll see a modern, animated success page with:

  • ✓ Green checkmark icon with pulse animation
  • Your team name (if you’re part of a team)
  • Confirmation message: “You are now logged in to the Cosine CLI”
  • Instruction to return to your terminal
  • Auto-closes after 2 seconds

Error Page - If login fails, you’ll see an error page with:

  • ✗ Red X icon with shake animation
  • Error message explaining what went wrong
  • Instructions to retry with `cos login` command
  • Auto-closes after 3 seconds

Both pages feature:

  • Glassmorphism design with frosted glass effect
  • Animated floating background orbs
  • Cosine logo gradient
  • Mobile-responsive layout

Terminal Feedback

Section titled “Terminal Feedback”

After authentication completes:

Success: ``` Login successful. Organisation: [Your Team Name] ```

Failure: ``` Unexpected error: [error details] ```

Automatic Authentication Check

Section titled “Automatic Authentication Check”

Background Verification

Section titled “Background Verification”

Every time you start the CLI, it automatically:

  1. Checks if you have a stored authentication token
  2. Verifies the token is still valid by calling `/users/me`
  3. Shows the login dialog if authentication is invalid

This happens in the background without blocking the UI startup.

When Authentication Fails

Section titled “When Authentication Fails”

If your token has expired or is invalid, you’ll see the login dialog automatically - even from the home page:

``` ┌─────────────────────────────────────────┐ │ Login Required │ │ │ │ Press Enter to login in your browser │ │ or Esc to quit │ └─────────────────────────────────────────┘ ```

The CLI detects these authentication failures:

  • 401 Unauthorized - Token is invalid
  • 403 Forbidden - Access is denied
  • 404 Not Found - User or token doesn’t exist

Network errors are silently ignored to avoid disrupting your workflow.

Re-Authentication

Section titled “Re-Authentication”

To re-authenticate:

  1. Press `Enter` in the login dialog
  2. Your browser opens to the login page
  3. Sign in with your credentials
  4. The dialog closes automatically
  5. You can continue working

Security

Section titled “Security”

Token Storage

Section titled “Token Storage”

Authentication tokens are stored securely:

  • Cosine tokens: `~/.cosine/config.toml` with restricted permissions
  • OpenAI OAuth tokens: `~/.cosine/auth.openai.json` with 0600 permissions

HTTPS Only

Section titled “HTTPS Only”

All authentication traffic uses HTTPS:

Local Callback

Section titled “Local Callback”

The CLI runs a temporary local server at `http://localhost:9793\` only during login to receive the authentication callback. This server:

  • Shuts down immediately after receiving credentials
  • Only accepts connections from localhost
  • Uses a short-lived session

Switching Between Authentication Methods

Section titled “Switching Between Authentication Methods”

You can switch between Cosine and OpenAI OAuth at any time:

Switch to Cosine Account: ```bash cos login ```

Switch to OpenAI OAuth: ```bash cos login-with-chatgpt ```

The CLI will use whichever method you logged in with most recently.

Troubleshooting

Section titled “Troubleshooting”

Login Dialog Doesn’t Appear

Section titled “Login Dialog Doesn’t Appear”

If the login dialog doesn’t show when expected:

  • Check that you have a valid `~/.cosine/config.toml` file
  • Verify your network connection
  • Try running `cos login` manually

Browser Doesn’t Open

Section titled “Browser Doesn’t Open”

If your browser doesn’t open automatically:

  1. Look for the URL printed in the terminal
  2. Copy and paste it into your browser manually
  3. Complete the login flow
  4. The CLI will detect the successful authentication

”State Mismatch” Error

Section titled “”State Mismatch” Error”

During OAuth flows, if you see a state mismatch error:

  • The session may have expired (10 minute timeout)
  • Try the login command again
  • Ensure you’re completing the flow in the same terminal session

Login Loop

Section titled “Login Loop”

If you keep seeing the login dialog after successful authentication:

  • Check file permissions on `~/.cosine/config.toml` (should be readable)
  • Verify the token was saved correctly
  • Try removing `~/.cosine/config.toml` and logging in again

See Also

Section titled “See Also”