gdDocumentation0.8.0

gd Manual

English | 日本語

What gd is for

gd is a single command for writing command-line tools, websites, Web APIs, scheduled jobs, and data processing in GDScript. It is Godot built small without a display, and it runs a single .gd file without a project.godot.

You start the way you would with a Python or Node.js script. When you need them, type checking, tests, packages, databases, a Web server, and a standalone executable are available in the same GDScript. For game screens and rendering, use upstream Godot.

Together with Godot itself, apps, frontends, servers, and CLI tools can all be written in one language, GDScript. The same script runs on macOS, Linux, and Windows, and waits on networking and databases do not stop other work. It links directly with C++ through GDExtension.

Speed matters too. gd supports HTTP/2, other work proceeds while a connection waits, and text and JSON processing is fast.

Install

Prebuilt downloads are available for macOS arm64/x86_64, Linux x86_64, and Windows x86_64. Linux arm64 can be built from source. You can also download an archive from Releases and put gd on your PATH.

macOS / Linux

curl -fsSL https://gd.progsha.com/install.sh | sh

Installs to ~/.local/bin. If the directory is missing from PATH, a y/N prompt offers to save it in your shell settings. Choose y, then open a new terminal to use it. Linux downloads require x86_64 and glibc 2.38 or newer.

Windows (PowerShell)

Invoke-WebRequest -UseBasicParsing https://gd.progsha.com/install.ps1 -OutFile install-gd.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\install-gd.ps1

If the installation directory is missing from PATH, a y/N prompt offers to add it to your user PATH.

Homebrew (macOS)

brew tap prog-sha/gd https://github.com/prog-sha/gd
brew install prog-sha/gd/gd

apt (Linux amd64)

Use an apt-based distribution with glibc 2.38 or newer, such as Ubuntu 24.04 or Debian 13.

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://gd.progsha.com/apt/gd.asc | sudo tee /etc/apt/keyrings/gd.asc >/dev/null
sudo chmod 0644 /etc/apt/keyrings/gd.asc
echo 'deb [arch=amd64 signed-by=/etc/apt/keyrings/gd.asc] https://gd.progsha.com/apt stable main' | sudo tee /etc/apt/sources.list.d/gd.list
sudo apt update
sudo apt install gd

Upgrading

gd upgrade            # Move to the latest release.
gd upgrade 0.8.0      # Move to a chosen version.
gd upgrade --dry-run  # Show the version without installing it.

The download is checked against the release's SHA-256 before the running gd is replaced. A gd installed through Homebrew or apt is upgraded with brew upgrade gd or apt upgrade gd instead.

Build from source

Install Python, uv, SCons, and a C/C++ compiler. Executables are written to bin/.

git clone --branch master https://github.com/prog-sha/gd.git
cd gd
scons platform=macos target=template_release -j8
# Linux ARM64: platform=linuxbsd arch=arm64
# Linux x86-64: platform=linuxbsd arch=x86_64
# Windows: platform=windows arch=x86_64 use_mingw=yes windows_subsystem=console

Quick start

Create one file, hello.gd. No config file or package is needed. main() is the entry point, and the integer it returns becomes the process exit code.

func main():
	print("Hello, world")
	return 0
gd hello.gd

To check types and syntax without running, use check.

gd check hello.gd

Import scripts and shared constants

Use @import "./settings" for a local file and @import hello for an installed package. Use the imported name directly; .gd and as settings can be omitted.

Put shared values in settings.gd:

const TITLE = "Hello"
const USER = "world"

Use them from main.gd:

@import "./settings"

func main():
	print(settings.TITLE, ", ", settings.USER, "!")
	return 0

This prints Hello, world!. Use this pattern when values need to be shared.

See Packages and distribution for installation and version locking.

Pick by purpose

The standard API has one entry point, GD, with a child per purpose. Scripts write these names as they are.

What you wantEntryExample
Files, text, time, HTTP client, asyncGDGD.file.read_text("a.txt")
Websites and Web APIsGD.webGD.web.app()
SQLite or PostgreSQLGD.databaseGD.database.client()
RedisGD.database.redisGD.database.redis.client()
TCP, UDP, TLSGD.netGD.net.listen_tcp("127.0.0.1", 8080)
Mail parsing and SMTP submissionGD.mailGD.mail.parse_address("me@example.com")

GD.database.postgres and GD.database.redis are advanced entries for features specific to one backend.

Looking up the API

gd --help lists the commands, and gd install --help describes one command's arguments and options.

Pass the same spelling you write in a script to gd doc. Signatures come from the executable, so they match the implementation.

gd doc                     # short guide and entry points
gd doc manual              # the full manual
gd doc GD                  # the children of GD
gd doc GD.file             # file API
gd doc GD.http.fetch       # the returned HTTP response
gd doc GD.web.app          # Web application
gd doc SceneTree           # Inspect a public engine class.
gd doc all                 # every public class

Return types such as Err and GDWebRequest are looked up by name alone. For Godot classes such as Node, SceneTree, and Timer, see the Godot class reference as well. The manual is shown in Japanese when LC_ALL or LANG starts with ja, and in English otherwise. The web version at gd.progsha.com switches between Japanese and English.

GDScript basics

The examples avoid repeating type names. Variables assigned with := infer their types from the right-hand side. Parameters without annotations remain dynamic. Add annotations only where you want to fix a type boundary.

Arguments and flags

Arguments placed after the script name arrive in main(argv). An argument that could be mistaken for gd's own flag, such as --name=gd, reaches the script when placed after --.

func main(argv):
	for arg in argv:
		print(arg)
	return 0
gd main.gd apple orange
gd main.gd -- --name=gd

To interpret them as flags, use GD.cli.flags(). It accepts --name gd, --name=gd, and -name=gd alike.

func main(argv):
	var flags := GD.cli.flags()
	flags.flag_str("name", "world", "who to greet")
	var _parsed, parse_err := flags.parse(argv)
	if parse_err:
		print(flags.usage())
		return 1
	print("Hello, " + flags.get_str("name"))
	return 0

Calling external commands

Call external tools with GD.cli.run(). Only the calling GDScript waits, so other requests proceed even when it is called from a gd serve handler. Under --strict it needs --allow-run. You can narrow the target, as in --allow-run=/usr/bin/git.

func main():
	var got, err := await GD.cli.run("git", ["rev-parse", "HEAD"])
	if err:
		return 1
	print("code=", got["code"], " out=", got["output"])
	return 0

A nonzero child exit returns an Err. Read the exit code from value.code and the output from value.output. A timeout or cancellation keeps the output captured so far.

The third argument, opts, changes the behavior.

NameDefaultMeaning
timeout0Seconds before giving up. 0 is unlimited. Past it, the child is shut down and Err.TIMED_OUT is returned
outputtrueCollect the output. With false, the child uses the parent's standard I/O directly and nothing is collected

Values and failures

A function that can fail returns two values: a value and an Err. Receive both with var value, e :=. Their types come from the function declaration; a non-null e means failure. Assign them to existing variables with value, e = call(). Variables declared without types remain Variant; declare var value: T and var e: Err when you want static checks.

func main():
	var text, e := GD.file.read_text("note.txt")
	if e:
		print(e.text())
		return 1
	print(text)
	return 0

