Quickstart

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

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

Installation

Choose your preferred installation method:

macOS / Linux (Homebrew)

bash

brew install lovelace-cli
ada --version

Windows (Winget)

powershell

winget install ReasonableTech.LovelaceCLI
ada --version

Universal install script

macOS / Linux / WSL:

bash

curl -fsSL https://d.uselovelace.com/install | sh
ada --version

Windows (PowerShell):

powershell

Invoke-WebRequest -Uri https://d.uselovelace.com/install.ps1 -UseBasicParsing | Invoke-Expression
ada --version

Quick Setup (5 Minutes)

Step 1: Run Setup Wizard

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

bash

ada setup

What happens:

Opens browser for Lovelace platform authentication
Connects to your Lovelace account
Configures default AI provider (optional)
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
ada doctor

# Authentication status
lovelace auth status

# List workspaces
ada workspace list

Expected output:

✓ Ada 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
ada 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
ada agents create code-analyzer --template analysis

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

# Check agent status
ada agents list

View agent output:

bash

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

# Get task results
ada agents results code-analyzer

Next Steps

Essential Commands

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

AI Interaction:

bash

ada chat                    # Interactive AI chat
ada analyze                 # Analyze current project
ada sessions                # View chat history

Agent Management:

bash

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

Workspace Operations:

bash

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

Configuration:

bash

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

Learn Common Workflows

Explore task-oriented guides for everyday development:

Common Workflows - Daily development, code review, team collaboration
Agent Execution Guide - Advanced agent usage and orchestration
MCP Integration - Connect to Model Context Protocol servers
Editor Integration - Use Lovelace from VS Code, Zed, and more

Explore Advanced Features

Multi-LLM Support:

bash

# Switch AI provider
lovelace config set ai.provider openai

# Use specific model for chat
ada 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
ada sessions

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

# Search session history
ada sessions search "authentication"

# Export sessions
ada 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 ada

# Reinstall via your install channel, e.g.:
brew reinstall lovelace-cli
# or
curl -fsSL https://d.uselovelace.com/install | sh

Agent daemon not starting:

bash

# Check daemon status
ada agents daemon status

# Restart daemon
ada agents daemon restart

# View daemon logs
ada agents daemon logs

Workspace sync issues:

bash

# Re-initialize workspace
ada workspace init --force

# Check workspace status
ada workspace status --verbose

Getting Help

Built-in Diagnostics:

bash

# Comprehensive system check
ada doctor

# Verbose diagnostic output
ada doctor --verbose

# Attempt automatic fixes
ada doctor --fix

Command Help:

bash

# General help
lovelace --help

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

Community Support:

Troubleshooting Guide - Detailed solutions for common issues

What's Next?

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

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

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

Lovelace Developer Portal

Lovelace Developer Portal

Quickstart

Installation

macOS / Linux (Homebrew)

Windows (Winget)

Universal install script

Quick Setup (5 Minutes)

Step 1: Run Setup Wizard

Step 2: Verify Installation

Step 3: Your First AI Chat

Step 4: Create Your First Agent

Next Steps

Essential Commands

Learn Common Workflows

Explore Advanced Features

Troubleshooting

Common Issues

Getting Help

What's Next?