CLI reference

Installation

Use Go’s tool directive to pin the generator version in go.mod:

go get -tool github.com/tylergannon/polytype/polytype@latest

Invoke the pinned CLI as go tool polytype.

The CLI generates JSON Schema, validation, Go JSON codecs, and TypeScript. Generators can select the same projections through the codegen package. The devalue transport and type-grammar packages also support lower-level use; see devalue transport and custom backends.

Generate

go tool polytype
go tool polytype gen [flags]
  -pretty            indent schema JSON
  -target DIR        package to process (default: current directory)
  -no-changes        fail without writing when schemas or requested TypeScript output would change
  -force             rewrite unchanged output and allow removal of generated validation; incompatible with -no-changes
  --validate         generate JSON validation methods
  --typescript DIR   generate structural TypeScript declarations in DIR
  --typescript-barrel
                     also generate index.ts type-only exports; requires --typescript

The command without a subcommand is equivalent to gen.

Environment

Any non-empty JSONSCHEMA_NO_CHANGES value is equivalent to -no-changes and applies through existing go generate directives. It guards schema JSON and every requested TypeScript artifact without writing those destinations, but generation can still update jsonschema_gen.go when they are unchanged. In CI, follow generation with test -z "$(git status --porcelain)" to verify tracked and untracked generated files.

A normal generation run removes an obsolete schema and checksum when their checksum still matches. -no-changes reports those pending removals without deleting them. If an orphaned schema was edited after generation, polytype preserves it and returns an error instead of deleting it.

Go codecs and TypeScript declarations

One directive can generate validation, Go owner codecs selected by field registrations, and TypeScript declarations:

//go:generate go tool polytype --validate --typescript web/src/generated --typescript-barrel

Sealed-interface union fields and .StringerEnum registrations cause the containing Go struct’s JSON methods to be generated automatically; there is no codec flag. The TypeScript output provides static declarations only, with no runtime decoder or validator. Validate untrusted values in the TypeScript application, and call the generated Go ValidateJSON method before json.Unmarshal.

One CLI run owns one TypeScript output directory. Use separate directories for different target Go packages; otherwise the later run replaces the earlier generated types.ts. Use the grammar and typescript packages when one declaration graph must span several packages.