npm package: @portl/cli
Description: Portl CLI - BYOI orchestration for AI coding agents
Author: Portl
Latest version: 0.1.0

# Portl CLI

Interactive command-line tool for setting up and managing your Portl infrastructure connections.

## Installation

### Global Installation (Recommended)

```bash
npm install -g @portl/cli
```

After installation, the `portl` command will be available globally.

### Local Development

From the monorepo root:

```bash
npm install
npm run cli -- init
```

Or directly:

```bash
node portl-cli/bin/portl.js init
```

### Creating Global Alias (Development)

To use `portl` command during development:

```bash
# From the portl-cli directory
npm link
```

Now you can use `portl` from anywhere:

```bash
portl init
portl connect supabase
portl --help
```

## Commands

### `portl init`

Interactive setup wizard that walks you through connecting your infrastructure:

- **Database**: PostgreSQL, MySQL, MongoDB, Supabase, Neon, PlanetScale
- **Storage**: S3, Cloudflare R2, and compatible providers
- **Payments**: Stripe, Mercado Pago
- **CI/CD**: GitHub Actions

**Features:**
- Conversational yes/no flow
- Auto-detects API keys from environment
- Executes OAuth in real-time (when API key available)
- Generates `portl.config.json` and `.env.portl`

**Example:**
```bash
portl init
```

### `portl connect supabase`

Complete OAuth authentication for Supabase:

```bash
portl connect supabase
portl connect supabase --project-id my-app
portl connect supabase --no-open  # Don't auto-open browser
```

### `portl bootstrap`

Generate integration configurations:

#### GitHub Actions Workflow
```bash
portl bootstrap github-actions --repository owner/repo
```

#### Stripe Webhooks
```bash
portl bootstrap stripe-webhook --secret-key sk_test_xxx
```

#### Mercado Pago Webhooks
```bash
portl bootstrap mercadopago-webhook
```

## Configuration Files

### `portl.config.json`

Main configuration file generated by `portl init`:

```json
{
  "projectId": "my-app",
  "integrations": [
    {
      "providerId": "supabase",
      "category": "database",
      "config": {
        "setupMode": "oauth",
        "projectRef": "abc123"
      }
    }
  ]
}
```

### `.env.portl`

Environment variables template:

```bash
# Portl Environment Variables
# Generated by: portl init

# supabase (database)
PORTL_DB_SUPABASE_SETUP_MODE=oauth
PORTL_DB_SUPABASE_PROJECT_REF=abc123

# r2 (storage)
PORTL_STORAGE_R2_ACCOUNT_ID=your-account-id
PORTL_STORAGE_R2_ENDPOINT=https://account-id.r2.cloudflarestorage.com
PORTL_STORAGE_R2_ACCESS_KEY_ID=your-key
PORTL_STORAGE_R2_SECRET_ACCESS_KEY=your-secret
PORTL_STORAGE_R2_BUCKET=your-bucket
```

**Important:** Copy values from `.env.portl` to your `.env` file.

## Supported Providers

### Databases
- ✅ **Supabase** - PostgreSQL + Auth + Storage (OAuth or manual)
- ✅ **Neon** - Serverless PostgreSQL
- ✅ **PostgreSQL** - Self-hosted or managed
- ✅ **MySQL** - Self-hosted or managed
- ✅ **MongoDB** - Document database
- ✅ **PlanetScale** - Serverless MySQL

### Storage
- ✅ **Cloudflare R2** - S3-compatible, zero egress fees
- ✅ **Generic S3** - AWS S3 or compatible providers

### Payments
- ✅ **Stripe** - Payment processing
- ✅ **Mercado Pago** - Latin America payments

### CI/CD
- ✅ **GitHub Actions** - Automated workflows

## OAuth Flow

When you select OAuth authentication (e.g., Supabase):

1. **With API Key** (Automatic):
   ```bash
   # Set API key first
   export ACCESS_API_KEY=your-key
   
   # Run init
   portl init
   # Select Database → Supabase → OAuth
   # Browser opens automatically
   # OAuth completes immediately ✓
   ```

2. **Without API Key** (Manual):
   ```bash
   # Run init
   portl init
   # Select Database → Supabase → OAuth
   # Message: "Run portl connect supabase after init"
   
   # After init, set API key and connect
   export ACCESS_API_KEY=your-key
   portl connect supabase
   ```

## Environment Variables

### `ACCESS_API_KEY`

Required for live OAuth connections and backend validation.

**Set via environment:**
```bash
export ACCESS_API_KEY=your-api-key-here
```

**Or in `.env` file:**
```bash
# .env
ACCESS_API_KEY=your-api-key-here
```

The CLI auto-detects this key and enables OAuth flows automatically.

### `PORTL_OAUTH_CLI_REDIRECT_URI`

Optional. Override the default OAuth redirect URI:

```bash
export PORTL_OAUTH_CLI_REDIRECT_URI=http://localhost:7131/oauth/callback
```

## Troubleshooting

### Command not found: portl

**Solution 1:** Install globally
```bash
npm install -g @portl/cli
```

**Solution 2:** Use npm link (development)
```bash
cd portl-cli
npm link
```

**Solution 3:** Use direct path
```bash
node /path/to/portl-cli/bin/portl.js init
```

### OAuth timeout

If OAuth doesn't complete:

```bash
# Increase timeout (default: 2 minutes)
portl connect supabase --no-wait  # Skip waiting
# Then manually verify connection in dashboard
```

### Can't read browser opened status

The CLI tries to auto-open your browser. If it fails, copy the URL manually:

```bash
🔗 OAuth URL:
https://api.supabase.com/v1/oauth/authorize?...

⚠ Could not open browser automatically
ℹ Please open the URL above in your browser
```

## Examples

### Full Setup Flow

```bash
# Install CLI
npm install -g @portl/cli

# Set API key (optional, enables OAuth)
export ACCESS_API_KEY=your-key-here

# Run interactive setup
portl init

# Follow prompts:
# Project name: my-awesome-app
# Database? (Y/n): y
#   Provider: Supabase
#   OAuth? (Y/n): y
#   → Browser opens, auth completes automatically ✓
# Storage? (y/N): y
#   Provider: Cloudflare R2
#   → Enter credentials
# Payments? (y/N): n
# CI/CD? (y/N): n

# Files generated:
#   ✓ portl.config.json
#   ✓ .env.portl

# Copy environment variables
cat .env.portl >> .env

# Install SDK
npm install @portl/sdk

# Start building!
```

### Quick Start Without OAuth

```bash
portl init

# Database? y
# Provider: PostgreSQL
# Host: localhost
# Port: 5432
# Database: mydb
# User: postgres
# Password: ****

# Storage? n
# Payments? n
# CI/CD? n

# Done!
```

## Development

### Running Tests

```bash
npm test
```

### Building

```bash
npm run build
```

### Publishing

```bash
npm version patch  # or minor, major
npm publish --access public
```

## License

Apache-2.0

## Links

- [Documentation](https://portl.finns.lat/docs)
- [GitHub](https://github.com/your-org/portl)
- [Issues](https://github.com/your-org/portl/issues)