cli

# Kleap — website infrastructure for AI agents

[![CI](https://github.com/kleaphq/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/kleaphq/cli/actions/workflows/ci.yml)
[![CLI](https://img.shields.io/badge/CLI-kleap-16b364)](#cli-for-agent-shells--claude-code-codex-scripts)
[![MCP](https://img.shields.io/badge/MCP-server-2563eb)](https://modelcontextprotocol.io)
[![17 tools](https://img.shields.io/badge/tools-17-ff0055)](#tools)
[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)

> **Your agent builds. Kleap ships it live.**
> Let any AI agent — Claude, ChatGPT, Cursor, or a bash-tool agent like Claude
> Code — build, edit and **publish real, live websites** for you. Hosting,
> database, auth and domains included.

An alternative to Lovable / v0 / Bolt — except it's driven by **your** agent, and
every publish comes with the **verified-live guarantee**: a site is only ever
reported online once it is *provably serving* — never a hallucinated dead link.

This package is **both** a CLI (`kleap create "…"`, `kleap publish 42`, …) and an
[MCP](https://modelcontextprotocol.io) server (`kleap mcp` / no args) — same
account, same `~/.kleap/config.json` auth, same underlying `/api/v1` REST API.
Pick whichever fits your agent: a shell/bash-tool agent (Claude Code, a cron
script, CI) wants the **CLI** — one compact line per call, no JSON-RPC framing.
An MCP-native client (Claude Desktop, Cursor, ChatGPT connectors) wants the
**MCP server**, which this package also is, unchanged.

![A real, unedited run: an agent writes a page with write_files, publishes, and it is live and serving in seconds.](https://raw.githubusercontent.com/kleaphq/cli/main/assets/demo.gif)

> *Above: a real run — your agent writes the code with `write_files`, `publish_app` builds & deploys it, and the page is live in seconds. Or just ask Kleap's AI in plain English.*

**No secrets live in this package** — it reads your own `KLEAP_API_KEY` (or the
token saved by `kleap auth login`) and talks only to `kleap.co`.

---

## CLI (for agent shells — Claude Code, Codex, scripts)

If your agent drives a **bash tool** rather than MCP, use the CLI directly.
Output is 1-3 lines by default (token-efficient — built for an agent reading
its own tool output, not a human terminal), clean exit codes (`0`/`1`), and a
`--json` flag whenever you want the full structured response.

```bash
npx -y kleap-cli auth login              # opens your browser once, no key to paste
# — or, for CI / non-interactive: npx -y kleap-cli auth key kleap_live_sk_...

npx -y kleap-cli create "a one-page site for my bakery, warm palette"
# ✓ created app 4821 — https://warm-bakery-fold.kleap.io

npx -y kleap-cli edit 4821 "change the headline to 'Roasted slow'"
# ✓ edited app 4821 — https://warm-bakery-fold.kleap.io

npx -y kleap-cli publish 4821
# ✓ published https://warm-bakery-fold.kleap.io

npx -y kleap-cli status warm-bakery-fold.kleap.io   # by id, slug, kleap.io URL, or connected custom domain
# ✓ Bakery (4821) — live: https://warm-bakery-fold.kleap.io
```

### Commands

| Command | What it does |
|---|---|
| `kleap auth login` | Sign in via browser (OAuth, PKCE loopback) — no key to copy |
| `kleap auth key <KEY>` | Store a `kleap_live_sk_...` key instead (CI / non-interactive) |
| `kleap auth logout` / `kleap auth status` | Clear / show current auth |
| `kleap create "<prompt>" [--visibility public\|personal] [--webhook <url>] [--no-wait] [--json]` | Create a site, wait for the build (~5-15 min), print the live URL |
| `kleap edit <app> "<prompt>" [--webhook <url>] [--no-wait] [--json]` | Ask Kleap's AI to change a site, wait for it to redeploy |
| `kleap publish <app> [--no-wait] [--json]` | Publish/redeploy with the verified-live guarantee |
| `kleap status <app> [--json]` | One-line status: name, id, live URL or "not published" |
| `kleap list [--limit N] [--q text] [--json]` | Your apps, one tab-separated row each: `id  name  url` |
| `kleap domains search <query> [--tlds .com,.io] [--json]` | Available domains, one per line |
| `kleap domains connect <domain> <app> [--json]` | Connect a domain you own; prints the A record to set |
| `kleap screenshot <app> [--json]` | Capture a preview screenshot, print its URL |
| `kleap mcp` | Run the MCP stdio server explicitly (same as no args) |

`<app>` accepts a numeric app id, a `slug.kleap.io` URL, a bare slug, or a
connected custom domain — resolved server-side in one call
(`GET /apps/resolve`), same as the MCP `find_app` tool.

### Example: a Claude Code / bash-tool agent

```bash
# One-shot: build it, publish it, hand back a URL a human can click.
url=$(npx -y kleap-cli create "a landing page for my podcast" --json | node -e \
  'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>console.log(JSON.parse(d).url))')
echo "Live: $url"

# Non-blocking flow (agent does other work while it builds):
npx -y kleap-cli create "a landing page for my podcast" --no-wait --json   # → { task_id, app_id, ... }
# ... later ...
npx -y kleap-cli status 4821
```

Exit codes are always clean: `0` on success, `1` on any failure, with a single
`✗ <reason>` line on stderr (or `{"error":{"message":...}}` with `--json`) —
safe to check with `$?` / `try/except subprocess.run(..., check=True)` without
scraping prose.

### Install once (optional — `npx -y` above needs no install)

```bash
npm i -g kleap-cli
kleap auth login
kleap create "a one-page site for my bakery"
```

---

## MCP server (for MCP-native clients — Claude Desktop, Cursor, ChatGPT)

Same package, same account, same `~/.kleap/config.json` auth — just a
different transport for clients that speak [MCP](https://modelcontextprotocol.io)
instead of a bash tool.

### Easiest — connect with OAuth, no key

Add the hosted connector and sign in. **Nothing to generate, nothing to paste** —
you authorize Kleap in your browser like any other app. Works in Claude Desktop,
ChatGPT and Cursor.

```
https://kleap.co/api/mcp
```

- **Claude Desktop** — Settings → Connectors → **Add custom connector** → paste the URL → **Connect** → sign in to Kleap.
- **ChatGPT** — Settings → Connectors → add the URL → authorize with OAuth.
- **Cursor** — Settings → **MCP** → Add server → paste the URL → authorize.

That's it — same 17 tools, no API key. Skip straight to step 3.

---

### Or — local CLI, sign in with your browser (no key)

Prefer a local stdio process? Sign in once — no key to generate or paste:

```
npx kleap-cli auth login
```

This opens your browser, you authorize Kleap, and the token is saved to
`~/.kleap/config.json`. After that, `npx -y kleap-cli` just works. (`kleap auth
logout` / `kleap auth status` are there too.) Then add a keyless stdio entry to
your client, e.g. Claude Desktop `claude_desktop_config.json`:

```json
{ "mcpServers": { "kleap": { "command": "npx", "args": ["-y", "kleap"] } } }
```

---

### Or — local CLI with an API key

Prefer a key (e.g. for CI or scripting the REST API directly)?

**1. Get an API key** — at [kleap.co](https://kleap.co) → **Settings → API key →
MCP / API access → Generate MCP key** (`kleap_live_sk_...`).

**2. Add Kleap to your AI client:**

<details open>
<summary><b>Claude Desktop</b> — <code>claude_desktop_config.json</code></summary>

```json
{
  "mcpServers": {
    "kleap": {
      "command": "npx",
      "args": ["-y", "kleap"],
      "env": { "KLEAP_API_KEY": "kleap_live_sk_..." }
    }
  }
}
```
</details>

<details>
<summary><b>Cursor</b> — <code>.cursor/mcp.json</code></summary>

```json
{
  "mcpServers": {
    "kleap": {
      "command": "npx",
      "args": ["-y", "kleap"],
      "env": { "KLEAP_API_KEY": "kleap_live_sk_..." }
    }
  }
}
```
</details>

<details>
<summary><b>Claude Code</b> — one command</summary>

```bash
claude mcp add kleap -e KLEAP_API_KEY=kleap_live_sk_... -- npx -y kleap-cli
```
</details>

<details>
<summary><b>Cline / Roo (VS Code)</b> — <code>cline_mcp_settings.json</code></summary>

```json
{
  "mcpServers": {
    "kleap": {
      "command": "npx",
      "args": ["-y", "kleap"],
      "env": { "KLEAP_API_KEY": "kleap_live_sk_..." }
    }
  }
}
```
</details>

<details>
<summary><b>Windsurf</b> — <code>~/.codeium/windsurf/mcp_config.json</code></summary>

```json
{
  "mcpServers": {
    "kleap": {
      "command": "npx",
      "args": ["-y", "kleap"],
      "env": { "KLEAP_API_KEY": "kleap_live_sk_..." }
    }
  }
}
```
</details>

<details>
<summary><b>ChatGPT &amp; hosted agents</b> — no local process</summary>

Add the hosted connector at **`https://kleap.co/api/mcp`** and authorize with
OAuth (or paste your `kleap_live_sk_` key). Same tools, no install.
</details>

> Every stdio config is identical — `npx -y kleap-cli` + a `KLEAP_API_KEY` env var —
> so any MCP client works.

**Least-privilege keys:** when you generate a key, pick a scope — **Read-only**
(inspect sites, no changes), **Build**, or **Full**. Buying domains is never
included by default. Give a read-only agent a read-only key.

**3. Restart the client and just ask:**

> *"Build me a one-page site for my bakery, publish it, and give me the live URL."*
> *"Add a contact form to my site and redeploy."*
> *"Change the headline to 'Roasted slow' and publish."*

Works with **any MCP-compatible agent**: Claude · ChatGPT · Cursor · Claude Code · Codex.

---

## Tools

**Find & build** — `find_app` · `create_app` · `modify_app` · `read_files` · `write_files` · `rename_app` · `check_task` · `retry_task`
**Publish & domains** — `publish_app` · `get_publish_status` · `search_domains` · `check_domain` · `connect_domain`
**Account** — `list_apps` · `get_app` · `list_app_files` · `get_credits`

| Tool | What it does |
|------|--------------|
| `find_app` | Resolve a domain / URL / slug → app_id in one call |
| `create_app` | Create an Astro site from a prompt → returns a task (auto-deploys live) |
| `modify_app` | Ask the app's AI to change it → returns a task |
| `read_files` | Read the **current contents** of files so you can edit them safe