@fluid-app/rep-cli

Command-line interface for creating and managing Fluid rep portal applications.

Installation

Global Installation (Recommended)

pnpm add -g @fluid-app/rep-cli

After global installation, the fluid command is available everywhere:

fluid create my-portal

Local Installation

pnpm add -D @fluid-app/rep-cli

With local installation, use pnpm exec:

pnpm exec fluid create my-portal

Quick Start

# Create a new project
fluid create my-portal

# Navigate to project
cd my-portal

# Start development server
fluid dev

Then open http://localhost:5173 in your browser.

Commands

fluid create <app-name>

Create a new Fluid rep portal application.

fluid create my-portal

Arguments:

| Argument | Description | | ------------ | ---------------------------------------------------------------------- | | <app-name> | Name of the application (lowercase letters, numbers, and hyphens only) |

Options:

| Option | Description | Default | | --------------------------- | ---------------------------- | --------- | | -t, --template <template> | Template to use | starter | | --skip-install | Skip dependency installation | false |

Examples:

# Create with defaults (interactive prompts)
fluid create my-portal

# Create with specific template
fluid create my-portal --template starter

# Create fullstack template, skip install
fluid create my-portal --template fullstack --skip-install

fluid dev

Start the development server with hot module replacement.

fluid dev

Options:

| Option | Description | Default | | ------------------- | ------------------------------------ | ------- | | -p, --port <port> | Port to run the dev server on | 5173 | | --host | Expose the dev server to the network | false |

Examples:

# Start on default port
fluid dev

# Start on custom port
fluid dev --port 3000

# Expose to network (for mobile testing)
fluid dev --host

fluid build

Build the application for production.

fluid build

Options:

| Option | Description | Default | | --------------------- | ---------------- | ------- | | -o, --out-dir <dir> | Output directory | dist |

Examples:

# Build to default directory
fluid build

# Build to custom directory
fluid build --out-dir build

The build output is a static site that can be deployed to any hosting provider.

fluid deploy

Deploy a fullstack application to Google Cloud Run with a Turso database.

This command handles the full deployment flow:

1. Validates gcloud CLI and authentication
2. Provisions a Turso database (or reuses an existing one)
3. Builds and deploys the container to Cloud Run via gcloud run deploy --source

fluid deploy

Prerequisites:

• gcloud CLI installed and authenticated (gcloud auth login)
• Turso account with an API token (get one at https://app.turso.tech/api-tokens)
• A fullstack template project (must have src/server/index.ts and a Dockerfile)

Options:

| Option | Description | Default | | ------------------------- | --------------------------------------------------------- | ------------------ | | --staging | Deploy to staging environment | | | --region <location> | Cloud Run region | us-central1 | | --gcp-project <id> | GCP project ID (default: from gcloud config) | auto-detected | | --db-region <location> | Turso database group location | ord | | --require-auth | Require IAM authentication for the Cloud Run service | public (no auth) | | -p, --project <name> | Service name override (default: from package.json name) | from package.json |

Required Environment Variables:

Set these in your .env file or export them in your shell:

| Variable | Description | | ----------------------- | ------------------------------------ | | FLUID_COMPANY_API_KEY | Fluid company API key | | TURSO_API_TOKEN | Turso platform API token | | TURSO_ORG | Turso organization name |

Examples:

# Deploy with defaults (auto-detects GCP project, uses us-central1)
fluid deploy

# Deploy to a specific region with a custom GCP project
fluid deploy --region us-east1 --gcp-project my-gcp-project

# Deploy with a custom service name
fluid deploy --project my-service-name

# Deploy with IAM authentication (not publicly accessible)
fluid deploy --require-auth

# Deploy with a specific Turso database region
fluid deploy --db-region lax

Post-deploy: Remember to run database migrations against your production database:

DATABASE_URL=<your-turso-url> DATABASE_AUTH_TOKEN=<token> pnpm db:push

Note: For static sites (starter template), fluid deploy is not supported. Instead, build your project and deploy the dist/ folder to any static hosting provider (Vercel, Netlify, Firebase Hosting, etc.).

fluid destroy

Tear down a deployed Cloud Run service and its Turso database.

fluid destroy
fluid destroy --yes   # skip confirmation prompt

Templates

starter (Default)

A minimal starter template with:

• React 19 + TypeScript
• Vite for fast builds
• TailwindCSS 4 for styling
• FluidProvider pre-configured
• Basic navigation structure
• Example home screen

Project Structure:

my-portal/
├── src/
│   ├── main.tsx           # Entry point
│   ├── App.tsx            # Root component with FluidProvider
│   ├── fluid.config.ts    # API configuration
│   ├── index.css          # Global styles
│   ├── navigation/
│   │   └── index.tsx      # Navigation component
│   └── screens/
│       └── Home.tsx       # Home screen
├── package.json
├── tsconfig.json
├── vite.config.ts
└── .env.example

fullstack

A full-stack template with a Hono API server, Turso/SQLite database, and Cloud Run deployment:

• React 19 + TypeScript
• Vite for the frontend + Hono for the API server
• TailwindCSS 4 for styling
• Drizzle ORM + Turso (libSQL) for the database
• Zod for API request validation
• Vitest for testing
• Dockerfile for Cloud Run deployment
• GitHub Actions CI/CD workflows

Project Structure:

my-portal/
├── src/
│   ├── main.tsx              # Frontend entry point
│   ├── App.tsx               # Root component with FluidProvider
│   ├── fluid.config.ts       # API configuration
│   ├── index.css             # Global styles
│   ├── server/
│   │   ├── index.ts          # Hono app setup
│   │   ├── entry.ts          # Production server entry
│   │   ├── db/
│   │   │   ├── index.ts      # Database client
│   │   │   └── schema.ts     # Drizzle schema
│   │   └── routes/
│   │       ├── index.ts      # API routes
│   │       └── schemas.ts    # Zod validation schemas
│   └── test/
│       └── setup.ts          # Test setup
├── .github/workflows/
│   ├── ci.yml                # PR checks
│   └── deploy.yml            # Production deployment
├── Dockerfile
├── drizzle.config.ts
├── esbuild.config.js
├── vite.config.ts
├── vitest.config.ts
└── package.json

Database Setup:

During local development, the fullstack template uses a local SQLite file (file:local.db). For production, fluid deploy provisions a Turso database automatically.

# Push schema to local database
pnpm db:push

# Open Drizzle Studio to browse data
pnpm db:studio

# Generate a migration
pnpm db:generate

Dev Workflow:

# Create a fullstack project
fluid create my-app --template fullstack

# Start development (frontend + API server with HMR)
cd my-app
pnpm dev

# Run tests
pnpm test

# Deploy to Cloud Run + Turso
fluid deploy

Requirements

• Node.js 18 or higher
• pnpm — install via corepack enable or pnpm.io

Environment Variables

Configure your project by copying .env.example to .env:

cp .env.example .env

Required variables:

| Variable | Description | | -------------------- | --------------------------- | | VITE_FLUID_API_URL | Fluid Commerce API base URL |

Troubleshooting

"command not found: fluid"

If installed globally, ensure your pnpm global bin directory is in your PATH:

pnpm bin -g
# Add the output to your PATH

"No package.json found"

The dev and build commands must be run from within a Fluid project directory (a directory containing package.json and vite.config.ts).

"Template not found"

Ensure you're using a valid template name. Currently available: starter, fullstack

Port already in use

If port 5173 is in use, specify a different port:

fluid dev --port 3000

Related Packages

• @fluid-app/rep-sdk - SDK for building custom Fluid rep portals

License

Private - Fluid Commerce