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.

🚀 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:

# 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.

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:

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.