Shorter failure handling

Append ? to a call to return its value and Err to the caller on failure. On success, use the value alone. A function using ? returns a value and Err. Without a return annotation, its first result is inferred from its return values; you can specify it as -> String, Err. On success, return value omits the null second result.

func title(path) -> String, Err:
	var text := GD.file.read_text(path)?
	return text.strip_edges()

func main():
	var text, e := title("note.txt")
	if e:
		print(e.note("read the title").text())
		return 1
	print(text)
	return 0

Return your own error

A readable file can still be invalid for your application. Create an Err when the message is empty. Err("message", kind, details) takes a description, a kind such as Err.INVALID_DATA, and optional details. Save this as read_message.gd:

# Read a message and reject empty contents.
func read_message(path: String) -> String, Err:
    var text := GD.file.read_text(path)?
    if text.strip_edges().is_empty():
        return "", Err("Message is empty", Err.INVALID_DATA, {"path": path})
    return text, null

# Print the message or report the failure to the caller.
func main() -> int:
    var text, err := read_message("message.txt")
    if err != null:
        printerr(err)
        return 1
    print(text)
    return 0
printf 'Hello!\n' > message.txt
gd read_message.gd
printf '' > message.txt
gd read_message.gd

The first run prints Hello!. After emptying the file, the second run reports Message is empty and exits with status 1.

Waiting and concurrency

Waiting methods in HTTP, databases, GD.net, files, and others are written as ordinary function calls. Only the calling GDScript waits; other networking and timers keep running.

func main():
	var res := GD.http.fetch("https://example.com/")!
	print(res.status)
	return 0

To start several operations together, use the variants ending in _async with GD.async.all().

func main():
	var got = await GD.async.all([
		GD.http.fetch_async.bind("https://example.com/a"),
		GD.http.fetch_async.bind("https://example.com/b"),
	])
	for result: Array in got:
		var res: GDHTTPResponse = result[0]
		var e: Err = result[1]
		if e:
			print(e.text())
			return 1
		print(res.status)
	return 0
EntryPurpose
name_async()Start the operation and move on at once. await it later for the same result as the regular name
GD.async.all(list)Run several operations together and return the results in the order given
GD.async.spawn(fn)Run a function in the background. It keeps running after main() returns
GD.async.sleep(sec)Wait the given number of seconds

To wait for a single one, receive it in the same shape as the regular name: var value, e := await GD.http.fetch_async(url).

Keep three points in mind.

Tutorial: a notes API on SQLite

With what you have read so far, this builds a small API that accepts JSON and stores it in SQLite, in one script. The result is a development server with input validation and SQL parameter binding, started with narrowed permissions.

1. Create a working directory

mkdir notes-api
cd notes-api

2. Write the API

Save the following as main.gd.

# Store notes in an embedded database and expose a JSON API.
extends RefCounted


const PORT := 18080 # development port listening on loopback
const DB_PATH := "user://notes.sqlite3" # per-user writable area provided by gd

var app := GD.web.app()
var db := GD.database.client()


# Return notes as JSON, newest first.
func list_notes(req: GDWebRequest) -> GDWebResponse, Err:
	var got, query_err := await GD.async.with_context_pair(req.context, db.query_async("SELECT id, title FROM notes ORDER BY id DESC"))
	if query_err:
		return query_err
	return GD.web.json(got.rows)


# Store a validated title and return the created row.
func add_note(req: GDWebRequest) -> GDWebResponse, Err:
	var body := req.valid("body")
	var made, query_err := await GD.async.with_context_pair(req.context, db.query_async(
		"INSERT INTO notes(title) VALUES($1) RETURNING id, title",
		[body.title]
	))
	if query_err:
		return query_err
	return GD.web.json(made.rows[0], 201)


# Prepare the database and routes, then listen on loopback.
func main() -> int, Err:
	db.open({"driver": "sqlite", "path": DB_PATH})?
	db.query("CREATE TABLE IF NOT EXISTS notes(id INTEGER PRIMARY KEY, title TEXT NOT NULL)")?
	app.route("GET", "/notes", list_notes)
	app.route("POST", "/notes", add_note, [GD.web.json_body(GD.web.object_rule({
		"title": GD.web.text_rule({"min": 1, "max": 120}),
	}))])
	app.listen(PORT, "127.0.0.1")?
	print("listening on http://127.0.0.1:%d" % PORT)
	return 0

Read it from the top.

3. Start with narrowed permissions

Run unverified scripts and servers exposed to the outside with --strict, which denies permissions by default. Here the listener is limited to one loopback port. serve keeps the process alive after main() returns, and it is the command to use for servers.

gd check main.gd
gd --strict --allow-net=127.0.0.1:18080 serve main.gd

4. Use it from another terminal

curl -s -X POST http://127.0.0.1:18080/notes \
  -H 'Content-Type: application/json' \
  -d '{"title":"try gd"}'
curl -s http://127.0.0.1:18080/notes

The first call returns status 201 with the created row, the second the stored array. An empty title, a title over 120 characters, or a non-JSON body is rejected with 400. Press Ctrl-C in the terminal that started it to stop.

In production, keep this process on loopback behind a TLS reverse proxy, and switch storage that must survive crashes to PostgreSQL. Keep connection details out of the source and read them from allowed environment variables.

Permissions

Start with normal execution. --strict is an advanced mode for explicitly designing and configuring the permissions a script needs.

ModeSuited toRestrictions
Normal executionRunning trusted source during developmentNeither files nor the network are restricted
--strictUnverified scripts, public serversThe startup directory is read-only; absolute paths outside it are denied. Network, environment variables, child processes, native extensions, and system information are denied by default

Under --strict, start by listing what the script uses.

gd --strict \
  --mount store=/srv/app:rw \
  --allow-net=db.example.com:5432 \
  --allow-env=DATABASE_URL \
  main.gd
FlagGrants
--mount name=path:r / --mount name=path:rwRead or read/write on a named directory
--allow-net=host:port,...Connecting and listening. Without a value, everything
--allow-env=name,...Environment variables
--allow-run=command,...Child processes
--allow-ext=path,...Native extensions a script loads while running
--allow-sys=item,...Machine and system information
--deny-*A denial that wins over the matching allow
-AAllow everything except files. For temporary use during development

--strict applies to the commands that run a script: run, serve, test, task, eval, and repl. Commands that do not run a script, such as check, fmt, and package operations, are unaffected.

File locations

A script sees files through four kinds of location. Write the name of the location at the start of the path, or write an absolute path as it is.

SpellingLocationUnder strict
res://a.txtThe directory the script was started fromRead-only
user://a.txtPer-user writable area provided by gdRead/write
store://a.txtThe name given by --mount store=/srv/app:rwAs specified
/etc/hostsThat location on the machineDenied unless it is inside the startup directory

When in doubt, put files you only read under res:// and files you save under user://.

Network and extension permissions

serve and SceneTree

gd serve is the resident way to run, and it creates no SceneTree. Networking, timers, await, custom Signals, GD.async.sleep(), and queue_free() on nodes outside a tree all work. With no work to do, it sleeps until the next deadline or network notification, so there is no cycle to tune.

