CLI Tools

The @effect-gql/cli package provides command-line tools for common development tasks like generating GraphQL SDL from your code-first schema.

Installation

npm

npm install @effect-gql/cli

pnpm

pnpm add @effect-gql/cli

yarn

yarn add @effect-gql/cli

Or use directly with npx:

npx @effect-gql/cli <command>

Commands

generate-schema

Generate GraphQL SDL (Schema Definition Language) files from your code-first schema without starting your server.

# Generate SDL to stdout
effect-gql generate-schema ./src/schema.ts

# Write to file
effect-gql generate-schema ./src/schema.ts -o schema.graphql

# Watch mode - regenerate on changes
effect-gql generate-schema ./src/schema.ts -o schema.graphql --watch

Options

Option	Description
-o, --output <file>	Write SDL to file instead of stdout
--no-sort	Don’t sort schema alphabetically (default: sorted)
-w, --watch	Watch for changes and regenerate
-h, --help	Show help message

Module Exports

Your schema module should export one of:

// Option 1: Export builder
export const builder = GraphQLSchemaBuilder.empty.pipe(
  query("hello", { ... }),
  objectType({ ... })
)

// Option 2: Export schema
export const schema = builder.buildSchema()

// Option 3: Default export
export default builder

create

Scaffold a new Effect GraphQL project with your choice of server runtime.

# Basic usage
effect-gql create my-api --server-type node

# Short form
effect-gql create my-api -s bun

# Interactive mode (prompts for options)
effect-gql create

Server Types

Type	Package	Best For
node	@effect-gql/node	General Node.js deployments
bun	@effect-gql/bun	Bun runtime with native WebSocket support
express	@effect-gql/express	Integrating into existing Express apps
web	@effect-gql/web	Cloudflare Workers, Deno, edge runtimes

Options

Option	Description
-s, --server-type <type>	Server type: node, bun, express, or web (required)
-d, --directory <path>	Target directory (default: ./<name>)
--monorepo	Create as a workspace package (auto-detected)
--skip-install	Skip dependency installation
--package-manager <pm>	Package manager: npm, pnpm, yarn, or bun
-i, --interactive	Interactive mode with prompts
-h, --help	Show help message

Monorepo Support

The CLI automatically detects if you’re inside a monorepo by looking for:

• pnpm-workspace.yaml
• package.json with workspaces field
• turbo.json

When in a monorepo, @effect-gql/* dependencies use workspace:* instead of version numbers:

# Inside a pnpm monorepo
effect-gql create packages/api -s node --monorepo

// Generated package.json
{
  "dependencies": {
    "@effect-gql/core": "workspace:*",
    "@effect-gql/node": "workspace:*",
    // ...
  }
}

Generated Project Structure

my-api/
├── package.json
├── tsconfig.json
├── .gitignore
└── src/
    └── index.ts    # Server entry point with example schema

Examples

# Create a Node.js server
effect-gql create my-api --server-type node

# Create a Bun server in a specific directory
effect-gql create my-api -s bun -d ./packages/graphql

# Create an Express middleware project without installing deps
effect-gql create my-api -s express --skip-install

# Create a Cloudflare Worker
effect-gql create my-worker -s web

# Add to an existing monorepo
effect-gql create @myorg/api -s node -d packages/api --monorepo

Why This Matters

In code-first GraphQL frameworks, the schema is typically built at runtime. This often means you need to:

1. Start your server with all dependencies (database, external services, etc.)
2. Mock or stub every Effect layer just to generate SDL

Effect GQL separates schema building from query execution. The R type parameter tracks service requirements, but these are only needed when resolvers actually run—not when constructing the schema structure.

import { generateSDL } from "@effect-gql/cli"

// This works without any DatabaseService layer!
const builder = GraphQLSchemaBuilder.empty.pipe(
  query("users", {
    type: S.Array(UserSchema),
    // Resolver requires DatabaseService, but it's never executed
    resolve: () =>
      DatabaseService.pipe(
        Effect.flatMap((db) => db.getUsers())
      ),
  })
)

// buildSchema() is pure - no services needed
const schema = builder.buildSchema()

// Generate SDL without any layers
const sdl = generateSDL(schema)

This means you can:

• Generate SDL in CI without database connections
• Create schema introspection endpoints
• Build documentation from schema
• Validate schema changes in pull requests

CI/CD Integration

GitHub Actions Example

name: Schema Check
on: [push, pull_request]

jobs:
  schema:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      # Generate schema and check for uncommitted changes
      - run: npx @effect-gql/cli generate-schema ./src/schema.ts -o schema.graphql
      - run: git diff --exit-code schema.graphql

Pre-commit Hook

Add to your .husky/pre-commit:

#!/bin/sh
npx @effect-gql/cli generate-schema ./src/schema.ts -o schema.graphql
git add schema.graphql

Custom Script

Create a simple generation script:

scripts/generate-schema.ts

import { generateSDL } from "@effect-gql/cli"
import { builder } from "../src/schema"
import { writeFileSync } from "fs"

const sdl = generateSDL(builder.buildSchema())
writeFileSync("schema.graphql", sdl)
console.log("Generated schema.graphql")

Run with:

npx tsx scripts/generate-schema.ts

Next Steps

• CLI API Reference - Programmatic API for custom tooling