Skip to main content

Authentication: Login and Logout

The spirlctl CLI requires authentication to interact with the SPIRL platform. This guide covers the complete authentication workflow, including logging in, managing sessions, and logging out.

Login Flow​

Login with Google​

The simplest way to log in is to use a Google account:

spirlctl login

This command opens your default web browser where you can authenticate with your Google account. After successful authentication, a session token is stored locally in ~/.spirl/config.json.

Organization Login​

If your Google account belongs to multiple organizations, or if you're using Enterprise SSO, you can specify the organization at the command line:

spirlctl login --org my-org

If the organization is not specified, the login page will prompt you to select one.

Login with Identity Provider Hint​

To pre-fill the login form with a specific email address:

spirlctl login --hint user@example.com

This is particularly useful when:

  • You have multiple accounts with the same identity provider
  • You want to speed up the login process
  • You're automating login flows in scripts

Headless Login​

For environments without browser support (e.g., SSH sessions, CI/CD pipelines), use headless login:

spirlctl login --headless

This will output a URL that you can open on another device. After authenticating in the browser, you'll receive a code to paste back into the terminal.

Service Account Login​

For non-interactive environments like CI/CD pipelines, use service account authentication:

spirlctl login \
  --service-account-key-id sak-1234 \
  --private-key-file /path/to/private.pem

Service accounts are ideal for:

  • Automated scripts and pipelines
  • Server-to-server authentication
  • Environments where user interaction isn't possible

Verifying Your Identity​

After logging in, verify your authentication status:

spirlctl whoami

This displays information about your current identity, including:

  • Your email or service account ID
  • Organization membership
  • Access level

Example output:

User ID:        user@example.com
Organization:   my-org
Authenticated:  Yes

Session Management​

Configuration File​

Authentication tokens are stored in ~/.spirl/config.json by default. You can specify an alternative location:

spirlctl login --config-file custom-config.json
warning

The configuration file contains sensitive authentication tokens. Protect this file with appropriate permissions and never commit it to version control.

Using a Proxy​

If your environment requires a proxy for outbound connections:

spirlctl login --endpoint-proxy http://proxy.example.com:8080

Logout​

To end your session and remove stored credentials:

spirlctl logout

This command:

  1. Revokes your session token with the SPIRL platform
  2. Removes authentication data from the local configuration file

After logging out, you'll need to run spirlctl login again to perform any authenticated operations.

Common Login Scenarios​

Switching Organizations​

To switch to a different organization:

spirlctl logout
spirlctl login --org other-org

Multiple Configurations​

Manage separate configurations for different environments:

# Development environment
spirlctl login --config-file ~/.spirl/dev-config.json --org dev-org

# Production environment
spirlctl login --config-file ~/.spirl/prod-config.json --org prod-org

Then specify the config file for each command:

spirlctl cluster list --config-file ~/.spirl/prod-config.json

CI/CD Pipeline Example​

Example GitHub Actions workflow:

- name: Login to SPIRL
  run: |
    echo "${{ secrets.SPIRL_PRIVATE_KEY }}" > private.pem
    spirlctl login \
      --service-account-key-id ${{ secrets.SPIRL_KEY_ID }} \
      --private-key-file private.pem
    rm private.pem

Best Practices​

  1. Use Service Accounts for Automation: Never use personal credentials in scripts or CI/CD pipelines
  2. Protect Configuration Files: Set appropriate file permissions on ~/.spirl/config.json
  3. Logout When Done: Always logout when finished, especially on shared systems
  4. Separate Environments: Use different config files for development and production
  5. Regular Key Rotation: Rotate service account keys regularly for security

Troubleshooting​

Browser Doesn't Open​

If the browser doesn't open automatically during login:

  • Use --headless flag for manual URL handling
  • Check if a BROWSER environment variable is set incorrectly
  • Ensure you have a default browser configured

Authentication Failure​

If you receive authentication errors:

  1. Verify you're using the correct organization name
  2. Ensure you've used your user invitation link to create your user for the organization
  3. Try clearing your configuration file: rm ~/.spirl/config.json
  4. Ensure your system clock is synchronized (OAuth2 tokens are time-sensitive)

Proxy Issues​

If you're behind a proxy:

  • Use the --endpoint-proxy flag
  • Ensure the proxy allows HTTPS connections
  • Check proxy environment variables (HTTP_PROXY, HTTPS_PROXY)

Service Account Login Fails​

If service account authentication fails:

  • Verify the key ID is correct
  • Ensure the private key file path is accessible
  • Check that the service account has not been revoked
  • Confirm the private key format matches the expected format (PEM)