What you wantHow
Keep a Web server or scheduled job residentgd serve main.gd
Use Node _process(), _physics_process(), process_frame, SceneTreeTimer, or high-level multiplayerNormal execution without serve
Run a script extending SceneTree or MainLoopNormal execution without serve
Check during development that no SceneTree slips ingd --no-scene-tree --allow-net serve app.gd
Listen with several processes--workers=<n> or --workers=auto. n is an integer of 1 or more

Under serve, a script that only extends Node is not added to a tree. --no-scene-tree reports a diagnostic as soon as a SceneTree is created and exits with code 1. It is inherited by --watch and --workers children.

Editor

gd editor opens the editor. The first run installs gd-godot, the executable that provides the window.

GoalCommand
Open the editorgd editor
Open a chosen projectgd editor <project directory>
Run a project in a windowgd run-game <project directory>

TCP and UDP

Use GD.net for low-level networking. Godot's low-level types remain for compatibility, but new code should use GD.net.

func echo() -> int, Err:
	var listener := GD.net.listen_tcp("127.0.0.1", 8080)?
	var conn := listener.accept()?
	var data := conn.read(65536)?
	conn.write(data)?
	conn.close()
	return 0

TLS

Open TLS with GD.net.dial_tls(host, port, opts). It verifies the certificate chain and host name by default, and a failure never falls back to plaintext. The result is the same GDTCPConn used for TCP.

optsMeaning
timeoutOne deadline in seconds covering both connect and handshake
ca_fileA private CA. It takes precedence over the environment settings
cert_file, key_fileClient authentication. Provide both, as files inside permitted mounts
server_nameCheck the certificate against a name different from the dial address
next_protosAn array of ALPN names. One name is 1–255 bytes, and the whole list is up to 65535 bytes
insecure_skip_verifySkip verification. Use only for tests where verification is deliberately unnecessary

Read the negotiated result from negotiated_protocol and version in connection_state(). TLS 1.2 is 771 and TLS 1.3 is 772.

Without other settings, the trusted CAs are the OS trust settings on macOS and Windows, and the system CA bundle on Linux. Set SSL_CERT_FILE or SSL_CERT_DIR before starting the process to use the given CAs on any OS. Directory lists use : on Unix and ; on Windows.

When a server requires client certificates, pass client_ca (a trusted CA bundle) and client_auth in the opts of app.listen_tls(port, cert, key, host, opts). A missing client_ca uses the system trust settings.

client_authBehavior
noneDoes not request a certificate
requestA certificate is optional. It is not verified
requireA certificate must be presented. It is not verified
verify_if_givenVerifies a certificate only when one is presented
require_and_verifyRequires a verified certificate

UDP and name resolution

Open UDP with GD.net.listen_udp(). A received packet carries the sender's host and port, so you can reply to it directly.

func echo_udp() -> int, Err:
	var conn := GD.net.listen_udp("127.0.0.1", 9000)?
	var packet := conn.read_from()?
	conn.write_to(packet.data, packet.host, packet.port)?
	conn.close()
	return 0

Mail

GD.mail parses addresses and headers and sends mail through an SMTP server.

func main() -> int, Err:
	var message := "From: me@example.com\r\nTo: you@example.com\r\nSubject: Hello\r\n\r\nHello\r\n".to_utf8_buffer()
	GD.mail.send_mail("smtp.example.com", 587, "me@example.com", PackedStringArray(["you@example.com"]), message, {
		"tls": "starttls", "timeout": 10.0,
		"auth": GD.mail.plain_auth("me@example.com", "secret"),
	})?
	return 0

Files and data

GD.file reads and writes files and handles paths. The directory you started from is res://, and absolute paths work as written. To write to an outside directory under strict, write the name given by --mount store=/srv/app:rw as in store://users.csv.

func main() -> int, Err:
	var rows := GD.data.csv_objects(GD.file.read_text("store://users.csv")?)?
	GD.file.write_text("store://users.json", JSON.stringify(rows))?
	return 0

File operations suspend only the calling GDScript, even under their regular names. Other requests proceed while a Web server handler reads a file. Use the variants ending in _async only to start several operations together.

func handler(_req) -> GDWebResponse:
	var body, read_err := GD.file.read_text("store://big.json")
	if read_err:
		return GD.web.text("cannot read", 500)
	return GD.web.text(body)

Files embedded by compile can be read, listed, and served statically through the same API.

Reading large files

To read without holding the whole file in memory, open a GDFileStream with GD.file.open(path, mode). Modes are read, write, append, and read_write. Call close() when done.

MethodBehavior
read(max)Returns up to max bytes. It may return fewer. An empty successful value is EOF
write(bytes)Writes all bytes and returns the count. On a failure partway, the first result retains the number already written

Operations on one stream run in arrival order, and separate streams proceed in parallel. Append always writes at the end, even after a seek. read_bytes() also retains the bytes already read in the first result when it fails partway. read_text() rejects input too large for a String instead of truncating it, so handle large files as bytes or a stream.

Files updated concurrently

When several processes update the same file, use GD.file.replace_text(path, old, body). It replaces the content only when the old you read still matches the current content, so a concurrent edit is never silently overwritten. Pass null as old to create a new file.

Entry points by data format

PurposeEntry
Reading CSV, TOML, YAML, JSONL, JSONC, XML, INI, TAR, front matter, and .env filesGD.file.read_csv(path) and similar
In-memory conversion of the same formats, JSON, codecs, hashes, HMAC, PBKDF2, HKDF, byte sequencesGD.data
UUID and ULIDGD.id
Time conversion and arithmeticGD.time
Text formatting and comparisonGD.text
HTML entities, tags, and gdhtml (a micro template with Mustache syntax)GD.html
Flags and environment variablesGD.cli
Array and dictionary operationsGD.collection
Special math values and bit operationsGD.math
Version comparisonGD.version
Logging to the terminal and filesGD.log
Test assertionsGD.test

Environment variables and .env have separate entries by what you read.

What you readEntry
Process environment variablesGD.cli.env(name, fallback) and GD.cli.require_env(name). Strict mode needs --allow-env
A .env fileGD.file.read_env(path). Reads the file into a dictionary
A dotenv stringGD.data.env(src) and GD.data.to_env(data). Convert to and from a dictionary in memory

In-memory conversions compute in place under their regular names, and their _async variants compute on another thread. Use _async for large inputs. Run gd doc GD.file and gd doc GD.data for the exact lists. Checks and limits per format are in the description of each entry in the API reference.

GD.collection operations that take a Callable yield to other work about every 1 ms. Each GD.log call waits until the write completes and never truncates the message. Check failures through the second Err result; GD.log.flush() waits for all earlier output.

JSON rules

Use GD.data.json_encode(value) to produce JSON bytes and GD.data.json_decode(bytes) to read received bytes. GDWebRequest.json(), GDHTTPResponse.json(), and each JSONL line follow the same rules.

func main() -> int, Err:
	var bytes := GD.data.json_encode({"id": 1, "tags": ["a", "b"]})?
	var value := GD.data.json_decode(bytes)?
	print(value.id)
	return 0

Hashes and key derivation

