CLI Reference

The GraphQL Code Generator provides both a command-line interface and a fluent Builder API for programmatic use.

Command-Line Interface

Required Arguments

Argument	Description
--sdl or --sdl-file	Path to the GraphQL SDL (Schema Definition Language) file
--generated-sources-package or --package	Java package name for generated source files (e.g., com.example.generated.graphql)

Optional Arguments

Argument	Default	Description
--generated-sources-dir	stdout	Directory where generated sources will be written (excluding package path)
--delete-existing-generated-sources	false	Delete all *.java files in generated sources directory before generating. Warning: Only use if directory contains ONLY generated sources
--class-name-prefix	""	Prefix for generated class names (e.g., "API" generates APISchemaContext, APIQuery, etc.)
--templated-sources-dir	none	Directory where templated sources will be written. Enables generation of endpoint and optional custom settings
--overwrite-templated-sources	false	Overwrite existing templated sources. Warning: This will overwrite manual edits
--templated-sources-package	Same as --generated-sources-package	Java package name for templated sources
--api-endpoint-display-name	none	Adds @DisplayName annotation to generated endpoint class (requires --templated-sources-dir)
--api-endpoint-path	Normalized --class-name-prefix	Permalink path for the API endpoint (requires --templated-sources-dir)
--generate-custom-settings	false	Generate a custom GraphQLSchemaSettings class as a templated source
--not-null-annotation-class	none	Fully qualified class name of annotation to apply to non-null fields/arguments (e.g., org.jetbrains.annotations.NotNull)
--custom-scalar	none	Map a custom scalar to a ScalarTypeGenerator. Can be specified multiple times. Format: name=<ScalarName>|typeGeneratorClass=<ClassName>[|schemaContextClass=<ClassName>|valueTypeClass=<ClassName>]
--type-mapping	none	Map a GraphQL type to an existing Java class. Can be specified multiple times. Format: <GraphQLTypeName>=<fully.qualified.JavaClass>

Example: Full CLI Invocation

1
java -cp "lib/*" com.psddev.graphql.schema.codegen.GraphQLCodeGenerator \
2
  --sdl src/main/resources/schema.graphql \
3
  --generated-sources-package com.example.generated.api \
4
  --generated-sources-dir build/generated/graphql \
5
  --delete-existing-generated-sources \
6
  --templated-sources-package com.example.api \
7
  --templated-sources-dir src/main/java \
8
  --class-name-prefix "API" \
9
  --api-endpoint-display-name "Example API" \
10
  --api-endpoint-path "/graphql/api" \
11
  --not-null-annotation-class "org.jetbrains.annotations.NotNull" \
12
  --custom-scalar "name=Long|typeGeneratorClass=com.psddev.graphql.schema.types.number.LongScalar" \
13
  --type-mapping "User=com.example.domain.User"

Builder API

For programmatic use, instantiate the public nested Builder class directly—new GraphQLCodeGenerator.Builder(). Every CLI flag has a corresponding builder method.

Required Methods

1
Builder sdl(TypeDefinitionRegistry sdl)
2
Builder sdlPath(String path)
3
Builder sdlPath(Path path)
4
Builder sdlContents(String contents)
5
Builder sdlContents(InputStream contents)

Set the GraphQL schema. Use exactly one of these methods to provide the SDL.

1
Builder generatedSourcesPackageName(String packageName)

Set the Java package name for generated sources (e.g., "com.example.generated.graphql").

Generated Sources

1
Builder generatedSourcesOutputDir(Path dir)
2
Builder generatedSourcesOutputDir(String dir)

Set where generated sources are written (excluding the package path). If not set, outputs to stdout.

1
Builder deleteExistingGeneratedSources(boolean delete)

Delete all *.java files in the generated sources directory before generating. Only use when the directory contains exclusively generated sources.

1
Builder classNamePrefix(String prefix)

Set a prefix for all generated class names (e.g., "API" creates APISchemaContext, APIQuery, and so on for every model and generator class).

Templated Sources

1
Builder templatedSourcesOutputDir(Path dir)
2
Builder templatedSourcesOutputDir(String dir)
3
Builder templatedSourcesPackageName(String packageName)
4
Builder overwriteTemplatedSources(boolean overwrite)

Enable and control the one-time scaffolding (endpoint and optional settings classes). The package defaults to the generated sources package. Templated sources are never overwritten unless you ask—save your edits before enabling overwriteTemplatedSources.

1
Builder apiEndpointDisplayName(String displayName)
2
Builder apiEndpointPath(String path)
3
Builder generateCustomSettings(boolean generate)

Customize the scaffolded endpoint: its @DisplayName, its permalink (defaults to the normalized class name prefix), and whether to also scaffold an editable GraphQLSchemaSettings class. These only apply when a templated sources directory is configured.

