giolt

Build, run and deploy Gleam apps on Giolt.

Add it as a dev dependency and run it. It works on Node 20 or newer, which is Gleam's default JavaScript runtime, and on Bun:

gleam add --dev giolt
gleam run -m giolt build
gleam run --runtime bun -m giolt build

Your entry module exports one function named handle:

// JavaScript target
pub fn handle(req: Request(conversation.RequestBody)) -> Response(conversation.ResponseBody)

// Erlang target (GlowVM)
pub fn handle(req: wisp.Request) -> wisp.Response

giolt build checks this signature against gleam export package-interface and fails with the expected and found types when it does not match.

Commands

Command	Does
`giolt build [--config FILE]`	Checks `handle`, compiles and bundles into `outdir`
`giolt dev [--config FILE]`	Builds, watches `watch`, serves on `port` and reloads on change (JavaScript target)
`giolt deploy [--preview] [--artifact DIR] [--project NAME] [--config FILE]`	Builds, then uploads `outdir` to Giolt (JavaScript target). With `artifact`, uploads that directory instead
`giolt link NAME [--config FILE]`	Writes `project = <id>` under `[tools.giolt]`, so `deploy` needs no flags. Commit the file so CI deploys there too
`giolt unlink [--config FILE]`	Removes that `project` line
`giolt help`	Prints the commands. `giolt <command> --help` prints that command's flags

gleam run -m giolt -h prints help for gleam run, not for giolt, because Gleam reads the flag first. Use gleam run -m giolt help or gleam run -m giolt with no arguments instead.

link and unlink edit the file as text, so comments and layout stay as they are. They write to the --config file when you pass one.

deploy picks its project and token like this:

--project NAME wins over the linked project. A name needs a user token to look up.
The token is GIOLT_TOKEN when set, otherwise the one giolt login stored.
With a project, deploy uploads to that project. A deploy key in GIOLT_TOKEN can deploy its own linked project.
With no project and a deploy key in GIOLT_TOKEN, deploy works as before: the key names the project.
GIOLT_TOKEN goes to GIOLT_API_URL, then api_url. A stored login only goes to the URL it logged in against.

Account and projects

Command	Does
`giolt login`	Shows a code and opens the dashboard so you can approve it in the browser, then stores the token
`giolt login --token -`	Reads a token made on the dashboard's Tokens page from stdin and stores it. It starts with `giolt_`; deploy keys are refused. `--token TOKEN` also works, but leaves the token in your shell history
`giolt logout`	Revokes the stored token and deletes it. If the revoke fails, the file is still deleted and you are told to revoke the token on the dashboard
`giolt whoami`	Shows the account email, the token's name, scopes and expiry, and where the token came from
`giolt projects`	Lists your projects with their URL and latest deployment status
`giolt projects create NAME`	Creates a project
`giolt projects rename OLD NEW`	Renames a project. The old URL stops working and there is no redirect
`giolt projects delete NAME [--yes]`	Deletes a project and its deployments for good. Asks you to type the name, or needs `--yes` when there is no terminal
`giolt usage`	Shows the account's requests against the included amount for the current billing period; `--json` prints it for scripts

Creating, renaming and deleting need an active subscription; the error says where to set one up.

giolt login stores the token in credentials.json, readable only by you, in:

$XDG_CONFIG_HOME/giolt/, or ~/.config/giolt/ when that is unset (Linux and macOS)
%APPDATA%\giolt\ (Windows)

pbpaste | gleam run -m giolt login --token -

Logging in again revokes the token it replaces.

GIOLT_TOKEN takes precedence over the stored token, so CI can set it without logging in. These commands need a user token, so a deploy key in GIOLT_TOKEN is refused. They never read gleam.toml, so a project's api_url cannot send your token elsewhere:

giolt login uses GIOLT_API_URL, or https://dash.giolt.com when that is unset, and stores that URL with the token.
The stored token is only ever sent to the URL stored with it.
GIOLT_TOKEN is sent to GIOLT_API_URL, or https://dash.giolt.com.

giolt logout only removes the stored token; it does not unset GIOLT_TOKEN.

Configuration

Everything is optional and lives under [tools.giolt] in your gleam.toml, or in the TOML file you pass with --config FILE when one package needs several builds (the package name and target still come from gleam.toml, and keys the file leaves out take their defaults):

Key	Default	Meaning
`entry`	your package name	Module that exports `handle`, such as `my_app/server`
`assets`	none	Directory of static files, copied to `outdir/static` and served by `dev`
`outdir`	`"./dist"`	Where the bundle goes. It is deleted before every build
`esbuild_args`	`[]`	Extra esbuild flags, appended after the fixed ones so they win
`spa`	`false`	Serve `index.html` for paths that match no file. Static-only apps: requires `artifact` (or `deploy --artifact`)
`watch`	`["src"]`, plus `assets`	Directories `dev` watches
`port`	`3000`	`dev` server port
`live_reload`	`true`	Reload the browser after a rebuild
`api_url`	`"https://dash.giolt.com"`	Giolt API used by `deploy`. The account commands ignore it
`prebuild`	none	Shell command run before every build, such as `gleam run -m docs/build`
`artifact`	none	Deploy this directory as a static site. Skips the `handle` check, the compile and the bundle
`project`	none	Id of the project `deploy` uploads to. Set by `giolt link`

Erlang target

A project with target = "erlang" builds for GlowVM. You need Erlang/OTP and rebar3 installed, and giolt build tells you which one is missing. The output in outdir is app.avm plus the runtime files (glowvm.wasm, index.js, index.min.js). dev and deploy do not support this target yet.

Issues

Report bugs and requests at github.com/withgiolt/issues.