npm package: @flying-pillow/manager
Description: Flying Pillow installation CLI
Latest version: 0.1.0-beta.33

# Flying Pillow CLI

The official command-line interface for installing, configuring, and managing the **Flying Pillow** platform.

This tool streamlines the deployment of the Flying Pillow monorepo, handling source code retrieval, environment configuration, SSL certificates, and Docker orchestration across Development, Staging, and Production environments.

![Version](https://img.shields.io/npm/v/@flying-pillow/cli?label=version)
![License](https://img.shields.io/npm/l/@flying-pillow/cli)

## 🚀 Quick Start (Installation)

To install the Flying Pillow platform on a new server or local machine, you do not need to clone the repository manually. The CLI handles everything.

**Run the installer via `npx`:**

```bash
# Install the latest beta version
npx @flying-pillow/cli@beta install
```

**What this does:**

1. Downloads the correct source code version from GitHub.
2. Extracts it to your specified directory.
3. Launches an interactive configuration wizard to set up:
   - Domain names and SSL (Let's Encrypt or Local).
   - System credentials.
   - Docker networking and environment variables.
4. Starts your selected services.

---

## 🛠 Management (Day-2 Operations)

Once installed, you use the CLI to manage the lifecycle of your environments.

### Option A: Global Installation (Recommended)

For the best experience, install the CLI globally so the `fp` command is available anywhere.

```bash
npm install -g @flying-pillow/cli@beta
```

### Option B: Run via NPX

If you prefer not to install globally, you can execute commands inside your installation directory using `npx`:

```bash
cd /path/to/flying-pillow
npx @flying-pillow/cli@beta <command>
```

---

## 📖 Command Reference

### `fp install [gateway]`

Runs the full installation wizard.

- `fp install`: Installs the full stack (Gateway + App Environments).
- `fp install gateway`: Configures only the Gateway (Traefik, DNS, TLS) service.

### `fp up <target>`

Starts the services for a specific environment. Handles Docker networking and volume mounts automatically.

- **Targets:** `gateway`, `dev`, `staging`, `prod`
- **Example:** `fp up prod`

### `fp down <target>`

Stops and removes the containers for a specific environment.

- **Example:** `fp down staging`

### `fp rebuild <target> [services...]`

Forces a rebuild of Docker images for specific services. Useful after updating code or configuration.

- **Example:** `fp rebuild prod app wss` (Rebuilds only the App and Websocket services in Production)

### `fp logs <target> [service]`

Tails the logs for an environment or a specific service.

- **Example:** `fp logs gateway` (View Traefik logs)
- **Example:** `fp logs prod app` (View logs for the main application container)

### `fp backup <target>`

Performs a full backup of the SurrealDB database (Global + all Tenants) for the specified environment.

- **Targets:** `dev`, `staging`, `prod`
- **Example:** `fp backup prod`
- **Configuration:**
  - Uses `CONFIG_PATH` from your `.env` file by default.
  - Can be overridden by setting `BACKUP_FOLDER` in your `.env` file.
  - The CLI will interactively confirm the backup location before proceeding.
- **Output:** Backups are stored in `<backup-folder>/backups/<timestamp>/`.
  - Includes `.surql` exports for Global and all Tenant databases.
  - Includes a copy of the raw data folders for each tenant (with ownership preserved).
  - Includes `backup_info.json` with metadata (date, system version, tenant list).

### `fp upgrade`

Automates the upgrade process by fetching the latest source code while preserving your existing `.env` configurations and data volumes.
**Note:** This command automatically performs a full system backup before applying any changes.

---

## 📋 Prerequisites

Before running the CLI, ensure your system meets these requirements:

- **OS:** Linux (Ubuntu/Debian recommended) or macOS.
- **Node.js:** Version 22 or higher.
- **Docker:** Engine 24+ with Docker Compose Plugin (`docker compose`).
- **Permissions:** User must be in the `docker` group (Linux) to run containers without sudo.

## 🔒 Security & Ports

The CLI configures a secure Gateway (Traefik) to route traffic. Ensure the following ports are open on your host:

- **80 / 443:** HTTP/HTTPS traffic (handled by Gateway).
- **8080:** SurrealDB (if running in Dev mode).
- **Other:** Specific services may expose internal ports in Dev mode (e.g., `5678` for debugging).

## 📄 License

This CLI is distributed under the ISC License.