Skip to main content

Quickstart

Get up and running with Lovelace CLI in just a few minutes

This guide will help you install Lovelace CLI, authenticate with the platform, and run your first AI-assisted development command.

Installation

Choose your preferred installation method:

NPM Installation

Requirements: Node.js 20+

bash
# Install globally
npm install -g @lovelace-ai/cli

# Verify installation
lovelace --version

Native Installer

macOS (Homebrew or direct install):

bash
# Using Homebrew
brew install lovelace-ai/tap/lovelace

# Or using install script
curl -fsSL https://install.uselovelace.com/cli/macos | bash

Linux:

bash
curl -fsSL https://install.uselovelace.com/cli/linux | bash

Windows (PowerShell as Administrator):

powershell
irm https://install.uselovelace.com/cli/windows | iex

Quick Setup (5 Minutes)

Step 1: Run Setup Wizard

The interactive setup wizard guides you through authentication and initial configuration:

bash
lovelace setup

What happens:

  1. Opens browser for Lovelace platform authentication
  2. Connects to your Lovelace account
  3. Configures default AI provider (optional)
  4. Creates your first workspace

Prefer headless setup? Use device flow authentication:

bash
lovelace auth signin --device-flow

Step 2: Verify Installation

Check that everything is working correctly:

bash
# System health check
lovelace doctor

# Authentication status
lovelace auth status

# List workspaces
lovelace workspace list

Expected output:

✓ Lovelace CLI v1.0.0
✓ Authentication: Active (user@example.com)
✓ Workspace: my-workspace
✓ AI Provider: Anthropic Claude
✓ All systems operational

Step 3: Your First AI Chat

Start an interactive chat session with workspace context:

bash
# Navigate to your project
cd /path/to/your/project

# Start chat with automatic workspace detection
lovelace chat

Try these prompts:

You: What's the structure of this codebase?

You: How can I improve error handling in auth.ts?

You: Generate unit tests for the user service

Tips:

  • Type /help to see available slash commands
  • Type /context to add files or directories to the conversation
  • Type /exit to end the session

Step 4: Create Your First Agent

Agents execute long-running tasks in the background:

bash
# Create a code analysis agent
lovelace agents create code-analyzer --template analysis

# Run analysis task
lovelace agents run code-analyzer "Analyze this codebase for security issues"

# Check agent status
lovelace agents list

View agent output:

bash
# Follow agent logs in real-time
lovelace agents logs code-analyzer --follow

# Get task results
lovelace agents results code-analyzer

Next Steps

Essential Commands

Now that you're set up, here are the most commonly used commands:

AI Interaction:

bash
lovelace chat                    # Interactive AI chat
lovelace analyze                 # Analyze current project
lovelace sessions                # View chat history

Agent Management:

bash
lovelace agents list             # List all agents
lovelace agents run <name> "task"  # Execute agent task
lovelace agents logs <name>      # View agent output

Workspace Operations:

bash
lovelace workspace switch <name>   # Switch workspace
lovelace workspace sync            # Sync workspace data
lovelace workspace status          # Check workspace health

Configuration:

bash
lovelace config list             # View all settings
lovelace config set <key> <value>  # Update setting
lovelace doctor                  # System diagnostics

Learn Common Workflows

Explore task-oriented guides for everyday development:

Explore Advanced Features

Multi-LLM Support:

bash
# Switch AI provider
lovelace config set ai.provider openai

# Use specific model for chat
lovelace chat --model gpt-4

# Configure local models (Ollama)
lovelace config set ai.provider ollama
lovelace config set ai.model llama2

MCP Integration:

bash
# List available MCP servers
lovelace mcp servers

# Start interactive MCP session
lovelace mcp repl

# Execute MCP commands
lovelace mcp exec list_issues assignee="me"

Session Management:

bash
# Browse previous chats
lovelace sessions

# Resume a session
lovelace sessions resume <session-id>

# Search session history
lovelace sessions search "authentication"

# Export sessions
lovelace sessions export today --format markdown

Troubleshooting

Common Issues

Authentication fails:

bash
# Clear credentials and retry
lovelace auth signout
lovelace auth signin --device-flow

Command not found:

bash
# Verify installation
which lovelace
npm list -g @lovelace-ai/cli

# Reinstall if needed
npm uninstall -g @lovelace-ai/cli
npm install -g @lovelace-ai/cli

Agent daemon not starting:

bash
# Check daemon status
lovelace agents daemon status

# Restart daemon
lovelace agents daemon restart

# View daemon logs
lovelace agents daemon logs

Workspace sync issues:

bash
# Re-initialize workspace
lovelace workspace init --force

# Check workspace status
lovelace workspace status --verbose

Getting Help

Built-in Diagnostics:

bash
# Comprehensive system check
lovelace doctor

# Verbose diagnostic output
lovelace doctor --verbose

# Attempt automatic fixes
lovelace doctor --fix

Command Help:

bash
# General help
lovelace --help

# Command-specific help
lovelace chat --help
lovelace agents run --help

Community Support:

What's Next?

You're now ready to use Lovelace CLI for AI-powered development! Here are some suggestions:

  1. Explore Common Workflows - See practical examples for everyday tasks
  2. Read the CLI Reference - Learn all available commands
  3. Set Up Editor Integration - Use Lovelace from your favorite editor

Need more help? Run lovelace doctor for diagnostics or check the Troubleshooting Guide.