Type Customization

1
Builder addCustomScalar(String name, Class<?> typeGeneratorClass)
2
Builder addCustomScalar(String name, String typeGeneratorClassName,
3
        String schemaContextClassName, String valueTypeClassName)

Map a scalar declared in the SDL to an existing ScalarTypeGenerator implementation for stricter type handling. The plugin ships generators for all built-in types (e.g. LongScalar, UuidScalar, InstantScalar). Use the String-based overload when the generator class isn't on the codegen classpath. Can be called multiple times.

1
Builder addTypeMapping(String graphqlTypeName, String javaClassName)
2
Builder addTypeMapping(String graphqlTypeName, Class<?> javaClass)

Map a GraphQL type to a pre-existing Java class: generated method signatures reference your class directly, and the schema context declares a to<Type> conversion method. Equivalent to the @javaType(class: "...") schema directive. Can be called multiple times.

1
Builder notNullAnnotationClass(String annotationClassName)

Apply the given annotation (e.g. org.jetbrains.annotations.NotNull) to generated methods and parameters that are non-null per the schema.

Example: Builder API Usage

1
package com.example.codegen;
2

3
import com.psddev.graphql.schema.codegen.GraphQLCodeGenerator;
4
import com.psddev.graphql.schema.types.number.LongScalar;
5
import com.psddev.graphql.schema.types.time.InstantScalar;
6
import com.psddev.graphql.schema.types.uuid.UuidScalar;
7

8
public class BuilderAPIExample {
9
    public static void main(String[] args) {
10
        new GraphQLCodeGenerator.Builder()
11
            // Required: the SDL and the package for generated sources
12
            .sdlPath("src/main/resources/schema.graphql")
13
            .generatedSourcesPackageName("com.example.generated.api")
14
            // Generated sources: regenerated (and optionally cleaned) on every run
15
            .generatedSourcesOutputDir("build/generated/graphql")
16
            .deleteExistingGeneratedSources(true)
17
            .classNamePrefix("API")
18
            // Templated sources: scaffolded once into your real source tree
19
            .templatedSourcesOutputDir("src/main/java")
20
            .templatedSourcesPackageName("com.example.api")
21
            .apiEndpointDisplayName("Example API")
22
            .apiEndpointPath("/graphql/api")
23
            .generateCustomSettings(true)
24
            // Map SDL scalars to existing ScalarTypeGenerator implementations
25
            .addCustomScalar("Long", LongScalar.class)
26
            .addCustomScalar("UUID", UuidScalar.class)
27
            .addCustomScalar("Instant", InstantScalar.class)
28
            // Map GraphQL types to pre-existing Java classes
29
            .addTypeMapping("User", "com.example.domain.User")
30
            // Optional null-safety annotations on generated methods
31
            .notNullAnnotationClass("org.jetbrains.annotations.NotNull")
32
            .build()
33
            .generate();
34
    }
35
}

Common Patterns

Generating from Multiple Schemas

You can create separate generator classes for different schemas:

1
public class UserAPICodeGenerator {
2
    public static void main(String[] args) {
3
        new GraphQLCodeGenerator.Builder()
4
            .sdlPath("schemas/user-api.graphql")
5
            .generatedSourcesPackageName("com.example.generated.userapi")
6
            .generatedSourcesOutputDir("build/generated/graphql")
7
            .classNamePrefix("UserAPI")
8
            .build()
9
            .generate();
10
    }
11
}

Custom Scalar Mapping

1
new GraphQLCodeGenerator.Builder()
2
    .sdlPath("src/main/resources/schema.graphql")
3
    .generatedSourcesPackageName("com.example.generated")
4
    .addCustomScalar("Instant", InstantScalar.class)
5
    .addCustomScalar("UUID", UuidScalar.class)
6
    .addCustomScalar("Long", LongScalar.class)
7
    .build()
8
    .generate();

Type Mapping to Domain Models

1
new GraphQLCodeGenerator.Builder()
2
    .sdlPath("src/main/resources/schema.graphql")
3
    .generatedSourcesPackageName("com.example.generated")
4
    .addTypeMapping("User", com.example.domain.User.class)
5
    .addTypeMapping("Post", com.example.domain.Post.class)
6
    .build()
7
    .generate();

Tips

• The classNamePrefix keeps multiple GraphQL APIs in the same project unambiguous—every generated class carries it
• Custom scalars map to ScalarTypeGenerator implementations, not raw Java types; reuse the built-in generators where possible
• Type mappings work best when your domain models closely match your GraphQL schema
• Run with deleteExistingGeneratedSources(true) once your generated directory is dedicated, so removed schema types don't leave stale classes behind

Next Steps

• Gradle Integration - Automate code generation in your build
• Implementation Patterns - Learn best practices for implementing generated code