GD.data returns SHA-1, SHA-224/256/384/512, and SHA3-224/256/384/512 digests. HMAC, PBKDF2, and HKDF accept sha1, sha224, sha256, sha384, sha512, sha3-224, sha3-256, sha3-384, or sha3-512 as the hash name. PBKDF2 and HKDF accept an output length and return an Err for an invalid hash or settings outside the supported range. PBKDF2 iteration counts of one or less perform one iteration.

Web framework

Create main.gd and index.html in the same directory. One route renders a greeting through an HTML template; another returns the same data as JSON.

main.gd:

# Serve a greeting as an HTML page and a JSON response.
var app := GD.web.app()

# Build the shared response data from the requested name.
func greeting(req: GDWebRequest) -> Dictionary, Err:
	var name := req.query.get("name", "world")
	if not name is String:
		return {}, Err("name must be text", Err.INVALID_DATA)
	return {"name": name, "message": "Hello, " + name + "!"}

# Render the page with escaped template values.
func home(req: GDWebRequest) -> GDWebResponse, Err:
	return GD.web.view("index.html", greeting(req)?)

# Return the same data as JSON.
func hello(req: GDWebRequest) -> GDWebResponse, Err:
	return GD.web.json(greeting(req)?)

# Listen locally, using an optional port argument.
func main(args):
	var port := 8080 if args.is_empty() else int(args[0])
	app.route("GET", "/", home)
	app.route("GET", "/api/hello", hello)
	app.listen(port, "127.0.0.1")!
	print("http://127.0.0.1:", app.port())
	return 0

index.html:

<!doctype html>
<!-- Display a greeting and let visitors choose the name. -->
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{{message}}</title>
  <style>
    body { max-width: 36rem; margin: 4rem auto; padding: 0 1rem; font-family: system-ui, sans-serif; line-height: 1.6; }
    input, button { padding: .6rem; font: inherit; max-width: 100%; box-sizing: border-box; }
  </style>
</head>
<body>
  <h1>{{message}}</h1>
  <form action="/" method="get">
    <label>Your name <input name="name" value="{{name}}"></label>
    <button type="submit">Say hello</button>
  </form>
  <p><a href="/api/hello?name={{name}}">View the JSON response</a></p>
</body>
</html>

Run from that directory:

gd serve main.gd

Open http://127.0.0.1:8080/?name=Alice to insert “Hello, Alice!” into {{message}}. /api/hello?name=Alice returns {"name":"Alice","message":"Hello, Alice!"}. Template values are escaped for their HTML context.

serve keeps listening after main() returns. Stop with Ctrl+C.

Routes and replies

route(method, pattern, handler) binds an HTTP method and a path to a handler. :name in the pattern arrives in req.params["name"]. A HEAD request is answered by the GET route. A request whose path matches but whose method does not gets a 405. A handler receives a GDWebRequest. It reads only the needed body through req.read(), bytes(), text(), json(), or save(). A body sent by an HTML form becomes a dictionary with GD.http.decode_query(req.text()?).

The value a handler returns becomes the reply. Return one of the values in the table below as it is, such as return GD.web.json(data).

When a step fails, return its Err with call()?. The Err becomes the status code in the last row of the table. Register app.on_error(handler) to decide that reply yourself.

Returned valueReply
GD.web.html(body), GD.web.view(path, data)HTML
GD.web.json(data)JSON
GD.web.text(body), GD.web.bytes(body, type)Text, or any media type
GD.web.stream(producer)A body written a little at a time. See "Web operations and advanced features"
GD.web.redirect(to)302. to is limited to a path on the same site. Set away to true to send elsewhere
GD.web.not_found()404
A string200 as text/plain
A dictionary with bodyA handwritten reply. status, type, and headers are optional
A dictionary without body200 as JSON
null204
An ErrStatus by kind. INVALID_DATA → 400, UNAUTHENTICATED → 401, PERMISSION_DENIED → 403, NOT_FOUND → 404, LIMITED → 429, UNSUPPORTED → 501, TIMED_OUT → 504; other kinds → 500 (all are Err constants)

A reply can be adjusted as follows.

The router also accepts the following.

RegistrationPurpose
app.static("/assets", "res://public")Answer GET and HEAD under the prefix with files from the directory. The media type comes from the extension, and nothing outside the directory is served. Write the index of / as a route
app.group("/api", [middleware])A route group with a shared prefix and middleware. The result has route() and use()
app.fallback(handler)Requests matching no route. Return the 404 page here
app.on_error(handler)The reply when a handler returns a failure
app.after(handler)Reshape the reply before sending. Receives func(req, reply) and returns it with headers added

Middleware

Middleware is a function called before the handler. It receives a GDWebRequest, returns null to continue, or returns a reply to stop there. An object with handle(req) also works. Pass values to later stages with req.keep(name, value) and read them with req.kept(name).

RegistrationScope
app.pre(mw)Before route selection. Every request
app.use(mw)After route selection. Every route. Can read req.params
group.use(mw)Routes in that group
app.route(method, pattern, handler, [mw])That route only

Input validation is middleware too. GD.web.json_body(rule), GD.web.query(rule), and GD.web.params(rule) check the body, query, and path values, and put the values that pass into req.valid("body"), req.valid("query"), and req.valid("params"). Rules are built from GD.web.text_rule(), int_rule(), number_rule(), bool_rule(), list_rule(), and object_rule(), with GD.web.optional() and GD.web.one_of() for omission and choices. Query and path values are strings, so check them with text_rule() and convert with to_int() when needed.

var app := GD.web.app()

func show(req) -> GDWebResponse, Err:
	var params := req.valid("params")
	return GD.web.json({"id": params.id})

func main():
	app.route("GET", "/posts/:id", show, [GD.web.params(GD.web.object_rule({"id": GD.web.text_rule({"min": 1, "max": 20})}))])
	app.listen(8080)!
	return 0

The built-in middleware are GD.web.sessions(), GD.web.csrf(), GD.web.jwt(), and GD.web.rate(). The authentication section uses them.

HTML templates

As pages grow, move the HTML into template files and render them with GD.web.view(path, data). The template language is gdhtml, a micro template with Mustache syntax. It handles {{name}}, {{{html}}}, #if, #unless, #each, #with, else, and {{> header}}. Using {{> header}} from views/page.html reads views/partials/header.html at the same level.

<!-- views/page.html -->
{{> header}}
<main><h1>{{title}}</h1></main>
<!-- views/partials/header.html -->
<header><a href="/">gd app</a></header>
func page(_req) -> GDWebResponse, Err:
	return GD.web.view("views/page.html", {"title": "Top"})

Double-brace values are escaped by the context they appear in. The template author is trusted, the values inserted are not.

ContextHandling
HTML body, quoted and unquoted attributes, attribute namesHTML escape
href="{{url}}"Relative URLs and http, https, mailto pass. data-href is treated the same
href="/work/{{path}}", href="/?q={{query}}"Paths are normalized keeping separators, query values are percent-escaped
onclick, script bodyEncoded as JSON in a form where </script> cannot break the structure, even for application/json
styleSafe single CSS values and CSS strings and URLs pass
Dangerous URLs, srcset, CSS values, attribute namesReplaced with #ZgdunsafeZ or ZgdunsafeZ without failing the whole page

