lovelace auth

Manage authentication credentials and user sessions

The auth command provides authentication management for the Lovelace CLI, allowing you to sign in, sign out, check authentication status, and manage user sessions across all CLI features.

Overview

Authentication enables:

Access to cloud features - Use Lovelace Agents Cloud and Memory Platform
Session persistence - Stay signed in across CLI sessions
Secure credential storage - Encrypted token storage
Multi-account support - Switch between different accounts
API integration - Authenticate programmatic access

All authentication data is stored securely in ~/.lovelace/auth/ with encrypted credentials and session tokens.

Usage

bash

lovelace auth <command> [options]

Subcommands

`lovelace auth login`

bash

lovelace auth login [options]

Options:

Option	Description	Default
`--email <email>`	Account email address	Interactive prompt
`--browser`	Open browser for OAuth flow	`true`
`--token <token>`	Authenticate with API token	-

Interactive Example:

$ lovelace auth login

┌─ Sign in to Lovelace ──────────────────────────────┐
│                                                     │
│  Choose sign-in method:                             │
│                                                     │
│  › Sign in with browser (recommended)               │
│    Sign in with email/password                      │
│    Sign in with API token                           │
│                                                     │
└─────────────────────────────────────────────────────┘

[Selected: Sign in with browser]

Opening browser for authentication...
→ https://accounts.uselovelace.com/oauth/authorize?...

Waiting for authentication...

✓ Successfully authenticated as user@example.com
✓ Session saved
✓ Ready to use Lovelace CLI!

Email/Password Flow:

$ lovelace auth login

[Select: Sign in with email/password]

Email: user@example.com
Password: ********

🔐 Authenticating...

✓ Successfully signed in as user@example.com
✓ Session expires in 30 days

API Token Flow:

$ lovelace auth login --token

API Token: sk-lovelace-****************************

✓ Token validated
✓ Authenticated as user@example.com (API)
✓ Session saved

`lovelace auth logout`

Sign out of your Lovelace account.

bash

lovelace auth logout [options]

Options:

Option	Description
`--all`	Sign out from all devices
`--keep-local`	Keep local session data (revoke cloud session only)

Interactive Example:

$ lovelace auth logout

Sign Out
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Currently signed in as: user@example.com

What would you like to do?
  › Sign out on this device
    Sign out on all devices
    Cancel

[Selected: Sign out on this device]

✓ Session cleared
✓ Signed out successfully

Run 'lovelace auth login' to sign in again.

Sign Out Everywhere:

$ lovelace auth logout --all

⚠️  Warning: Sign Out from All Devices
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This will:
  • Revoke all active sessions
  • Sign you out on all devices
  • Require re-authentication everywhere

Continue? (y/N): y

🔄 Revoking sessions...

✓ Revoked 3 active sessions
✓ Signed out from all devices

`lovelace auth status`

Check current authentication status.

bash

lovelace auth status [options]

Options:

Option	Description
`--json`	Output in JSON format
`--verbose`	Show detailed session information

Interactive Example:

$ lovelace auth status

Authentication Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Signed in as user@example.com

Account Details:
  Email: user@example.com
  Name: John Doe
  Plan: Pro
  Status: Active

Session:
  Type: OAuth
  Created: 2025-10-15 09:30:00
  Expires: 2025-11-14 09:30:00
  Valid for: 25 days

Permissions:
  ✓ Agents Cloud access
  ✓ Memory Platform access
  ✓ API access

Verbose Status:

$ lovelace auth status --verbose

Authentication Status (Detailed)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

User Information:
  User ID: usr_abc123def456
  Email: user@example.com
  Name: John Doe
  Account Created: 2025-01-15
  Email Verified: Yes

Subscription:
  Plan: Pro
  Status: Active
  Billing Cycle: Monthly
  Next Billing: 2025-11-01

Session Details:
  Session ID: sess_xyz789abc123
  Type: OAuth 2.0
  Issued: 2025-10-15 09:30:00 UTC
  Expires: 2025-11-14 09:30:00 UTC
  Last Used: 2025-10-19 14:25:00 UTC
  IP Address: 203.0.113.42
  User Agent: Lovelace-CLI/1.0

Permissions & Scopes:
  ✓ agents:read
  ✓ agents:write
  ✓ memory:read
  ✓ memory:write
  ✓ user:profile

Active Devices:
  • MacBook Pro (this device) - Last active: now
  • iPhone 15 - Last active: 2 hours ago
  • Ubuntu Desktop - Last active: yesterday

Storage:
  Credentials: ~/.lovelace/auth/credentials.enc
  Session: ~/.lovelace/auth/session.json

JSON Output:

bash

$ lovelace auth status --json

{
  "authenticated": true,
  "user": {
    "id": "usr_abc123def456",
    "email": "user@example.com",
    "name": "John Doe",
    "plan": "pro"
  },
  "session": {
    "id": "sess_xyz789abc123",
    "type": "oauth",
    "created": "2025-10-15T09:30:00.000Z",
    "expires": "2025-11-14T09:30:00.000Z",
    "expiresIn": 2160000
  },
  "permissions": [
    "agents:read",
    "agents:write",
    "memory:read",
    "memory:write",
    "user:profile"
  ]
}

`lovelace auth whoami`

Display current user information.

bash

lovelace auth whoami

Example:

$ lovelace auth whoami

user@example.com (John Doe)
Plan: Pro
Account ID: usr_abc123def456

