Getting Started

GQLSchemaGen makes it easy to generate a GraphQL schema from your Go models. This guide walks you through installation, setup, and your first generated type.

Installation

You can install GQLSchemaGen globally or pin it directly to your project using Go’s toolchain-aware installation. The latter is preferable when you want fully reproducible builds.

Option 1: Global installation with go install

$ 
go install github.com/pablor21/gqlschemagen@latest

This installs a global gqlschemagen binary into $GOBIN (or $GOPATH/bin).

Option 2: Install as a versioned tool (recommended)

Go supports installing CLI tools inside your module using the -tool flag. This keeps the tool versioned and isolated, without polluting global binaries.

Install it:

$ 
go get -tool github.com/pablor21/gqlschemagen

Use it:

$ go tool gqlschemagen generate

This ensures you always run the module-pinned version of GQLSchemaGen—ideal for teams and CI environments.

Tip: Combine this with //go:generate to guarantee consistent schema generation across machines.

Option 3: Install as a library (for building a custom wrapper)

If you prefer full control over the generation workflow, you can install GQLSchemaGen purely as a library:

$ go get github.com/pablor21/gqlschemagen

This allows you to build your own wrapper command or orchestrate multiple tools together. It’s useful when you want:

• custom logging or output formatting
• additional pre- or post-processing steps
• a single unified codegen entrypoint for your project

Here is an example of a custom go:generate script that chains GQLSchemaGen and GQLGen together. Save this file as generate.go (or any name you want):

Run it with:

$ go generate ./...

This pattern keeps your project self-contained, version-controlled, and flexible. It also avoids depending on globally installed binaries, since your wrapper decides how and where to execute each tool.

Initialize your project

We recommend starting by running:

$ gqlschemagen init

This will create a gqlschemagen.yml configuration file in your project root. This file is where you can specify which packages to scan, output paths, naming conventions, and other options. See Configuration for full details.

Annotate your first type

Add GraphQL annotations to your Go structs using comments above your type:

These annotations tell GQLSchemaGen how to map Go types to GraphQL object types.

Generate your schema

Once your structs are annotated, generate the GraphQL schema:

$ gqlschemagen generate

This will produce a schema.graphql file with your types. For example, the User struct above generates:

Do you use gqlgen? We got you covered! just run:

$ gqlschemagen generate --gqlgen

Tip: Use gqlschemagen generate --watch during development to automatically regenerate the schema whenever you change your types.

Next Steps

Now that you have your first type generated, you can explore the gqlschemagen.yml configuration to customize package scanning, naming conventions, directives, and more. Check out Configuration for full details.