CLI API Reference

The @effect-gql/cli package exports functions for programmatic use in custom scripts and tooling.

For installation and command-line usage, see the CLI Guide.

Functions

generateSDL

Generate SDL from a GraphQL schema.

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

const sdl = generateSDL(schema)

// With options
const sortedSdl = generateSDL(schema, { sort: true })

Parameters

Parameter	Type	Description
schema	GraphQLSchema	The GraphQL schema
options.sort	boolean	Sort types alphabetically (default: true)

Returns

string - The SDL representation of the schema.

---

generateSDLFromModule

Load a schema from a module and generate SDL.

import { generateSDLFromModule } from "@effect-gql/cli"
import { Effect } from "effect"

const sdl = await Effect.runPromise(
  generateSDLFromModule("./src/schema.ts")
)

// With options
const sdl = await Effect.runPromise(
  generateSDLFromModule("./src/schema.ts", { sort: false })
)

Parameters

Parameter	Type	Description
modulePath	string	Path to the module (relative to cwd)
options.sort	boolean	Sort types alphabetically (default: true)

Returns

Effect.Effect<string, Error> - Effect that produces SDL or fails with an error.

---

loadSchema

Load a GraphQL schema from a module path.

import { loadSchema } from "@effect-gql/cli"
import { Effect } from "effect"

const schema = await Effect.runPromise(
  loadSchema("./src/schema.ts")
)

Parameters

Parameter	Type	Description
modulePath	string	Path to the module (relative to cwd)

Returns

Effect.Effect<GraphQLSchema, Error> - Effect that produces the loaded schema or fails with an error.

---

scaffold

Programmatically scaffold a new Effect GraphQL project.

import { scaffold } from "@effect-gql/cli"
import { Effect, Option } from "effect"

await Effect.runPromise(
  scaffold({
    name: "my-api",
    serverType: "node",
    directory: Option.none(),
    monorepo: Option.none(),
    skipInstall: false,
    packageManager: Option.none(),
  })
)

Parameters

The scaffold function takes a CreateOptions object:

Parameter	Type	Description
name	string	Package/project name
serverType	ServerType	"node", "bun", "express", or "web"
directory	Option<string>	Target directory (default: ./<name>)
monorepo	Option<boolean>	Create as workspace package (auto-detected if None)
skipInstall	boolean	Skip dependency installation
packageManager	Option<PackageManager>	"npm", "pnpm", "yarn", or "bun" (auto-detected if None)

Returns

Effect.Effect<void, Error> - Effect that creates the project or fails with an error.

Example: Custom Scaffolding Script

import { scaffold, SERVER_TYPES } from "@effect-gql/cli"
import { Effect, Option, Console } from "effect"

const createProject = (name: string, serverType: string) =>
  Effect.gen(function* () {
    yield* Console.log(`Creating ${name} with ${serverType}...`)

    yield* scaffold({
      name,
      serverType: serverType as "node" | "bun" | "express" | "web",
      directory: Option.some(`./projects/${name}`),
      monorepo: Option.some(false),
      skipInstall: true,
      packageManager: Option.some("pnpm"),
    })

    yield* Console.log("Done!")
  })

Effect.runPromise(createProject("my-api", "node"))

---

Types

ServerType

type ServerType = "node" | "bun" | "express" | "web"

PackageManager

type PackageManager = "npm" | "pnpm" | "yarn" | "bun"

CreateOptions

interface CreateOptions {
  readonly name: string
  readonly serverType: ServerType
  readonly directory: Option.Option<string>
  readonly monorepo: Option.Option<boolean>
  readonly skipInstall: boolean
  readonly packageManager: Option.Option<PackageManager>
}

---

Constants

SERVER_TYPES

Array of all valid server types.

import { SERVER_TYPES, isValidServerType } from "@effect-gql/cli"

SERVER_TYPES // ["node", "bun", "express", "web"]

isValidServerType("node") // true
isValidServerType("invalid") // false

---

Module Resolution

The module should export one of:

• builder - A GraphQLSchemaBuilder instance (calls buildSchema() automatically)
• schema - A GraphQLSchema instance
• default - Either of the above as the default export

// Any of these work:
export const builder = GraphQLSchemaBuilder.empty.pipe(...)
export const schema = builder.buildSchema()
export default builder

Usage Examples

Custom Build 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")

Schema Validation

import { loadSchema } from "@effect-gql/cli"
import { Effect } from "effect"
import { validateSchema } from "graphql"

const program = Effect.gen(function* () {
  const schema = yield* loadSchema("./src/schema.ts")
  const errors = validateSchema(schema)

  if (errors.length > 0) {
    console.error("Schema validation errors:", errors)
    process.exit(1)
  }

  console.log("Schema is valid!")
})

Effect.runPromise(program)

Comparing Schemas

import { generateSDLFromModule } from "@effect-gql/cli"
import { Effect } from "effect"
import { readFileSync } from "fs"

const program = Effect.gen(function* () {
  const currentSDL = yield* generateSDLFromModule("./src/schema.ts")
  const committedSDL = readFileSync("schema.graphql", "utf-8")

  if (currentSDL !== committedSDL) {
    console.error("Schema has changed! Run 'effect-gql generate-schema' to update.")
    process.exit(1)
  }

  console.log("Schema is up to date.")
})

Effect.runPromise(program)