For a server that renders the same template repeatedly, parse it once at startup with GD.html.template(source, partials)?, then call execute(data)? on the returned value from each request. The parsed value is immutable and can be used by several requests at once. execute_bytes(data)? produces UTF-8 bytes directly, so they can be returned as is with GD.web.bytes(body, "text/html; charset=utf-8").

Authentication and CSRF

Login state is held by GD.web.sessions(). issue(value) creates a session ID, and the value of cookie(id) is returned as Set-Cookie. On routes that carry the same store as middleware, the value behind the cookie's ID arrives in req.kept("user"), and a missing session is a 401. An invalid middleware configuration returns null from its factory; passing it to app.use() or a route makes app.listen() report a configuration error.

var app := GD.web.app()
var sessions := GD.web.sessions()

func login(req: GDWebRequest) -> GDWebResponse, Err:
	var form := GD.http.decode_query(req.text()?)?
	var user := str(form.get("user", [""])[0])
	if user.is_empty():
		return GD.web.text("user is required", 400)
	var reply := GD.web.redirect("/me")
	return GD.web.header(reply, "Set-Cookie", sessions.cookie(sessions.issue(user)?))

func me(req) -> GDWebResponse, Err:
	return GD.web.text("hello, " + str(req.kept("user")))

func main():
	app.route("POST", "/login", login)
	app.route("GET", "/me", me, [sessions])
	app.listen(8080)!
	return 0

cookie(id) sets Secure and HttpOnly. If the cookie does not arrive during development without TLS, use cookie(id, false). Log out with drop(id) and clear_cookie(). Sessions live in one process, so with several processes under --workers use JWT or an external store.

Attach GD.web.csrf() to write paths that authenticate with cookies. Requests other than GET, HEAD, and OPTIONS need the browser's Sec-Fetch-Site: same-origin. When old browsers or non-browser clients must be accepted, choose GD.web.csrf({"allow_missing": true}) and combine it with separate token verification.

var app := GD.web.app()
var sessions := GD.web.sessions()

func save_email(_r):
	return "saved"

func main():
	app.route("POST", "/account/email", save_email, [GD.web.csrf(), sessions])
	app.listen(8080)!
	return 0

When JWT is used as a login session, revoke issued tokens on password change and logout. check is called after the signature and standard claims are verified, and authentication passes only when it returns true. For example, put the user's ver in the token and increment the stored version on password change. With several workers, compare against something like a cache synced from a shared DB, not a per-process dictionary.

func token_auth(key, versions):
	return GD.web.jwt(key, {"check": func(claims):
		return versions.get(claims.get("sub", ""), -1) == claims.get("ver", -2)
	})

To limit per IP behind a reverse proxy, list the proxy's IPs or CIDRs in trusted_proxies. gd strips trusted proxies from the right end of X-Forwarded-For and uses the first untrusted IP as the key. X-Forwarded-For is ignored when trusted_proxies is unset and when it comes from an untrusted peer, so a client cannot forge its own IP. IPv4 and IPv4-mapped IPv6 are matched as different things, so use an IPv6 CIDR to trust mapped addresses. Proxy settings with zones are rejected.

var per_ip := GD.web.rate({"limit": 60, "trusted_proxies": ["127.0.0.1", "172.18.0.0/16"]})

Allowed and 429 responses include X-RateLimit-Limit and X-RateLimit-Remaining. A 429 response also includes Retry-After in seconds.

Shutdown

Wait for shutdown with app.shutdown(context). It stops accepting new connections and keep-alive, then waits for in-flight requests. Past the deadline it returns Err.TIMED_OUT but does not kill in-flight requests. Use app.stop() when every connection must close immediately.

func close(app: GDWebApp):
	var context := GD.async.context().with_timeout(10.0)
	var _stopped, stop_err := app.shutdown(context)
	if stop_err:
		app.stop()

A handler can observe request completion and disconnection through req.context. with_cancel() and with_timeout() return a child context without changing the parent, and the parent's cancellation reaches the child. To cancel HTTP, database, process, and other two-result waits, wrap them with with_context_pair(), passing the context first. Use with_context() for single-value Signals. The operation result is returned when it finishes first; when the context finishes first, the operation is canceled.

func load(req: GDWebRequest, db: GDDatabaseClient) -> Variant, Err:
	return await GD.async.with_context_pair(req.context, db.query_async("SELECT * FROM posts"))

Web operations and advanced features

Limits and large uploads

When handling large bodies or long handlers, set the limits explicitly with limits() before listening.

func main():
	var limited_app := GD.web.app()
	limited_app.limits({"header_bytes": 1048576, "header_values": 500, "header_timeout": 15.0, "body_timeout": 10.0, "job_timeout": 30.0, "jobs": 128})
	return 0

To accept a 1 GB ZIP, put a per-request limit on it and stream it to a writable mount.

func main():
	var app := GD.web.app()
	app.limits({"body_timeout": 600.0})
	app.route("POST", "/upload", func(req: GDWebRequest) -> GDWebResponse, Err:
		req.limit(1000 * 1000 * 1000)?
		req.save("uploads://package.zip")?
		return GD.web.text("saved")
	)
	var _server, listen_err := app.listen(8080, "127.0.0.1")
	return 0 if listen_err == null else 1
gd --strict --allow-net=127.0.0.1:8080 --mount=uploads=/srv/uploads:rw serve main.gd

How you read the body decides how much memory it uses.

ReadingMemory use
read(), save()Read a little at a time. save() never holds the whole body in memory
bytes(), text(), json()Read the whole remaining body into memory. Use save() for large bodies
req.limit(bytes)Body limit for that request. Past it, the reading operation fails

Streaming bodies

GD.web.stream(producer, length=-1, type="application/octet-stream", status=200) sends only what producer(writer) writes to the GDWebWriter. It never joins the whole body in memory. The producer may await, and it finishes by returning void or a value and Err.

GDWebWriterBehavior
write(data, offset=0, count=-1)Sends a range of a byte array and returns the accepted bytes. When sending is backed up, it waits until it progresses
write_text(text, offset=0, count=-1)Sends a range of a string as UTF-8. Offset and count are in characters; the result is in bytes
flush()Waits for preceding writes to be sent. A disconnect shows up as an error here and as req.context cancellation

HTTPS and HTTP/2

Start HTTPS with app.listen_tls(8443, "cert://chain.pem", "cert://key.pem", "127.0.0.1") and check the second Err result. Mount the certificate directory read-only with --mount cert=/path/to/certs:r. Pass a PEM chain and an unencrypted private key. When key validation fails, no port is opened.

TLS 1.2 and 1.3 are supported, and ALPN selects HTTP/2 or HTTP/1.1. Each HTTP/2 stream proceeds independently, and canceling one does not close the others. header_timeout also applies to an incomplete handshake. For requiring client certificates, see the TLS tables in "TCP and UDP".

gzip compression

GD.data.gzip_writer(writer, level=-1) creates a GDGzipWriter that gzips the bytes written to it and passes them to the writer below. The writer below can be a GDFileStream, a TCP connection, or a GDWebWriter. The whole body is never held in memory.

