npm package: @flightdev/cli
Description: Command-line interface for Flight Framework
Author: Flight Contributors
Latest version: 0.4.17

# @flightdev/cli

The command-line interface for Flight Framework. Create, develop, build, and deploy full-stack applications with a single tool.

## Table of Contents

- [Installation](#installation)
- [Creating a Project](#creating-a-project)
- [Development](#development)
- [Building for Production](#building-for-production)
- [Running in Production](#running-in-production)
- [Generate Commands](#generate-commands)
- [Configuration](#configuration)
- [Environment Variables](#environment-variables)
- [All Commands Reference](#all-commands-reference)
- [Troubleshooting](#troubleshooting)
- [License](#license)

---

## Installation

### Global Installation (Recommended)

```bash
npm install -g @flightdev/cli
```

After installation, the `flight` command is available globally:

```bash
flight --version
flight --help
```

### Using npx (No Installation)

Run commands without installing:

```bash
npx @flightdev/cli create my-app
npx @flightdev/cli dev
```

### Using pnpm or yarn

```bash
pnpm add -g @flightdev/cli
# or
yarn global add @flightdev/cli
```

---

## Creating a Project

### Interactive Mode

Run `create` without arguments for the interactive wizard:

```bash
flight create
```

The wizard guides you through:
1. Project name
2. UI framework selection
3. TypeScript or JavaScript
4. Additional features (forms, auth, i18n, etc.)

### Quick Start

Create a project with defaults (React + TypeScript):

```bash
flight create my-app
cd my-app
npm install
flight dev
```

### With Options

Specify options to skip prompts:

```bash
# React with TypeScript (default)
flight create my-app

# Vue with TypeScript
flight create my-app --ui vue

# Svelte with JavaScript
flight create my-app --ui svelte --no-typescript

# Solid with all features
flight create my-app --ui solid --features forms,auth,i18n
```

### Available UI Frameworks

| Framework | Option | Description |
|-----------|--------|-------------|
| React | `--ui react` | Default. Best ecosystem support |
| Vue | `--ui vue` | Composition API with SFC support |
| Svelte | `--ui svelte` | Compiler-based, minimal runtime |
| Solid | `--ui solid` | Fine-grained reactivity |
| Preact | `--ui preact` | Lightweight React alternative |
| Qwik | `--ui qwik` | Resumability-first |
| Lit | `--ui lit` | Web Components |
| HTMX | `--ui htmx` | HTML-driven interactivity |

### Create Options

| Option | Description |
|--------|-------------|
| `--ui <framework>` | UI framework to use |
| `--typescript` | Use TypeScript (default) |
| `--no-typescript` | Use JavaScript |
| `--features <list>` | Comma-separated features: forms, auth, i18n, db |
| `--package-manager <pm>` | npm, pnpm, yarn, or bun |
| `--git` | Initialize git repository (default: true) |
| `--no-git` | Skip git initialization |
| `--install` | Install dependencies (default: true) |
| `--no-install` | Skip dependency installation |
| `--raw` | Create raw project (100% Web Standards, zero dependencies) |
| `--empty` | Create empty project (just package.json) |
| `--minimal` | Create minimal project (single server file) |

### Toolbox Mode (Zero Lock-in)

Start with the minimum and add what you need:

```bash
# Raw project - 100% Web Standards, ZERO dependencies
# Works on Bun, Deno, Node 22+, Cloudflare Workers
flight create my-app --raw

# Empty project - just package.json
flight create my-app --empty

# Minimal project - single server file with Flight
flight create my-app --minimal

# Then add packages as needed
cd my-app
flight add http
flight add db
flight add cache
```

The `--raw` mode generates code with **zero Flight dependencies**. You can run it on any runtime and add Flight packages later if you want.

---

## Adding Packages

Add Flight packages to an existing project:

```bash
flight add [package]
```

### Available Packages

| Package | Description |
|---------|-------------|
| `http` | HTTP server with routing and middleware |
| `core` | File-based routing and configuration |
| `db` | Database abstraction layer |
| `cache` | Caching with multiple adapters |
| `auth` | Authentication adapters |
| `forms` | Type-safe form handling |
| `i18n` | Internationalization |
| `seo` | SEO utilities |
| `image` | Image optimization |
| `email` | Email sending |
| `realtime` | WebSocket and real-time features |
| `helpers` | Optional helper utilities |

### Examples

```bash
# Add HTTP server
flight add http

# Add database support
flight add db

# Add authentication
flight add auth

# See all packages
flight add
```

---

## Development

Start the development server with hot module replacement:

```bash
flight dev
```

The dev server includes:
- Hot Module Replacement (HMR)
- Server-Side Rendering (if enabled)
- API routes with hot reload
- TypeScript type checking
- Error overlay with source maps

### Dev Options

| Option | Default | Description |
|--------|---------|-------------|
| `-p, --port <number>` | `5173` | Port number |
| `-h, --host <host>` | `localhost` | Host to bind |
| `--open` | `false` | Open browser automatically |
| `--https` | `false` | Enable HTTPS with self-signed cert |
| `--ssr` | from config | Enable/disable SSR |
| `--no-ssr` | - | Disable SSR for this session |
| `--force` | `false` | Force re-optimization of dependencies |

### Examples

```bash
# Start on port 3000
flight dev -p 3000

# Bind to all interfaces (for network access)
flight dev --host 0.0.0.0

# Open browser and enable HTTPS
flight dev --open --https

# Disable SSR temporarily
flight dev --no-ssr
```

---

## Building for Production

Build optimized bundles for production:

```bash
flight build
```

The build process:
1. Type checks the project
2. Bundles client and server code
3. Optimizes assets (minification, tree-shaking)
4. Generates static pages (if configured)
5. Creates deployment artifacts

### Build Options

| Option | Default | Description |
|--------|---------|-------------|
| `--target <adapter>` | from config | Deployment target |
| `--analyze` | `false` | Generate bundle analysis |
| `--sourcemap` | `false` | Include source maps |
| `--no-minify` | - | Skip minification |

### Deployment Targets

```bash
# Node.js server (default)
flight build --target node

# Cloudflare Workers
flight build --target cloudflare

# Vercel
flight build --target vercel

# Netlify
flight build --target netlify

# Static site
flight build --target static

# Docker
flight build --target docker
```

### Build Output

```
dist/
  client/           # Browser bundles
    assets/
    index.html
  server/           # Server code
    index.js
  static/           # Pre-rendered pages
```

---

## Running in Production

Start the production server:

```bash
flight start
```

This runs the optimized build with:
- Compression enabled
- Static asset caching
- Production error handling
- Health check endpoint at `/_health`

### Start Options

| Option | Default | Description |
|--------|---------|-------------|
| `-p, --port <number>` | `3000` | Port number |
| `-h, --host <host>` | `0.0.0.0` | Host to bind |
| `--cluster` | `false` | Enable cluster mode |
| `--workers <number>` | CPU cores | Number of workers |

### Examples

```bash
# Start on port 8080
flight start -p 8080

# Enable cluster mode for multi-core
flight start --cluster --workers 4
```

---

## Generate Commands

Scaffold new files with correct structure:

```bash
flight generate <type> <name>
# or shorthand
flight g <type> <name>
```

### Available Generators

| Type | Alias | Description |
|------|-------|-------------|
| `page` | `p` | New page component |
| `api` | `a` | API route handler |
| `component` | `c` | UI component |
| `action` | `act` | Server action |
| `middleware` | `mw` | Middleware function |
| `layout` | `l` | Layout component |

### Examples

```bash
# Generate a page at /dashboard
flight g page dashboard

# Generate an API route at /api/users
flight g api users

# Generate a reusable component
flight g component Button

# Generate a server action
flight g action submitForm

# Generate middleware
flight g middleware auth
```

### Generated Files

```bash
flight g page dashboard
# Creates: src/routes/dashboard.page.tsx

flight g api users
# Creates: src/routes/api/users.get.ts
#          src/routes/api/users.post.ts

flight g component Button
# Creates: src/components/Button.tsx
#          src/components/Button.css
```

---

## Configuration

Flight uses `flight.config.ts` (or `.js`) in the project root:

```typescript
// flight.config.ts
import { defineConfig } from '@flightdev/core';

export default defineConfig({
  // Server configuration
  server: {
    port: 3000,
    host: 'localhost',
  },

  // Rendering options
  render: {
    defaultMode: 'ssr',        // 'ssr' | 'ssg' | 'spa'
    streaming: true,
  },

  // Build options
  build: {
    outDir: 'dist',
    target: 'node',            // Deployment target
    minify: true,
    sourcemap: false,
  },

  // Routes configuration
  routes: {
    directory: 'src/routes',
  },
});
```

---

## Environment Variables

Flight automatically loads environment variables:

| File | Environment | Priority |
|------|-------------|---------|
| `.env` | All | 1 (lowest) |
| `.env.local` | All | 2 |
| `.env.development` | Development | 3 |
| `.env.production` | Production | 3 |
| `.env.development.local` | Development | 4 (highest) |
| `.env.production.local` | Production | 4 (highest) |

### Accessing Variables

```typescript
// Server-side (full access)
const apiKey = process.env.API_KEY;

// Client-side (only PUBLIC_ prefix)
const publicUrl = process.env.PUBLIC_API_URL;
```

Only variables prefixed with `PUBLIC_` are exposed to the browser.

---

## All Commands Reference

| Command | Description |
|---------|-------------|
| `flight create [name]` | Create new project |
| `flight dev` | Start development server |
| `flight build` | Build for production |
| `flight start` | Start production server |
| `flight generate <type> <name>` | Generate files |
| `flight typecheck` | Run TypeScript type checking |
| `flight lint` | Run ESLint |
| `flight test` | Run tests |
| `flight preview` | Preview production build locally |
| `flight upgrade` | Upgrade Flight packages |
| `flight info` | Display project information |

### Global Options

Available on all commands:

| Option | Description |
|--------|-------------|
| `--help` | Show help |
| `--version` | Show version |
| `--config <path>` | Path to config file |
| `--cwd <path>` | Working directory |
| `--verbose` | Verbose output |
| `--quiet` | Minimal output |

---

## Troubleshooting

### Port Already in Use

```bash
# Use a different port
flight dev -p 3001

# Or kill the process using the port
npx kill-port 5173
```

### TypeScript Errors on Start

```bash
# Force rebuild of type cache
flight dev --force
```

### Permission Denied (Global Install)

```bash
# Fix npm permissions
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

# Or use npx instead
npx @flightdev/cli dev
```

### Slow Dev Server

Check for large `node_modules` in the routes directory, or try:

```bash
# Clear Vite cache
rm -rf node_modules/.vite
flight dev
```

### Build Fails with Memory Error

Increase Node.js memory limit:

```bash
NODE_OPTIONS="--max-old-space-size=8192" flight build
```

---

## License

MIT