npm package: @portl/install
Description: Complete Portl setup: local-first wizard + MCP installation for AI agents
Author: Portl
Latest version: 0.3.0

# @portl/install

Complete Portl setup: runs interactive wizard + installs MCP for all your AI agents.

**Local-first**: No external cloud dependency. Backend runs on localhost, credentials auto-generated.

## Quick Start

```bash
# One command, complete setup
npx @portl/install
```

This will:
1. Run the setup wizard (asks about integrations)
2. Create `.portl/runtime.json` with auto-generated API key
3. Generate `.env` with backend defaults
4. Detect all AI agents on your system
5. Configure MCP for each detected agent
6. Done!

## What Gets Created

### `.portl/runtime.json` (local credentials)
```json
{
  "apiBaseUrl": "http://localhost:7130/api",
  "apiKey": "ik_abc123...",
  "projectId": "my-app",
  "updatedAt": "2026-03-22T..."
}
```

### `.env` (backend config)
```bash
PORT=7130
ACCESS_API_KEY=ik_abc123...
JWT_SECRET=...
POSTGRES_HOST=localhost
POSTGRES_DB=portl
PORTL_LOCAL_MODE=true
```

### MCP Config (example: Cursor)
```json
{
  "mcpServers": {
    "portl": {
      "command": "npx",
      "args": ["-y", "@portl/mcp@latest"]
    }
  }
}
```

**Note:** MCP reads credentials from `.portl/runtime.json` automatically. No need to embed keys in agent configs.

## Options

```bash
# Full setup (recommended)
npx @portl/install

# Skip wizard, just configure MCP
npx @portl/install --skip-wizard

# Install for specific agent only
npx @portl/install --client cursor

# Custom backend URL
npx @portl/install --env API_BASE_URL=http://custom:3000

# List detected agents
npx @portl/install --list
```

## Supported Agents (14)

| Agent | Auto-detected | Config Location |
|-------|---------------|-----------------|
| Cursor | ✓ | `~/.cursor/mcp.json` |
| Claude Code | ✓ | `./.mcp.json` |
| Claude Desktop | ✓ | OS-specific |
| GitHub Copilot | ✓ | `./.vscode/mcp.json` |
| Codex | ✓ | `~/.codex/config.toml` |
| Windsurf | ✓ | `~/.codeium/windsurf/mcp_config.json` |
| Cline | ✓ | `~/.cline/mcp_settings.json` |
| + 7 more... | ✓ | See `--list` |

## How It Works

### 1. Setup Wizard (portl init)

Interactive wizard asks:
- Project name
- What database? (Supabase, Neon, PostgreSQL...)
- Need storage? (Cloudflare R2, AWS S3...)
- Need payments? (Stripe, Mercado Pago...)
- Need CI/CD? (GitHub Actions...)

Generates:
- `.portl/runtime.json` - Local credentials (API key, URLs)
- `portl.config.json` - Your integrations config
- `.env` - Backend environment with secrets

### 2. MCP Installation

Detects AI agents on your system and writes minimal config:

**Cursor** (`~/.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "portl": {
      "command": "npx",
      "args": ["-y", "@portl/mcp@latest"]
    }
  }
}
```

**Codex** (`~/.codex/config.toml`)
```toml
[mcp_servers.portl]
type = "stdio"
command = "npx"
args = ["-y","@portl/mcp@latest"]
```

MCP server automatically:
- Reads `.portl/runtime.json` from your project
- Connects to backend with generated API key
- Provides tools to AI agent

### 3. Start Backend & Use

```bash
# Start Portl backend
npm run dev

# In your AI agent
"Use Portl to create a users table with email and name"
```

## Command Line Options

```
-c, --client <agent>    Install for specific agent only
-e, --env <KEY=value>   Override environment variable
-l, --list              List all supported agents
--skip-wizard           Skip setup, just install MCP
-h, --help              Show help
```

## Examples

```bash
# First time setup (recommended)
npx @portl/install

# Already configured, just update MCP
npx @portl/install --skip-wizard

# Only configure Cursor
npx @portl/install --client cursor

# Use production backend
npx @portl/install --env API_BASE_URL=https://api.portl.dev

# See what agents you have
npx @portl/install --list
```

## After Installation

1. **Start backend**: `npm run dev` (port 7130)
2. **Restart** your AI coding agent(s)
3. **Test**: "Use Portl to show database config"
4. **Build**: "Create a blog with posts table"

## Troubleshooting

**"No agents detected"**
- Install Cursor, Claude Code, or another MCP-compatible agent
- Run `npx @portl/install --list` to see detection status

**"Wizard failed"**
- Installation continues with MCP setup
- Configure manually: `npx @portl/cli init`

**"Connection refused"**
- Start the backend: `npm run dev`
- Check `.portl/runtime.json` has correct `apiBaseUrl`

## Local-First Architecture

```
Your Project/
├── .portl/
│   └── runtime.json          ← Credentials (auto-generated)
├── portl.config.json         ← Integrations (from wizard)
├── .env                      ← Backend config
└── your-code/

AI Agent → @portl/mcp (reads .portl/runtime.json)
         ↓
    Backend (localhost:7130)
         ↓
    Your Infrastructure (Supabase, Neon, etc.)
```

**Benefits:**
- No external Portl cloud account needed
- Full control over your data
- Works offline (with local services)
- API key stays local (never sent to cloud)

## License

Apache 2.0