ItemDetails
Methodswrite(bytes), flush(), close(), and reset(writer). Each returns a value and Err
level-2 (Huffman only), -1 (default), and 0..9
close()Finishes the gzip trailer. It does not close the writer below
reset(writer)Clears errors and reuses the compressor at the same level
headername and comment (non-NUL Latin-1), extra (up to 65535 bytes), mod_time (Unix seconds from 0 to 4294967295), and os (default 255). Set it before the first write

For HTTP, return GD.web.header(GD.web.stream(producer), "Content-Encoding", "gzip"); the producer creates the compressor, writes, and returns the result of close(). Checking Accept-Encoding and setting Vary are up to the caller. Do not compress secrets together with external input, and do not apply it to an already compressed body or a partial response.

Listen address and port

For an IPv6-only localhost listener, use app.listen(8080, "::1")!. Under strict use --allow-net=[::1]:8080, and connect to http://[::1]:8080/. ::1 and 127.0.0.1 are separate listeners, and both differ from ::, which means every interface.

To let the OS pick a free port, read app.port() right after app.listen(0). The number is obtained while holding the listener, so no other process can take it. Check app.serve_error() for a listener failure after startup. Temporary resource shortages cause a short retry; a permanent failure closes the listener. Under strict the chosen port cannot be limited ahead of time, so allow the whole host, as in --allow-net=127.0.0.1. GD.net.free_port() and is_free() are momentary diagnostics, not a way to reserve that number.

HTTP client connections

Web settings

The settings passed as a dictionary to GD.http.fetch() and the GD.web functions, with their defaults. Times are seconds and sizes are bytes.

EntrySetting and defaultMeaning
GD.http.fetchmethod="GET", headers={}, body=nullHTTP method, request headers, request body
sametimeout=0.0, max_body=0Seconds for the whole request and bytes of the response body. 0 is unlimited. New TCP connections default to 30 seconds and TLS handshakes to 10 seconds
samesave="", sha256=""Stream a 2xx body to save, returning an empty body. sha256 requires save, is 64 hex digits, and only a matching completed file is placed
sameauthority="host:port"Request target for CONNECT only
GDWebApp.limitsjobs=0, job_timeout=0.0Number of async handlers kept and seconds. 0 is unlimited
sameheader_timeout=0.0, body_timeout=0.0Seconds to finish receiving request header/body. 0 is unlimited
sameheader_bytes=1048576, header_values=2147483647Header bytes including the request line, and the header line count
GD.web.jwt_signttl=900Seconds used to fill iat/exp. 0 does not add them
GD.web.jwt / jwt_verifyleeway=0.0, require_exp=trueClock tolerance in seconds, and whether exp is required
sameiss="", aud="", keep="jwt"Issuer/audience match when non-empty, and the name kept on the request
samecheck=Callable()Revocation check receiving claims after signature verification. When set, only true passes
GD.web.sessionstotal=1024, per_user=3Sessions per process, and per user
sameidle=1800, life=43200Idle and maximum lifetime in seconds
samecookie="sid", keep="user"Cookie name and the name kept on the request. The cookie name uses ASCII token characters
GD.web.ratelimit=60, window=60.0Largest burst per key, and the seconds that refill that many requests
sameexpires=180.0Seconds after the last request before a key is released
samekeys=0, key=Callable()Keys kept per process and the key selector. Zero is unlimited. A full explicit store evicts the earliest expiring key
sametrusted_proxies=PackedStringArray()IPs or CIDRs of proxies whose forwarded IP is trusted
GD.web.csrfallow_missing=falseWhether to allow state changes from clients without Fetch Metadata
GD.web.text_rulemin=0, max=4096Text length in characters
GD.web.int_rulemin=-9223372036854775808, max=922337203685477580764-bit integer range
GD.web.number_rulemin=-1e308, max=1e308Finite float range
GD.web.list_rulemin=0, max=1024Element count
GD.web.object_ruleextra=falseWhether to keep undeclared fields

GDWebApp.limits accepts only the six listed setting names and rejects misspellings and body_limit.

A value outside the accepted range fails when set. The ranges are listed with each function in the API reference.

Database

The client returned by GD.database.client() handles SQLite and PostgreSQL with the same code. Switching from the embedded SQLite in local development to PostgreSQL in production is done through the driver passed to open().

func main() -> int, Err:
	var local := GD.cli.env("DB_DRIVER", "sqlite") == "sqlite"
	var db := GD.database.client()
	db.open({
		"driver": "sqlite" if local else "postgres",
		"path": "user://app.sqlite3",
		"host": "127.0.0.1",
		"database": "app",
		"user": "app",
		"password": GD.cli.env("PGPASSWORD", ""),
	})?
	db.query("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")?
	db.query("INSERT INTO users (id, name) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING", [1, "ada"])?
	var out := db.query("SELECT id, name FROM users WHERE id=$1", [1])?
	print(out.rows[0].name)
	db.close()
	return 0

Table creation, INSERT, and SELECT all go through the one query(). It yields a dictionary with columns, rows, and tag, where rows is an array of dictionaries keyed by column name. In the example, out.rows[0].name is ada. SQL values are bound in order as $1, $2, and the spelling is the same on both drivers. SQL is not translated, so use SQL that works on both.

MethodPurpose
query(sql, args)Collect and return the whole result
query_row(sql, args)Return only the first row. Err.NOT_FOUND when there is no row
query_rows(sql, args)Open GDDatabaseRows and read one row at a time. For large results
stats()Connection count, in use, idle, wait count, wait duration, and cumulative close counts by reason

Advance query_rows() with while rows.next(). scan() returns a dictionary keyed by column name and values() returns an array in column order. After next() returns false, inspect err(). Call close() when stopping early.

func list_users(db: GDDatabaseClient) -> Variant, Err:
	var rows := db.query_rows("SELECT id, name FROM users ORDER BY id")?
	while rows.next():
		var user := rows.scan()?
		print(user.id, " ", user.name)
	if rows.err() != null:
		return null, rows.err()
	return null

On a constraint violation, the second result e.info carries machine-readable details. violation is one of duplicate, not_null, or foreign_key, and columns lists the related column names. On PostgreSQL, code, table, and constraint are included when the server returns them. Values themselves are never kept in info. A failure reported by SQLite itself keeps source="sqlite" and its extended source_code. SQLite's foreign key message has no column names, so columns is empty there.

func save(db: GDDatabaseClient) -> void:
	var _saved, e := db.query(
		"INSERT INTO users(id,name) VALUES($1,$2)",
		[1, "ada"])
	if e and e.info.get("violation") == "duplicate":
		var columns := e.info.get("columns", PackedStringArray())
		print("duplicate columns: ", columns)

Transactions and migrations

To make several updates one success or failure, use transaction(). The callback receives a GDDatabaseTx pinned to one connection. A null second result commits, while an Err rolls back.

func save(db: GDDatabaseClient, id: int, title: String) -> Variant, Err:
	return db.transaction(func(tx: GDDatabaseTx) -> int, Err:
		tx.query("INSERT INTO posts(id,title) VALUES($1,$2)", [id, title])?
		tx.query("UPDATE counters SET value=value+1 WHERE name='posts'")?
		return id
	)

When a PostgreSQL transaction fails because it collided with another one running at the same time (SQLSTATE 40001), serialize() retries it.

