lovagentic

Agentic CLI for Lovable.dev — agents in, apps out.

Send prompts, verify builds, fix errors, and publish — straight from your terminal or from inside your AI agent.

npm install -g lovagentic
lovagentic prompt "https://lovable.dev/projects/YOUR-ID" "Add a dark mode toggle"

That's it. Lovable builds. You ship.

What it does

lovagentic gives your terminal (and your AI agents) full control over Lovable:

| | | |---|---| | 🚀 Prompt | Send prompts, split long ones automatically, verify they landed | | 🔍 Verify | Screenshot every route, check for layout overflows, assert text | | 📦 Publish | One command to deploy — with live URL check | | 🛠 Fix | Inspect runtime errors, click "Try to fix", loop until clean | | 🤖 Agent-ready | --json output on every command. Pipe it, script it, chain it. |

Multi-backend: browser, MCP, or API

lovagentic v0.2 auto-selects the fastest available backend:

LOVABLE_API_KEY set  →  @lovable.dev/sdk preview backend  (fastest, no browser)
LOVABLE_MCP_URL set  →  MCP backend
nothing set          →  Playwright browser fallback  (always works)

Lovable's public docs currently describe the Lovable API as starting with Build with URL. The key-backed SDK backend in lovagentic is intentionally treated as a preview path: use it when Lovable has granted API access, and keep the browser backend as the compatibility layer for UI-only surfaces.

Set an API key and supported commands can skip Playwright:

export LOVABLE_API_KEY=lov_your_key_here
lovagentic api --validate        # confirm SDK is ready
lovagentic list --json           # pure HTTPS, instant
lovagentic prompt "..." "..."    # no browser launch

No lov_... API key yet? Use the Firebase Bearer-token path that the Lovable web/desktop app uses internally. After signing in to Lovable Desktop or running lovagentic login, capture the refresh token once and let lovagentic keep a fresh Bearer on disk for you:

lovagentic import-desktop-session --profile-dir /tmp/lovagentic-profile
lovagentic auth bootstrap \
  --profile-dir /tmp/lovagentic-profile \
  --out-env $HOME/.lovagentic/lovable.env

lovagentic api --validate        # auto-uses the cached token

Optional: install a macOS LaunchAgent that refreshes the Bearer every 50 minutes (see scripts/launchd/install-auth-refresh.sh). Full reference in docs/lovable-api.md and per-endpoint detail in docs/lovable-api-reference.md.

Install

npm install -g lovagentic

First run:

lovagentic doctor          # check environment
lovagentic login           # authenticate with Lovable (browser, one-time)
lovagentic list            # confirm projects are visible

Quick examples

Send a prompt and verify it landed:

lovagentic prompt "https://lovable.dev/projects/YOUR-ID" \
  "Make the hero section full-width on mobile" \
  --headless --seed-desktop-session --verify-effect

Scaffold a project directory:

mkdir my-app && cd my-app
lovagentic init --project-url https://lovable.dev/projects/YOUR-ID

Publish to production:

lovagentic publish "https://lovable.dev/projects/YOUR-ID" \
  --headless --seed-desktop-session --verify-live

Screenshot all routes (desktop + mobile):

lovagentic verify "https://lovable.dev/projects/YOUR-ID" \
  --route / --route /docs --route /pricing \
  --expect-text "Get started"

Run a repeatable build plan:

# runbook.yaml
projectUrl: https://lovable.dev/projects/YOUR-ID
steps:
  - type: snapshot
  - type: prompt
    promptFile: ./prompts/feature.md
  - type: verify
    expectText: [Feature, Get started]
  - type: publish
    verifyLive: true

LOVABLE_API_KEY=lov_... lovagentic runbook ./runbook.yaml

All commands

| Command | What it does | |---|---| | init | Scaffold a project directory | | doctor | Check local environment + network | | api | Validate SDK/API-key readiness | | login | Authenticate with Lovable | | list | List your projects | | create | Create a new Lovable project | | prompt | Send a prompt | | mode | Switch build/plan mode | | wait-for-idle | Wait until Lovable stops thinking | | verify | Screenshot routes, check text/layout | | publish | Publish / deploy | | status | Read project metadata | | code | Read repo files via Lovable | | snapshot | API-backed project artifact | | diff | API-backed git diff | | runbook | Execute a YAML/JSON build plan | | knowledge | Read/write project knowledge | | domain | Manage custom domains | | speed | Lighthouse audit | | fidelity-loop | Iterative verify → fix loop | | chat-loop | Prompt → actions → verify | | errors | Inspect + click runtime errors | | findings | Read security findings |

Full reference → lovagentic.com/docs/reference/commands

Agent-ready: pipe it, script it

Every command supports --json:

STATUS=$(lovagentic status "https://lovable.dev/projects/YOUR-ID" --json)
EDIT_COUNT=$(echo $STATUS | jq '.editCount')

lovagentic prompt "..." "Add a pricing table" --json | jq '.effect.confirmed'

lovagentic publish "..." --json | jq '.liveUrl'

Use it from Claude, GPT, Codex, or any agent that can run shell commands.

GitHub Action

Drop the lovagentic-runbook action into your Lovable project repo to run snapshot + diff (or any other runbook) on every PR and have the result posted back as a comment:

# .github/workflows/lovagentic-runbook.yml
name: Lovable runbook
on: { pull_request: { branches: [main] } }
permissions: { contents: read, pull-requests: write }
jobs:
  runbook:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Alfridus1/[email protected]
        with:
          bearer-token: ${{ secrets.LOVABLE_BEARER_TOKEN }}
          project-url:  ${{ vars.LOVABLE_PROJECT_URL }}

Falls back to a built-in snapshot + diff runbook when no .lovagentic/runbook.yaml is present. Full example workflow at examples/github-actions-runbook.yml and a starter runbook at examples/lovagentic-runbook.default.yaml.

Environment variables

| Variable | Effect | |---|---| | LOVABLE_API_KEY | Use SDK/API backend where available | | LOVABLE_BEARER_TOKEN | Alternative API auth | | LOVABLE_MCP_URL | Use MCP backend | | LOVABLE_PROJECT_URL | Default project for commands | | LOVAGENTIC_PROFILE_DIR | Custom browser profile path |

Full reference → lovagentic.com/docs/reference/env

Requirements

• Node.js 20+
• A Lovable account + session
• Playwright Chromium (auto-installed, only needed for browser backend)
• Optional: LOVABLE_API_KEY to use SDK-backed flows where available

Roadmap

| Version | Status | What | |---|---|---| | v0.1 | ✅ shipped | Browser-first CLI — Playwright control of every Lovable surface | | v0.2 | ✅ shipped | Multi-backend — SDK/API + MCP + browser fallback | | v0.3 | ✅ shipped | Firebase bearer-token bootstrap, refresh, persistent cache; full Lovable API reference docs; runbook output persistence; getProject enrichment workaround | | v0.4 | 🔵 planned | CI/CD integrations (GitHub Actions, Vercel workflows) | | v0.5 | ⚪ exploratory | Team-scale hosted control plane |

Long-form upstream proposals (e.g. @lovable.dev/sdk enhancements) live in proposals/.

Development

npm test          # 78 tests
npm run check     # syntax + tests
npm run doctor    # environment check

📚 Full docs: lovagentic.com/docs
📦 npm: npmjs.com/package/lovagentic
🐛 Issues: github.com/Alfridus1/lovagentic/issues

MIT License