`lovelace auth token`

Manage API tokens for programmatic access.

bash

lovelace auth token <action> [options]

Actions:

create - Create a new API token
list - List all API tokens
revoke - Revoke an API token

Create Token:

$ lovelace auth token create

Create API Token
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Token Name: CI/CD Pipeline
Description (optional): GitHub Actions deployment
Expiration:
  › 30 days
    90 days
    1 year
    Never

Scopes:
  [x] agents:read
  [x] agents:write
  [ ] memory:read
  [ ] memory:write

✓ Token created successfully

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  IMPORTANT: Save this token securely
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  sk-lovelace-abc123def456ghi789jkl012mno345pqr

This token will not be shown again!

Store in environment variable:
  export LOVELACE_API_TOKEN="sk-lovelace-abc123..."

Token Details:
  Name: CI/CD Pipeline
  Scopes: agents:read, agents:write
  Expires: 2025-11-18 14:30:00

List Tokens:

$ lovelace auth token list

API Tokens
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

tok_abc123   │ CI/CD Pipeline     │ agents:*           │ Expires Nov 18
tok_def456   │ Local Development  │ agents:*, memory:* │ Never expires
tok_ghi789   │ Testing            │ agents:read        │ Expired Oct 10

3 tokens total (2 active, 1 expired)

Revoke Token:

$ lovelace auth token revoke tok_abc123

⚠️  Revoke API Token
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Token: CI/CD Pipeline (tok_abc123)
Created: 2025-09-18
Last used: 2025-10-19 (2 hours ago)

Are you sure? (y/N): y

✓ Token revoked successfully
⚠️  Applications using this token will lose access

Common Use Cases

Initial Authentication

$ lovelace auth login

[Browser opens, complete OAuth flow]

✓ Successfully authenticated
✓ Ready to use Lovelace CLI

Check Authentication Before Running Commands

Verify you're signed in:

$ lovelace auth status

✓ Signed in as user@example.com

$ lovelace agents list
[Works because authenticated]

Switching Accounts

Sign out and sign in with different account:

$ lovelace auth logout
✓ Signed out

$ lovelace auth login
Email: other@example.com
Password: ********
✓ Signed in as other@example.com

CI/CD Authentication

Use API tokens in automated environments:

bash

# Create token via CLI
lovelace auth token create

# Store in CI/CD secrets
# LOVELACE_API_TOKEN=sk-lovelace-abc123...

# Use in pipeline
export LOVELACE_API_TOKEN="${LOVELACE_API_TOKEN}"
lovelace agents deploy

Debugging Authentication Issues

Check detailed auth status:

$ lovelace auth status --verbose

[Shows detailed session, permissions, devices]

$ lovelace doctor

[Runs auth diagnostics]

Authentication Storage

Authentication data is stored securely:

~/.lovelace/auth/
├── credentials.enc       # Encrypted user credentials
├── session.json          # Active session data
└── tokens/               # API tokens
    ├── tok_abc123.json
    └── tok_def456.json

Security Features:

Credentials encrypted at rest
Session tokens never logged
File permissions restricted to user only (chmod 600)
Automatic token rotation
Secure deletion on logout

Environment Variables

Variable	Description	Default
`LOVELACE_API_TOKEN`	API token for authentication	-
`LOVELACE_AUTH_URL`	Custom authentication endpoint	`https://accounts.uselovelace.com`

Note: API token takes precedence over interactive session.

Exit Codes

Code	Meaning
`0`	Command succeeded
`1`	Authentication failed
`2`	Invalid token or credentials
`3`	Network error

Troubleshooting

Not Authenticated

$ lovelace agents list

Error: Not authenticated
Run 'lovelace auth login' to sign in

Solution:

$ lovelace auth login
[Complete authentication]

Session Expired

Error: Session expired
Please sign in again: lovelace auth login

Solution:

$ lovelace auth login
[Re-authenticate]

Token Invalid

$ lovelace auth login --token
Error: Invalid token format

Solution:
1. Check token starts with 'sk-lovelace-'
2. Verify no extra spaces
3. Create new token: lovelace auth token create

Browser Won't Open

$ lovelace auth login

Opening browser for authentication...
Error: Could not open browser

Solution: Use manual URL:
→ https://accounts.uselovelace.com/oauth/authorize?client_id=...

Copy this URL to your browser to authenticate.

Multiple Device Sessions

⚠️  Warning: Session conflict detected
You are signed in on multiple devices

Options:
1. Keep all sessions: Continue
2. Sign out other devices: lovelace auth logout --all

Related Commands

lovelace config - View authentication configuration
lovelace doctor - Diagnose authentication issues

Related Guides

Authentication Setup Guide - Detailed authentication setup
Getting Started - First-time CLI setup

See the Command Reference for all available commands.

Lovelace Developer Portal

lovelace auth

Overview

Usage

Subcommands

`lovelace auth login`

`lovelace auth logout`

`lovelace auth status`

`lovelace auth whoami`

`lovelace auth token`

Common Use Cases

Initial Authentication

Check Authentication Before Running Commands

Switching Accounts

CI/CD Authentication

Debugging Authentication Issues

Authentication Storage

Environment Variables

Exit Codes

Troubleshooting

Not Authenticated

Session Expired

Token Invalid

Browser Won't Open

Multiple Device Sessions

Related Commands

Related Guides

Lovelace Developer Portal