func increment(db: GDDatabaseClient, id: int) -> int, Err:
	var saved, e := db.serialize(func(tx: GDDatabaseTx) -> int, Err:
		tx.query("SET TRANSACTION ISOLATION LEVEL SERIALIZABLE")?
		tx.query("UPDATE counters SET value=value+1 WHERE id=$1", [id])?
		return id
	)
	return saved, e

To apply a schema in order, pass an array of statements to migrate() instead of splitting SQL on semicolons. If one statement fails, everything rolls back. On success it returns the number of statements applied. Versions and checksums are managed by the application.

func migrate(db):
	return db.migrate([
		"CREATE TABLE posts(id INTEGER PRIMARY KEY, title TEXT NOT NULL)",
		"CREATE INDEX posts_title ON posts(title)",
	])

Advanced database features

Driver differences

ItemSQLitePostgreSQL
Suited toLocal development, a single processProduction, crash resilience, several workers
ConnectionOne per client. Journal and temporary tables live in memoryA pool that opens only the connections it needs. Set a maximum as in pool=25
Extra entriesGD.database.sqlite.open() for short work done in placeGD.database.postgres for batched sends, arrays, and JSONB
NotesPersistent databases recover unfinished writes with a rollback journal. Checkpoint existing -wal and -shm files with regular SQLite before openingHosts other than loopback verify the TLS certificate and host name by default. Loopback defaults to no TLS

open() on GD.database.postgres.client() and GD.database.redis.client() takes the target as arguments, in the form open(host, port, opts).

SQLite concurrency

query() calls on one client run in arrival order. Separate clients proceed concurrently, while writes to the same database file follow SQLite locking. The GDSQLiteDB and GDSQLiteStatement returned by GD.database.sqlite.open() are a synchronous API that runs directly on the caller. Use them only for short work and never concurrently. Use GDDatabaseClient for concurrent work.

PostgreSQL connections and types

The pool opens connections as they are needed and takes them back after use. Normally you just call query() without thinking about connections. When none is free, queries wait in turn.

GoalHow
Run several SQL statements as one unitUse transaction() instead of sending BEGIN yourself
Send several SQL statements togetherquery_many, fetch_many, exec_many
Detect a duplicate insertErr.ALREADY_EXISTS. Read the SQLSTATE in e.info.code for the exact cause
See whether there are enough connectionswait_count in stats() (times a query waited for a connection)
Pin the authentication methodauth="scram". auth="md5" is for older servers

Column values arrive as these types.

Column typeReceived value
real, double precisionfloat
numericText, so no digits are lost
json, jsonbDictionaries and arrays. Integers stay int
Arrays such as int[] and text[]An Array of the same element type. Nulls and nesting are kept

A query that is cancelled or times out closes its connection. The SQL on the server may not stop at once. The character encoding is UTF-8.

Redis connections

Use Redis through GD.database.redis.client(). Pass the command name and its arguments separately to query().

func main() -> int, Err:
	var redis := GD.database.redis.client()
	redis.open("127.0.0.1", 6379)?
	redis.query("SET", ["greeting", "hello"])?
	print(redis.query("GET", ["greeting"])?)
	redis.close()
	return 0
GoalHow
Tell that a value is missingGET returns Err.NOT_FOUND
Send several commands togetherpipeline(cmds). Results come back as an Array in the order sent
Use it from many requests at onceGD.database.redis.pool(). Connections open on the first query()
Use MULTI, WATCH, SELECT, or subscriptionsA dedicated GDRedisClient, not the pool
Set a deadlinetimeout in open() (seconds)

The TLS choice is the same as PostgreSQL.

Database settings

The settings passed as a dictionary to open(), with their defaults.

EntrySetting and defaultMeaning
GDDatabaseClient.opendriver="postgres", path=""Driver and SQLite path. SQLite needs user://... or :memory:
samehost="127.0.0.1", port=5432PostgreSQL target
samepool=0PostgreSQL maximum connections. 0 is unlimited. Unused by SQLite
samemax_rows=0, max_bytes=0Rows and bytes per result collected by query(). 0 is unlimited. Not applied to query_rows()
GDPostgresClient.openuser="postgres", database="postgres", password=""Credentials and database name
sameconnect_timeout=0.0, timeout=0Connect and query seconds. Waiting for a pool connection counts toward the query time. Zero has no deadline; set either deadline when needed
sameauth="any", allow_cleartext_password=falsePin the method with auth="scram"/"md5". A cleartext password reply only when explicit
sametls=<decided by host>, ca=""External hosts use verify-full, loopback disable. A CA file only when explicit
GD.database.sqlite.openbusy_ms=0, max_ms=0, foreign_keys=falseLock wait and execution deadline in milliseconds. busy_ms=0 reports contention immediately; max_ms=0 has no execution deadline. Enable foreign-key checks explicitly
samemax_rows=0, max_bytes=0Rows and bytes per result. 0 is unlimited
GDRedisClient.openpassword="", dial_timeout=5, read_timeout=5, write_timeout=5Password, and connect, read, and write deadlines in seconds. An explicit 0 is unlimited. timeout sets all three, and an individual setting wins
sametls=<decided by host>, ca=""The same TLS choice as PostgreSQL
GD.database.postgres.poolsize default 0; 0 or 1..21474836470 is unlimited. Connections open only as needed
GDPostgresPool.openmax_idle=2Connections kept after work ends. 0 keeps none. Never exceeds the maximum
GD.database.redis.poolsize default 0; 0..2147483647Maximum connections. 0 selects ten times the CPU count. Simultaneous dials do not exceed the maximum
GDRedisPool.openpool_timeout=read_timeout+1.0 (30 seconds when the read deadline is 0), conn_max_idle_time=1800Deadline for waiting for a free connection, and how long a returned connection stays reusable. An explicit 0 is unlimited. An expired idle connection is closed at the next borrow

Set read_timeout explicitly to extend the deadline for a long Redis query.

A query() over max_rows or max_bytes fails only that query. The whole connection is closed when ordering is lost through a deadline or a corrupt reply.

A value outside the accepted range fails when set. The ranges are listed with each function in the API reference.

Scheduled jobs

A job that runs once at a fixed time is an ordinary script, called from the OS's cron or a systemd timer. gd needs no resident scheduler for it.

func collect() -> int, Err:
	var now := GD.time.to_iso(GD.time.now())
	GD.file.append_text("store://log.txt", now + "\n")?
	return 0

func main() -> int, Err:
	collect()?
	return 0
gd --strict --mount store=/var/lib/app:rw collect.gd

A job that loops on its own interval is passed to GD.async.spawn() and kept resident with gd serve. Work passed to spawn() keeps running after main() returns.

func every(sec, fn):
	while true:
		await GD.async.sleep(sec)
		fn.call()

func collect():
	print(GD.time.to_iso(GD.time.now()))

func main():
	var _job := GD.async.spawn(every.bind(60.0, collect))
	return 0
gd serve schedule.gd

Stop it by ending the process. It is resident like a Web server, so serve is needed here too.

Official extension modules

The core stays small. Features specific to an external service are added as GDScript packages or GDExtensions only to projects that need them.

