GQLSchemaGen CLI Reference

The GQLSchemaGen CLI lets you generate GraphQL schemas directly from your Go structs. This page covers all commands, flags, and options to help you get the most out of the tool.

Quick Start

Initialize Configuration

Create a default configuration file:

$ gqlschemagen init

Options:

gqlschemagen init --output custom-config.yml gqlschemagen init -o custom-config.yml gqlschemagen init --force # Overwrite existing file gqlschemagen init -f

Generate Schema

Basic usage (requires --pkg flag):

gqlschemagen generate -p ./internal/domain

With output directory:

gqlschemagen generate -p ./internal/domain -o ./graph/schema

Using a configuration file:

$ Create config first

gqlschemagen init

$ Then generate (uses gqlschemagen.yml by default)

gqlschemagen generate

$ Or specify a custom config

gqlschemagen generate -c custom-config.yml

Watch mode (auto-regenerate on changes):

gqlschemagen generate -p ./internal/domain --watch gqlschemagen generate -w

Get Help

View available commands and usage:

gqlschemagen --help gqlschemagen help

$ Show help for a specific command

gqlschemagen generate --help gqlschemagen init --help

Commands

`gqlschemagen init`

Create a default configuration file.

Usage:

Options:

Flag	Short	Description	Default
`--output`	`-o`	Output file path	`gqlschemagen.yml`
`--force`	`-f`	Overwrite existing file	`false`

Examples:

`gqlschemagen generate`

Generate GraphQL schema from Go structs.

Usage:

Required Flags:

Flag	Short	Description
`--pkg`	`-p`	Root package directory to scan

Optional Flags:

Flag	Short	Type	Description	Default
`--config`	`-c`	string	Path to config file	`gqlschemagen.yml`
`--watch`	`-w`	bool	Watch for changes and regenerate	`false`
`--out`	`-o`	string	Output directory or file path	`graph/schema`
`--output-file-name`	`--ofn`	string	Output file name for single strategy	`gqlschemagen.graphqls`
`--output-file-extension`		string	File extension for multiple/package strategies	`.graphqls`
`--strategy`	`-s`	string	Generation strategy: `single`, `multiple`, or `package`	`single`
`--skip-existing`		bool	Skip generating files that already exist	`false`
`--field-case`	`--case`	string	Field name case: `camel`, `snake`, `pascal`, `original`, `none`	`camel`
`--use-json-tag`		bool	Use json tag for field names	`true`
`--use-gqlgen-directives`	`--gqlgen`	bool	Generate @goModel and @goField directives	`false`
`--model-path`	`-m`	string	Base path for @goModel directive	``
`--strip-prefix`		string	Comma-separated prefixes to strip from type names	``
`--strip-suffix`		string	Comma-separated suffixes to strip from type names	``
`--add-type-prefix`		string	Prefix to add to GraphQL type names	``
`--add-type-suffix`		string	Suffix to add to GraphQL type names	``
`--add-input-prefix`		string	Prefix to add to GraphQL input names	``
`--add-input-suffix`		string	Suffix to add to GraphQL input names	``
`--schema-file-name`		string	Schema file name pattern for multiple mode	`{model_name}.graphqls`
`--include-empty-types`		bool	Include types with no fields	`false`

Using Command Line Flags

All flags support long (--flag) and short (-f) formats where available.

Usage Examples

Single File Strategy

Generate all types in one schema file:

gqlschemagen generate -p ./internal/models -o ./graph/schema/schema.graphqls -s single

Multiple Files Strategy

Generate one file per type:

gqlschemagen generate -p ./internal/models -o ./graph/schema -s multiple --schema-file-name "{model_name}.graphqls"

Result:

Package Strategy

Generate one file per Go package:

gqlschemagen generate -p ./internal -o ./graph/schema -s package

Result:

With gqlgen Directives

Generate schema with gqlgen integration:

gqlschemagen generate -p ./internal/models -o ./graph/schema --gqlgen -m github.com/myapp/models

Generated:

Type Name Manipulation

Strip prefixes and add suffixes:

gqlschemagen generate -p ./internal/models --strip-prefix DB,Api --strip-suffix DTO,Entity --add-input-suffix Input

Example:

DBUser → User
ApiProduct → Product
OrderDTO → Order
CreateUserDTO input → CreateUserInput

Field Case Transformation

Use snake_case for GraphQL fields:

gqlschemagen generate -p ./internal/models --case snake

Go struct:

Generated GraphQL:

Watch Mode

Auto-regenerate on file changes:

gqlschemagen generate -p ./internal/models -o ./graph/schema --watch

Configuration File vs CLI Flags

You can use either a YAML configuration file or CLI flags. CLI flags always override config file values.

Using Configuration File

$ Create config

gqlschemagen init

$ Generate using config

gqlschemagen generate

Mixing Config and Flags

$ Use config but override output path

gqlschemagen generate -o ./custom/output

$ Use custom config file

gqlschemagen generate -c my-config.yml

$ Override multiple settings

gqlschemagen generate -c my-config.yml -s multiple --gqlgen

Common Workflows

Development Setup

CI/CD Integration

Go Generate Integration

Add to your Go file:

Then run: