npm package: @fuseplane/cli
Description: The official CLI for Fuseplane, designed to simplify the integration of Fuseplane into your project.
Author: fuseplane-cli
Latest version: 0.1.13

# @fuseplane/cli

The official CLI for Fuseplane, designed to simplify the integration of Fuseplane into your project.

## Features

- **Automatic Framework Detection:** Identifies your project framework (Next.js, Vite, etc.) and suggests the optimal configuration.
- **Dedicated Subdomain Routing:** Automatically configures your project to route requests to your dedicated FusePlane subdomain (`https://<id>.fuseplane.com`).
- **One-Command Setup:** Initialize your project with a single command that handles environment variables and proxy configuration.
- **Proxy Configuration:** Automatically configures proxy settings for local development (Vite, Next.js, etc.) to forward requests securely.
- **Template Generation:** Scaffolds necessary API routes and configuration files based on your deployment target (Vercel, Next.js, etc.).
- **Local Development Server:** `dev` command to run a local proxy server for frameworks without native proxy support.

## Installation

You can use the CLI directly with `npx` or install it globally.

### Using npx (Recommended)

```bash
npx @fuseplane/cli init
```

### Global Installation

```bash
npm install -g @fuseplane/cli
```

## Usage

### Initialize Fuseplane

Run the init command in your project root to set up Fuseplane:

```bash
fuseplane init
# or
npx @fuseplane/cli init
```

The CLI will:
1. Detect your framework and language (TypeScript/JavaScript).
2. Ask for your deployment platform (if applicable).
3. Create or update your `.env` file with placeholders for `FUSEPLANE_SECRET_KEY` and `FUSEPLANE_URL`.
4. Create a minimal `fuseplane.config.json` file.
5. Generate the necessary API route handler or proxy configuration for your project.

### Configuration

After running `init`, you **MUST** configure your environment variables in `.env`:

```env
FUSEPLANE_SECRET_KEY=your_secret_key_here
FUSEPLANE_URL=https://<your-project-id>.fuseplane.com
```

- **FUSEPLANE_SECRET_KEY**: Your project's secret key from the FusePlane dashboard.
- **FUSEPLANE_URL**: Your dedicated FusePlane Gateway URL (e.g., `https://a1b2c3d4.fuseplane.com`).

### How It Works

**Local Development:**
The CLI injects a proxy configuration (e.g., in `vite.config.ts` or `next.config.js`) that intercepts requests starting with your Project ID (e.g., `/a1b2c3d4/...`). It securely adds your Secret Key and forwards the request to your dedicated FusePlane URL.

**Production:**
The CLI generates a serverless function or API route (e.g., `/api/p/[...path]`) that handles production traffic. It uses the `FUSEPLANE_URL` and `FUSEPLANE_SECRET_KEY` from your production environment variables to route requests securely.

### Supported Frameworks & Platforms

- **Next.js** (App Router & Pages Router)
- **Vite** (React, Vue, Svelte, etc.)
- **Vercel** (Edge Functions & Serverless Functions)
- **Netlify** (Functions)
- **Cloudflare Pages** (Functions)
- **AWS Lambda**
- **Express / Node.js** (Railway, Render, etc.)

### Local Development Server

If your framework doesn't support easy proxy configuration, you can use the Fuseplane dev server:

```bash
fuseplane dev
# or
npx @fuseplane/cli dev
```