@formgrid/cli

A Supabase-like CLI for managing and running Formgrid locally with Docker.

Installation

Global Installation (Recommended)

# Install from npm
npm install -g formgrid-cli

Usage

Important: The CLI must be run from your FormGrid project root directory.

# 1. Navigate to your FormGrid project
cd /path/to/formgrid

# 2. Run commands
formgrid start
formgrid status
formgrid logs

First Time Setup

# Clone FormGrid
git clone https://github.com/allenarduino/formgrid.git
cd formgrid

# Install dependencies
pnpm install

# Initialize environment files
formgrid init

# Start with CLI
formgrid start -d

Local Usage (Development)

# From the monorepo root
pnpm cli:dev -- <command>

# Or directly
cd packages/cli
pnpm dev -- <command>

Commands

formgrid init

Initialize FormGrid by creating required environment files.

formgrid init

What it does:

• Creates docker/.env from example or with defaults
• Creates packages/api/.env from example or with defaults
• Sets up minimal configuration to get started
• Skips files that already exist

Run this first before starting FormGrid for the first time.

formgrid start

Start Formgrid locally using Docker Compose.

formgrid start              # Start all services (interactive)
formgrid start --detached   # Start in background (detached mode)
formgrid start -d           # Same as above

What it does:

• Starts MySQL database
• Starts Redis
• Starts MinIO (S3-compatible storage)
• Starts backend API
• Starts frontend dashboard
• Starts queue worker

Access your services:

• Dashboard: http://localhost:5173
• API: http://localhost:4001
• MinIO Console: http://localhost:9001

formgrid stop

Stop all Formgrid Docker containers.

formgrid stop

formgrid restart

Restart all Formgrid Docker containers.

formgrid restart

formgrid logs

View logs for running Formgrid containers.

formgrid logs                      # Follow all logs
formgrid logs --service backend    # Backend logs only
formgrid logs --service frontend   # Frontend logs only
formgrid logs --service db         # Database logs only
formgrid logs -s redis             # Redis logs only

Available services: backend, frontend, db, redis, minio, queue-worker

formgrid ps

List all running Formgrid containers.

formgrid ps

formgrid status

Check the status of all Formgrid services.

formgrid status

Shows which services are running, stopped, or healthy.

formgrid clean

Stop containers and remove volumes (clean slate).

formgrid clean

Warning: This will delete all data including:

• Database data
• Redis cache
• MinIO files
• Uploaded files

formgrid migrate

Run database migrations.

formgrid migrate

Runs Prisma migrations inside the backend container.

Quick Start

# 1. Start Formgrid
formgrid start -d

# 2. Check status
formgrid status

# 3. View logs
formgrid logs

# 4. Stop when done
formgrid stop

Development

Running the CLI in Development

# From monorepo root
pnpm cli:dev -- start

# Or from packages/cli
pnpm dev -- start

Building the CLI

# From monorepo root
pnpm cli:build

# Or from packages/cli
pnpm build

Architecture

The CLI is built with:

• Commander.js - CLI framework
• Chalk - Colorful terminal output
• Ora - Elegant terminal spinners
• Execa - Better child_process
• TypeScript - Type safety
• tsup - Fast TypeScript bundler

Examples

Start Formgrid for development

formgrid start

Start in background and check logs

formgrid start -d
formgrid logs --service backend

Reset everything and start fresh

formgrid clean
formgrid start

Check what's running

formgrid status
formgrid ps

Troubleshooting

"docker: command not found"

Make sure Docker is installed and running:

docker --version
docker ps

"Cannot connect to the Docker daemon"

Start Docker Desktop or the Docker daemon.

Services not starting

Check logs for specific service:

formgrid logs --service backend

Clean and restart:

formgrid clean
formgrid start

Environment Variables

The CLI uses the Docker Compose configuration in docker/docker-compose.yml.

Make sure you have:

• docker/.env with required environment variables
• Docker and Docker Compose installed

Publishing

To publish to npm (for maintainers):

cd packages/cli
pnpm build
npm publish --access public

License

MIT

FormGrid CLI - Manage your local Formgrid instance with ease! 🚀