open-seo Command-Line Interfaces (CLIs): Complete Guide to Development, Database, and Deployment Tools

open-seo exposes its complete command-line interface surface through npm scripts defined in package.json, enabling developers to execute development workflows, database migrations, authentication generation, utility tasks, and Cloudflare deployments using pnpm run <command> or npm run <command>.

The open-seo repository provides a comprehensive CLI ecosystem that manages the entire application lifecycle without leaving the terminal. These command-line interfaces are orchestrated through standard npm scripts and share a common argument parsing infrastructure located in scripts/cli-utils.ts to ensure consistent configuration handling across SQLite, Postgres, and Cloudflare environments.

Development and Build CLIs

The foundation of daily development relies on standard Vite-based commands defined in package.json. These scripts handle the complete build pipeline from local development to production preview.

pnpm run dev starts the Vite development server with hot module replacement enabled for rapid iteration.

pnpm run build bundles the application for production deployment, optimizing assets and generating the distribution files.

pnpm run preview serves the production build locally to verify the bundled output before deployment:

pnpm run preview

Database Migration and Authentication CLIs

Database management commands handle schema migrations across multiple backends and generate authentication schemas via the better-auth CLI.

Database migrations support both SQLite (D1) and Postgres environments:

• pnpm run db:migrate:prod – Runs Wrangler/Drizzle migrations against the production SQLite (D1) database
• pnpm run db:migrate:pg – Executes migrations against the Postgres backend

Authentication schema generation creates type-safe auth configurations for both database backends:

pnpm run auth:generate        # Generates schemas for both backends

pnpm run auth:generate:d1     # SQLite/D1 specific schema

pnpm run auth:generate:pg     # Postgres specific schema

These commands are implemented in cli-auth.ts and integrate with the better-auth CLI to produce up-to-date TypeScript definitions.

Utility Scripts for Data Management

One-off operational tasks are handled by TypeScript utilities executed via tsx directly from the scripts/ directory. These CLIs perform data seeding, cost calculations, and maintenance operations.

Running utility scripts requires invoking tsx with the specific script path and optional flags:

tsx scripts/seed-rank-tracking.ts --projectId=123 --dryRun=true
tsx scripts/backlinks-cost-profile.ts

The scripts/cli-utils.ts module provides the underlying argument parsing for these commands, supporting --key=value or --flag style arguments and automatically loading local .env files when present. This shared utility underpins many scripts, including seed-rank-tracking.ts which populates the rank-tracking table with test data.

Deployment CLIs for Cloudflare and Alchemy

Production deployment commands orchestrate complex multi-step workflows involving database migrations, builds, and Cloudflare Worker deployment.

pnpm run deploy deploys the application to Cloudflare using the standard SQLite (D1) backend.

pnpm run deploy:postgres executes a sequential deployment pipeline for Postgres environments:

1. Runs db:migrate:pg to ensure schema consistency
2. Builds the application for production
3. Invokes the Alchemy deployment (alchemy.deploy) with production environment variables

pnpm run preview:access and alchemy.preview-access.run.ts provide temporary access to preview deployments for testing purposes.

Testing and Code Quality CLIs

Continuous integration and code quality are enforced through dedicated test and lint commands:

• pnpm run test – Executes unit tests via Vitest
• pnpm run test:e2e – Runs end-to-end tests via Playwright
• pnpm run lint – Performs static code analysis
• pnpm run format:check – Validates code formatting standards

These commands ensure that package.json serves as the single source of truth for quality gates across local development and CI pipelines.

Shared CLI Infrastructure

All scripts leverage the argument parsing helper in scripts/cli-utils.ts to maintain consistency across the CLI surface. This module:

• Parses --key=value and --flag style arguments from process.argv
• Loads environment variables from local .env files when present
• Provides type-safe access to configuration across utility scripts

This shared infrastructure enables the tsx scripts/<script>.ts pattern to function reliably across different execution contexts.

Summary

• open-seo exposes its CLI through npm scripts in package.json, accessible via pnpm run <command>
• Development workflows include dev, build, and preview for Vite-based operations
• Database commands support dual backends through db:migrate:prod (D1/SQLite) and db:migrate:pg (Postgres)
• Authentication generation via auth:generate creates schemas for both SQLite and Postgres using cli-auth.ts
• Utility scripts in the scripts/ directory handle data seeding and cost calculations, parsed by cli-utils.ts
• Deployment pipelines orchestrate Cloudflare and Alchemy deployments through deploy and deploy:postgres commands
• Testing infrastructure provides Vitest unit tests and Playwright E2E tests through dedicated npm scripts

Frequently Asked Questions

How do I start the development server in open-seo?

Execute pnpm run dev from the repository root. This command launches the Vite development server configured in package.json, enabling hot module replacement for rapid development cycles. The server automatically reloads when you modify source files in the project.

What is the difference between db:migrate:prod and db:migrate:pg?

db:migrate:prod targets the SQLite D1 database used in Cloudflare production environments, while db:migrate:pg executes migrations against the Postgres backend. The Postgres variant is typically used in conjunction with deploy:postgres for deployments requiring relational database features beyond D1's capabilities.

How does open-seo handle CLI argument parsing across utility scripts?

All utility scripts use the shared helper in scripts/cli-utils.ts to parse command-line arguments. This module standardizes --key=value and --flag formats, loads .env files automatically, and exposes parsed values through process.argv. This ensures consistent behavior whether running tsx scripts/seed-rank-tracking.ts or custom maintenance scripts.

Which CLI command deploys open-seo to Cloudflare with Postgres support?

Use pnpm run deploy:postgres, which executes a sequential pipeline: it first runs db:migrate:pg to ensure database schema consistency, then builds the production bundle, and finally invokes the Alchemy deployment wrapper (alchemy.run.ts) configured for Postgres environments. This command handles the complete deployment lifecycle in a single terminal invocation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}