llms.txt
Compare with other sites' llms.txt files →---
title: Quickstart
---
> IMPORTANT: If you're using an agentic coding solution, you can provide [gluelang.dev/llms.txt](https://gluelang.dev/llms.txt) as a reference, which contains all of these docs in Markdown format.
> It will be able to figure out how to bootstrap Glue in your project.
# 1. Install Glue
```shell
# Homebrew
brew install guywaldman/tap/glue
# Linux/macOS
curl -fsSL https://github.com/guywaldman/glue/releases/latest/download/install.sh | bash
# Windows (PowerShell)
iwr -useb https://github.com/guywaldman/glue/releases/latest/download/install.ps1 | iex
```
# 2. Create a Glue file
Start by creating a Glue file that defines your data models and intefaces using the [Glue IDL](/docs/language-reference).
You can also generate code from a URL or from standard input (stdin).
Example:
```glue
// models.glue
/// Use triple slash for comments that should be included in generated code as docstrings
model Apartment {
/// The apartment number, e.g. "1A"
number: int
// Use double slash for internal comments and not included in generated code
residents: Person[]
}
model Person {
name: string
age: int
residence_end_date?: string // Optional fields are denoted with a `?`
is_employed: bool = false // Default values are supported
}
model Building {
name: string
apartments: Record<int, Apartment> // Complex types like maps, lists, etc. are supported
address: Address
// Nested models are supported
model Address {
street: string
city: string
country_code: string
zipcode: string
}
}
// Glue supports endpoints (like OpenAPI), which you can optionally define with sane defaults.
/// Get building information by the building ID
endpoint "GET /building/{building_id}" GetBuilding {
responses: {
200: Building
4XX: ApiError
5XX: ApiError
}
}
model ApiError {
code: Code
message: string
enum Code: "INVALID_REQUEST" | "NOT_FOUND" | "INTERNAL_ERROR"
}
```
Glue also support imports, so you can split your models into multiple files and import them:
```glue
import * from "models/person.glue"
import * as common from "models/common.glue" // Namespaced import
import { Address } from "models/building.glue" // Direct symbol import
```
# 3. Generate code
Pick a target (e.g., `typescript`, `python`, `rust`, `go`, `openapi`, `jsonschema`, `protobuf`) and generate code:
```shell
glue gen typescript -i models.glue -o ./generated
# If you wish to validate the Glue file without generating code, run:
glue check models.glue
```
# 4. Configure code generation (optional)
To support different use-cases, you can configure code generation with a `.gluerc` file. For example:
```yaml
# .gluerc.yaml
global:
output_base_dir: "./src/generated" # Base output directory for all generated code
config:
watermark: "none" # Don't generate a watermark
lint_suppressions: false # Don't generate lint suppression comments in generated code
gen:
- mode: typescript
files:
- "models/*.glue"
output: "{file_name}.ts" # Output path template (relative to output_base_dir)
config_overrides:
typescript:
zod: true # Emit Zod types for TypeScript generation
- mode: python
files:
- "schemas/*.glue"
output: "schemas/{file_name}.py"
config_overrides:
python:
data_model_library: "dataclasses" # Use Python dataclasses instead of the default Pydantic
```
# 5. Install VS Code extension (optional)
For a better development experience, install the [Glue VS Code extension](https://marketplace.visualstudio.com/items?itemName=guywaldman.glue) for syntax highlighting, error diagnostics, hover definitions, go-to definitions and more for Glue files (by default, those ending with `.glue`).
---
title: Overview
---
Glue is a language for modeling data structure and interfaces, with an ecosystem of tooling for code generation, IDE support, and more.
It is designed from the ground up to be simple, human-friendly, AI-friendly, and language-agnostic.
For the motivation behind Glue and the challenges it aims to solve, see [this blog post](https://guywaldman.com/posts/introducing-glue) by its creator.
If you're familiar with OpenAPI, Protobuf, Smithy or even Avro IDL, you can think of Glue as a batteries-included and minimalistic alternative to those, with a focus on ease of use and flexibility.
Glue's philosophy is:
1. **Easy for common users, extensible for power users**.
Glue wants you (or your LLM) to write as little code as possible. There should be sane defaults for everything.
1. **Generic with escape hatches**
Code generation is a never ending arms race against the complexity of target languages and frameworks. Glue should be as generic as possible, but provide escape hatches for advanced use cases.
1. **Just Work™**
Glue should be fast and reliable. It should "just work" for the vast majority of use cases, without needing to fight with it. In addition, Glue should provide helpful error messages when it doesn't work, and ideally even suggest fixes (inspired by Rust's compiler).
# Motivation
Glue empowers you to define your data models and interfaces in a single source of truth, and revolve your business logic around them.
It alleviates the need for multiple disparate tools for generating code (e.g., web servers/clients, OpenAPI specs, Protobuf schemas) in favor of a single unified toolchain.
The design goal for a single, simple, fast and reliable toolchain is inspired by projects such as [Rust's Cargo](https://doc.rust-lang.org/cargo/) and [uv](https://docs.astral.sh/uv/).
In fact, [**Glue's configuration is itself written in Glue**](https://github.com/guywaldman/glue/blob/main/glue/assets/config_schema.glue) and is used to generate **Rust code** which defines the models (with serialization/deserialization) as well as a **JSON schema**!
# Quickstart
Refer to the [Quickstart](/docs/quickstart) page for a quick introduction to using Glue, or if you're using an agentic coding solution, provide [gluelang.dev/llms.txt](https://gluelang.dev/llms.txt) as a reference, which contains all of these docs in Markdown format.
# The Glue toolchain
## Glue IDL
An Interface Definition Language (IDL) for modeling data models and API endpoints in a way that aims to be as simple and generic as possible, while providing adequate "escape hatches" for advanced use cases. For more information, see the [Language Reference](/docs/04-language-reference) page.
An example Glue model definition:
```glue
model User {
name: string
age: int
email?: string
active: bool = true
}
```
## Glue CLI & code generation
A command-line interface (CLI) tool for working with Glue files, generating code, and more. For more information, see the [CLI Reference](/docs/cli-reference) page.
Example usage:
```shell
glue check user.glue # Lint and validate a Glue file
glue gen typescript -i user.glue -o ./generated # Generate TypeScript code from a Glue file
```
### Installation
Glue supports multiple platforms (Linux, macOS, Windows) and multiple architectures (x86, ARM).
To install:
```shell
# Homebrew
brew install guywaldman/tap/glue
# Linux/macOS
curl -fsSL https://github.com/guywaldman/glue/releases/latest/download/install.sh | bash
# Windows (PowerShell)
iwr -useb https://github.com/guywaldman/glue/releases/latest/download/install.ps1 | iex
```
## IDE support
Glue has a [VS Code extension](https://marketplace.visualstudio.com/items?itemName=guywaldman.glue) that provides syntax highlighting, error diagnostics, hover definitions, go-to definitions and more for Glue files (by default, those ending with `.glue`).
### Usage
Glue has a command-line interface (CLI) tool that you can install and use to work with Glue files, generate code, and more.
Below is a simple Glue model definition for a `User` type, with some fields.
```glue
model User {
name: string
age: int
email?: string
active: bool = true
}
```
Then use the CLI to validate and generate code:
```shell
glue check user.glue
glue gen typescript -i user.glue -o ./generated
```
Glue currently supports generation for `typescript`, `python`, `rust`, `go`, `protobuf`, `openapi`, and `jsonschema`.
---
title: CLI reference
---
# Available commands
```shell
$ glue --help
Usage: glue <COMMAND>
Commands:
check Checks for validity of a Glue file
gen Generates code from a Glue file
ast Emits Glue IR as JSON
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
```
# Code generation
Glue generates code from Glue files using the `gen` command. The generated code can be used for:
1. Serialization/deserialization
1. Data schemas (e.g. JSON Schema, Protobuf messages)
1. Generating OpenAPI spec from which you can generate API clients or server stubs
Glue currently supports these languages and formats for code generation (click for more details):
1. [OpenAPI](./codegen-openapi)
1. [JSON Schema](./codegen-jsonschema)
1. [TypeScript](./codegen-typescript) (including Zod types)
1. [Python](./codegen-python) (including support for `pydantic`, `dataclasses`, `attrs`, and `msgspec`)
1. [Rust](./codegen-rust)
1. [Go](./codegen-go)
1. [Protobuf](./codegen-protobuf)
To generate code from a Glue file:
```shell
# Generate code from a Glue file
glue gen <language> api.glue -o ./generated
# ...or from a URL:
glue gen python https://raw.githubusercontent.com/guywaldman/glue/refs/heads/main/examples/basic.glue -o ./models.py
# ...or from stdin:
cat api.glue | glue gen <language> -o ./generated
# ...or into stdout:
glue gen <language> -i api.glue > ./generated
```
# Configuration
If you have a `.gluerc` YAML file (or `.gluerc.yaml`, `.gluerc.yml`, `.gluerc.json`) at the same directory level, Glue will automatically use it for configuration. You can also specify a config file with `--config path/to/config`.
You can also override specific config options inline with `--set key=value` (e.g. `--set watermark=none` to disable the watermark in generated code).
```shell
# Use `.gluerc` in the current directory if it exists
glue gen
# ...or specify a config file explicitly
glue gen --config path/to/.gluerc.yaml
# ...or override specific config options inline:
glue gen go https://raw.githubusercontent.com/guywaldman/glue/refs/heads/main/examples/basic.glue --set "watermark=none"
```
For configurations, see [Configuration](/docs/configuration).
# Static validation
Glue files can be statically validated with the `check` command:
```shell
glue check api.glue
glue check --config path/to/.gluerc.yaml api.glue
```
## Imports
Glue resolves imports recursively for both `check` and `gen`.
- Local file inputs resolve imports relative to the importing file.
- URL inputs resolve imports relative to the base URL.
- Import cycles are handled safely (already-visited sources are skipped).
- Imports must be declared at the top of the file (before `const`, `type`, `model`, `endpoint`, and `enum` declarations).
# Advanced usage
## Inspect Glue IR
Glue can emit the intermediate representation (IR) it uses for code generation, which can be useful for debugging and understanding how Glue processes your files:
```shell
glue ast https://raw.githubusercontent.com/guywaldman/glue/refs/heads/main/examples/basic.glue
```
---
title: Quickstart
---
Create a Glue file, validate it, and generate code in a few commands.
## 1) Create a model
Create a file named `person.glue`:
```glue
model Person {
name: string
age: int
address: Address
model Address {
street: string
city: string
country_code: string
zipcode: string
}
}
```
## 2) Validate it
```shell
glue check person.glue
```
If the model is valid, the command exits successfully without errors.
## 3) Generate code
Generate TypeScript code into `./generated`:
```shell
glue gen typescript -i person.glue -o ./generated
```
You can replace `typescript` with any supported target:
- `python`
- `rust`
- `go`
- `protobuf`
- `openapi`
- `jsonschema`
## 4) Use project configuration (optional)
If your project has a `.gluerc` (or `.gluerc.yml`, `.gluerc.yaml`, `.gluerc.json`), run:
```shell
glue gen --config path/to/.gluerc
```
See the [Configuration](./03-configuration) page for full details.
---
title: Configuration
---
Use a `.gluerc` file to set defaults and per-target overrides for code generation.
## Supported config files
Glue auto-detects these files next to your input file:
- `.gluerc` (YAML)
- `.gluerc.yaml`
- `.gluerc.yml`
- `.gluerc.json`
If no config file is found, Glue uses built-in defaults.
To use a specific config file:
```shell
glue gen --config path/to/.gluerc ...
```
## How the config is structured
- `global`: defaults applied to every generation entry.
- `gen`: a list of per-input rules (`mode`, `files`) with optional output and overrides. `files` can be a single glob string or a list of glob strings.
## JSON schema
Glue ships a JSON schema for config files at [`glue/assets/config_schema.json`](https://github.com/guywaldman/glue/blob/main/glue/assets/config_schema.json). Use it with VS Code's YAML support to get autocomplete and validation in `.gluerc.yaml` files.
## Example
```yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/guywaldman/glue/main/glue/assets/config_schema.json
global:
output_base_dir: ./generated
diagnostics:
suppress_warnings:
- constant_case
config:
lint_suppressions: true
preserve_generated_identifiers: false
watermark: short
typescript:
zod: false
python:
data_model_library: pydantic
base_model: pydantic.BaseModel
rust:
include_yaml: true
serde_struct_derives: true
extra_derives:
structs: ["PartialEq", "Eq", "Hash"]
enums: ["Ord", "PartialOrd"]
unions: ["PartialEq"]
type_aliases: ["Ord", "PartialOrd"]
go:
package_name: glue
protobuf:
package_name: glue
gen:
- mode: typescript
files: "**/*.glue"
output: "src/types/{file_name}.ts"
config_overrides:
typescript:
zod: true
- mode: python
files:
- "schemas/api/*.glue"
- "schemas/shared/*.glue"
output: "src/generated/{file_name}.py"
config_overrides:
python:
data_model_library: dataclasses
lint_suppressions: false
- mode: protobuf
files: "models/*.glue"
output: "proto/{file_name}.proto"
config_overrides:
protobuf:
package_name: myapp.v1
```
## Notes
- Run `glue gen` to use an auto-discovered config file, or `glue gen --config path/to/.gluerc.yaml` to use one explicitly.
- `output` supports `{file_name}` and `{file_ext}` placeholders.
- `watermark` supports `full`, `short`, or `none`.
- `global.diagnostics.suppress_warnings` suppresses source diagnostics for both `glue check` and `glue gen`. Currently supported warning codes: `constant_case`.
- `preserve_generated_identifiers` keeps user-provided identifiers exactly as written, such as model names and fields. Glue may still normalize identifiers it synthesizes from values, such as enum variant constants.
- `python.data_model_library` supports `pydantic`, `dataclasses`, `attrs`, or `msgspec`.
- `rust.serde_struct_derives` controls serde derives and serde attributes on generated Rust structs, enums, union enums, and type alias newtypes.
- `rust.extra_derives` appends additional Rust derive paths by generated shape: `structs`, `enums`, `unions`, or `type_aliases`.
---
title: Language reference
---
> NOTE: This page explains the Glue syntax in pseudo EBNF form. It is not a formal specification, but rather a reference guide to the language features and syntax, so that it's easier to grok.
> If you are interested in the exact grammar, Glue uses [pest](https://pest.rs/) and you can check out the Pest file in the Glue codebase.
The Glue IDL is designed to be simple and intuitive, with a syntax that is easy to read and write. Below is a reference of the language features and syntax.
# Primitive types
Glue supports the following primitive types:
- `string`
- `int`
- `uint`
- `i8`, `i16`, `i32`, `i64`
- `u8`, `u16`, `u32`, `u64`
- `float`
- `any`
- `bool`
# Compound types
- `model` (a structured type with named fields)
- `enum` (enumeration of string values)
- `type` alias declarations (e.g., `type UserID = string`)
- `const` declarations (e.g., `const MAX_PAGE_SIZE: int = 100`)
- `T[]` (an array/list of type `T`)
- `(T, U)` (a fixed-length tuple)
- `Record<T, U>` (a map/dictionary type with keys of type `T` and values of type `U`)
- `A | B` (a union type)
- `endpoint` (an API endpoint definition with method, path, parameters, and responses)
- `service` (a Protobuf service definition with RPC methods)
# Block member separators
Model, anonymous model, endpoint, service, and RPC blocks accept either whitespace/newlines or commas between members.
Commas are useful for compact one-line shapes:
```glue
model User { id: string, email?: string, profile: { name: string, age?: u8 } }
endpoint "GET /users/{id}" GetUser { responses: { 200: User, 4XX: ApiError } }
```
# Type aliases
Glue supports type aliases, which let you define reusable names for existing types.
```glue
type UserId = string
type UserIds = UserId[]
model User {
id: UserId
related: UserIds
}
```
Notes:
- Aliases declared inside a model are scoped to that model.
- Alias targets can be any valid type expression.
# Constants
Glue supports top-level and model-scoped constants for reusable literal values.
```glue
const MAX_PAGE_SIZE = 100
const DEFAULT_LIMIT = MAX_PAGE_SIZE * 2
const USER_ALIAS = "user_" + "id"
const _RETRY_MS = (100 + 50) * 2
// Optional explicit annotation
const FEATURE_ENABLED: bool = true
model FieldNames {
const SUFFIX = "_id"
const USER_ID_ALIAS = "user" + SUFFIX
const _INTERNAL_ALIAS = "internal_id"
}
model Tags {
const USER_ID = 1
}
model User {
@field(alias=FieldNames.USER_ID_ALIAS, proto_tag=Tags.USER_ID)
user_id: int
}
```
Notes:
- Constant types are inferred from folded values. Optional annotations can be integer primitives, `string`, or `bool`.
- Int expressions support `+`, `*`, parentheses, and references to int constants.
- String expressions support `+`, parentheses, and references to string constants.
- Bool expressions support literals and references only.
- Constants can be referenced before they are declared. Cycles are rejected.
- Constants declared inside a model are scoped to that model. Public model constants can be referenced as `Model.CONSTANT`; nested model constants can be referenced as `Outer.Inner.CONSTANT`.
- Names should use `CONSTANT_CASE`. A leading `_` marks a constant as private in generated language targets. Private model constants cannot be referenced from outside their owning model as `Model._CONSTANT`.
- Constants can be used in field defaults and decorator arguments, including `@field(alias=...)` and `@field(proto_tag=...)`.
- TypeScript, Python, Rust, and Go emit standalone constants. Model-scoped constants are emitted with model-path prefixes. OpenAPI, JSON Schema, and Protobuf only consume folded constant values.
# Models
**Models** are the foundation of Glue data models.
They are defined using the `model` keyword, followed by the model name and a block of fields.
```glue
/// Optional public documentation
model <model_name> {
<field_name>[?]: <field_type> [= <default_value>]
...
}
```
For example:
```glue
/// A user of the system
model User {
name: string
age?: int // Optional fields are denoted with a `?`
active: bool = true // Default values are supported
contact: ContactInfo
// Models can be nested
model ContactInfo {
email: string
phone?: string
}
}
```
Fields can also use anonymous structs for one-off inline shapes:
```glue
model User {
profile: {
bio: string
age?: int
}
}
```
## Mo