EntryPurposeSetup
DiscordPure-GDScript text bots on the Discord Gateway and RESTgd add @mofukuma/discord
GDMemcachedCache client reusing TCP connectionsgd add ext:@mofukuma/memcached
GDSupabaseDatabase and Auth clientgd add ext:@mofukuma/supabase

Browse published packages in the package list. Because they are optional, they are not part of the API reference generated from the core.

Packages and distribution

To use a package someone else published, create gd.json with gd init and then add the package. Find published packages in the package list or with gd search.

gd init
gd add hello
GoalCommand
Searchgd search discord
Addgd add hello (gd install hello does the same)
Choose the scope or a version rangegd add @mofukuma/hello@^0.1.0
Add under a name you choosegd add greet @mofukuma/hello
Add a native extensiongd add ext:@mofukuma/memcached
Add from a URL or a local directorygd add util https://example.com/util.gd, gd add ../mylib
Restore the same versions elsewheregd install --frozen
Check for and move to newer versionsgd outdated, gd update
Removegd uninstall hello
List what is installedgd info

Dependencies are recorded in gd.json (what you use) and gd.lock (which versions). Commit both. gd install without arguments restores the dependencies in gd.json; --frozen, --cached-only, and --sync apply to that restore.

Using packages

Read an installed package by writing @import alias at the top of a script.

@import hello

Installing as a command

gd install -g installs a package or script as a command such as my-tool. It leaves the gd.json and gd.lock of the project you are in untouched.

gd install -g tool                      # Install a published package by its short name.
gd install -g @scope/tool@1.0.0         # Choose the scope and version.
gd install -g --name my-tool ./tool.gd  # Install a local script.
gd uninstall -g my-tool
FlagMeaning
-n / --nameCommand name. Defaults to the package or script name (the parent directory name for main.gd or mod.gd)
--root <dir>Install location. Defaults to GD_INSTALL_ROOT, then the default cache. Add its bin/ to PATH
-f / --forceUpdate an installed command
-- argsFixed arguments passed first on every launch

Short import syntax

@import is the short form of const Name = preload(...).

It is useful even without external dependencies: see samples/packages for a real registry dependency and its lockfile.

@import greet
@import "./util"
@import greet/style as theme

Creating a package

A package is one project rooted at its gd.json. gd init @scope/name seeds mod.gd and a test, gd test runs it, and gd publish releases it.

{"name":"@scope/hello","version":"1.0.0","main":"src/mod.gd","include":["src"]}
gd publish
gd add hello gd:@scope/hello@^1.0.0

Packages submitted to the public registry become searchable and installable after review. When gd publish prints a review ID, the version remains private until accepted.

A package under development is added from a local path with gd add ../path. Its alias comes from the name in its gd.json. The checkout is copied under pkg/<alias>/ and copied again on the next run whenever its content fingerprint changes. Files starting with ., pkg/, tmp/, subdirectories holding a gd.json, and token are not copied. gd publish turns a local import into its registry range when the target's gd.json has name and version, and refuses it otherwise.

Local development channel

Start the real registry on loopback from the repository. It saves published versions under tmp/dev-channel/data.

export GD_TOKEN='development token'
uv run --no-project python -B devtools/channel.py serve --scope dev --port 8787

In another terminal, set GD_REGISTRY=http://127.0.0.1:8787 and the same GD_TOKEN. Run gd publish --dry-run and gd publish from an @dev/name package. Consumers using that GD_REGISTRY can run gd search, gd add, gd install, gd install -g, and gd compile. A project's registry in gd.json takes precedence over the environment.

Dependency resolution

gd install resolves the whole dependency graph. It picks a version in this order: the version gd.lock pins, a version already chosen this time that satisfies the range, then the newest match in the registry.

gd.lock also records the resolved imports configuration. A run after a configuration change uses the same resolver instead of silently loading an outdated version. --frozen rejects mismatched requests. When multiple aliases name one package, the lexicographically first alias selects its copy directory.

Sharing a location with Godot

To share a project with tools that only read res://, such as upstream Godot, set "place": "project" in gd.json. Packages are copied under pkg/<alias>/, and both pkg:// and res://pkg/ point there. A package that only other packages use goes under pkg/@scope/name@version/.

Native extension packages

Settings and environment variables

gd.json has these eleven settings.

NameWritten by gd init / when omittedMeaning
namemy-tool / requiredProject name. Publishing needs @scope/name
version0.1.0 / requiredPackage version
tasksrun and test / noneCommands invoked by gd task
imports{} / {}Alias and dependency source. A published package may name registry packages only
registryomitted / environment or the public registryRegistry URL pinned to the project
mainomitted / mod.gdmod.gd or .gdextension entry published
includeomitted / main onlyFiles or directories inside the main directory included in a pure GDScript package
placeomitted / cache, or project beside project.godotWhere packages live. project copies them under pkg/
godotomitted / falseDeclares a package that runs on upstream Godot without gd's own API
descriptionomitted / emptyDescription shown in the registry
assetsomitted / noneGodot asset management alias and channel:publisher/slug[@version]; installed into addons/

gd reads these environment variables. A script that reads the environment needs the names allowed with --allow-env.

VariablePurpose
GD_CACHE_HOMEPackage cache root. Defaults to gd in Windows LocalAppData. On macOS/Linux, uses an absolute XDG_CACHE_HOME plus /gd, or .gd under the home directory. The OS account directory is used when HOME is unset
GD_INSTALL_ROOTWhere gd install -g places commands. --root wins
GD_USER_HOMEAbsolute path for user://. By default it uses a working-directory-specific temporary area
GD_REGISTRYRegistry. Defaults to https://gd.progsha.com/pkg. registry in gd.json wins
GD_RELEASESRelease source read by gd upgrade. Defaults to https://github.com/prog-sha/gd/releases
GD_TOKENPublish token. Keep it out of config files and pass it only to the publishing process
LC_ALL, LANGLanguage of the manual shown by gd doc
GD_WORKERInternal mark set by --workers. Not a user setting

Remote packages and registries use HTTPS. A development registry on loopback may also use HTTP. Fetched packages and native libraries are checked against the SHA-256 in the registry index. All files in a package are limited to 500 MiB in total.

Distributing a single executable

compile collects scripts, views, static files, migrations, dependency packages, and the target OS's GDExtensions into one executable. The target needs no cache.

gd compile -o app main.gd
./app

Asset channels

gd search includes packages, the public Godot asset catalog, and the reviewed gd catalog. A project using a custom registry searches only that registry.

ChannelSource
officialGodot Asset Store
gdReviewed gd assets

Copy an asset:channel:publisher/name result directly into gd add.

gd search dialog
gd add asset:official:publisher/dialog
gd add ui asset:gd:publisher/dialog@1.2.0
gd install --frozen --cached-only
gd update ui
gd uninstall ui

The source distribution also includes a catalog inspection client:

gd tools/store.gd channels
gd tools/store.gd search official 4.7 dialog
gd tools/store.gd show gd publisher dialog
gd tools/store.gd releases gd publisher dialog

Scope and reporting

gd is a public release before the API has settled. Do not assume backward compatibility. Changes and the Godot version used as the base are recorded in the CHANGELOG. gd is not an official product of the Godot Foundation or the Godot Engine project.

Report bugs in Issues. Report vulnerabilities that should not be public through GitHub private reporting.