Command line reference | Gleam programming language

Gleam's command line is the primary way of working with Gleam projects.

Most commands have to be run from within a Gleam package, i.e. a directory containing a gleam.toml file and a src directory containing Gleam code.

add

Add new dependencies to the package.

The newest compatible version of the package is determined, and then gleam.toml is updated to require at least that version, with a range permitting future patch and minor updates.

Add the package "wibble":

gleam add wibble

Add the package "wibble", requiring version >= v2.0.0 and < v3.0.0:

gleam add wibble@2

Add the package "wibble", requiring version >= v2.5.1 and < v3.0.0:

gleam add wibble@2.5.1

Add multiple packages:

gleam add wibble@2 warble@1

Add a package as a non-production dependency:

gleam add --dev wibble

You can also edit gleam.toml directly, for further control over your package dependencies. Run gleam help deps for documentation on the format.

build

Compile the Gleam package. Any dependencies will be downloaded and compiled as required. If the package has been previously compiled then only the Gleam modules that have changed will be compiled.

gleam build --target javascript

The --target flag is used to pick which compilation target to use. It has two possible values, erlang and javascript. If this flag is not given then the target value from gleam.toml is used, and if neither are present then the Erlang target is used.

gleam build --warnings-as-errors

When the --warnings-as-errors flag is given if there are any warnings emitted during compilation then the build is considered a failure, and a non-zero exit-code will be used. This may be useful to run on CI, to ensure that all warnings are fixed before merging changes into the main branch.

gleam build --no-print-progress

When given this flag disables the progress messages that Gleam prints during compilation.

check

Analyse the project for errors. This command is similar to gleam build except compilation halts after type checking, skipping optimisation and code generation. It may be useful in-development for rapidly checking code is valid while writing it.

gleam check --target javascript

clean

Delete the build directory and all build artefacts.

gleam clean

compile-package

This command is a lower-level compilation API that very few people will have a use for. The most common time you would want this command is if you are adding Gleam support to some other build tool.

gleam compile-package \
    --target javascript \
    --package ./packages/wibble \
    --out ./build \
    --lib ./build \
    --javascript-prelude prelude.mjs

The --target flag is used to pick which compilation target to use. It has two possible values, erlang and javascript.

The --package flag specifies the path to the Gleam package to be compiled.

The --out flag specifies the path to compile the package to.

The --lib flag specifies the path to where the compiler can file can find the already-compiled dependencies of the package being compiled.

The --javascript-prelude flag specifies the path to the JavaScript prelude module, relative to the out directory. This is required when compiling to JavaScript.

The --no-beam flag will make the compiler output Erlang code but not compile it to BEAM bytecode. This flag is invalid when compiling to JavaScript.

deps list

Print the names and versions of the all the dependencies of the package.

gleam deps list

deps download

Download the dependencies of the package. This is performed automatically by any other command that needs the dependencies, so typically you do not run this yourself.

gleam deps download

If the versions of the dependencies listed in gleam.toml have not been selected yet then this command will perform version resolution, and a manifest.toml file will be generated to lock the used versions.

deps outdated

Print the names, current versions, and latest available versions of all dependencies that are not at their latest version.

gleam deps outdated

deps update

Upgrade the dependencies to the newest available versions that are compatible with the requirements specified in gleam.toml.

gleam deps update

If you only wish to upgrade certain dependencies then their names can be given as arguments to this command.

gleam deps update gleam_stdlib lustre

This command will not change the requirements specified in gleam.toml. If you wish to change them you will need to edit that file.

deps tree

Print the names and versions of all dependencies in a tree-like format, showing which dependencies depend on which others. If a dependency A is depended on by multiple other dependencies then dependency A will be down in the tree multiple times.

gleam deps tree

The --package flag can be used to print the tree from a particular package, only shows its dependencies.

gleam deps tree --package pearl

The --invert flag can be used to show all the paths from a dependency package up to the root package. This is useful for understanding why a particular package and version is included in the project.

gleam deps tree --invert splitter

dev

Run the main function of the development module of the package, which is the module with the name of the package with _dev appended. For example, if the package is called wibble, then the module is called wibble_dev.

gleam dev

docs build

Build the documentation for the package, saving the HTML files to the local disc.

gleam docs build --open

If the --open flag is given then the index page of the generated documentation will be opened in the computer's default web browser.

docs publish

Build the documentation for the package and publish it to HexDocs for the latest version of the package.

gleam docs publish

This command will ask you to log-in with Hex.

docs remove

Remove the documentation from HexDocs for a specific package and version that has been published to Hex.

gleam docs remove --package wibble_package --version 1.0.0

This command will ask you to log-in with Hex.

This command can be run outside of a Gleam package.

export escript

This command builds the Gleam package into an escript.

An escript is a single-file bundle of an Erlang-based program, which can be run on any computer with a compatible version of Erlang installed on it. Escripts are most commonly used for command line programs as they can be easily shared, due to being a single file.

gleam export escript

export erlang-shipment

This command builds the Gleam package into a directory of compiled Erlang bytecode, configuration, and a start script. This is most suited for server deployment, desktop software, and other scenarios where a directory of files is not a problem for installation.

gleam export erlang-shipment

This is preferred over escripts as it can make use of the priv directories for packages, and in future will be easier to migrate to "OTP releases", which will replace Erlang shipments.

export hex-tarball

Build the tarball that would be send to the Hex package manager in order to publish the package. This may be useful for debugging or for auditing.

gleam export hex-tarball

export javascript-prelude

Print the JavaScript prelude module. This command is likely only useful for people using the gleam compile-package command.

gleam export javascript-prelude

export typescript-prelude

Print the TypeScript prelude module. This command is likely only useful for people using the gleam compile-package command.

gleam export typescript-prelude

export package-interface

Output a JSON file containing information about the code in the package.

gleam export package-interface --out ./wibble.json

Decoders for this data can be found in the gleam_package_interface package.

export package-information

Output a JSON file containing information about the package, including the contents of its gleam.toml file.

gleam export package-information --out ./wibble.json

fix

Run automatic fixes for problems with the code of the package. Historically this was used to help with grading code to new language versions before Gleam v1.0.0. Currently this code does nothing.

gleam fix

format

Run the Gleam code formatter, rewriting the code to use the canonical Gleam format.

gleam format

By default this command will format all Gleam files within the current directory that are not inside a Gleam build directory.

gleam format projects/wibble projects/wobble another_file.gleam

Paths can be given to the command to format specific files or directories.

gleam format --check

When the --check flag is given this command will check that the code has the correct format but will not reformat it. If any code is found to have the incorrect format then the command will return an error.

cat some_module.gleam | gleam format --stdin | cowsay

The --stdin flag can be used to read the Gleam source code from standard input. When given the formatted code will be printed to standard output, making it suitable for shell pipelines.

help

The help command can be used to view documentation for the command line, similar to this document. Put help after before the command you wish to know more about and it will print documentation for it.

gleam help build

Running this would show documentation for the gleam build command.

hex retire

Retire a published version of a package from Hex. The retired version is still available in the repository for projects that already depend on it, but they should upgrade to another version, and new packages should not use it.

gleam hex retire \
    --package wobble \
    --version 1.0.0 \
    --reason security \
    "The wobble.load function is vulnerable to..."

A detailed message should be given explaining the reason for the retirement. If you have a CVE number then include that in the message.

The --reason flag must be given one of other, invalid, security, deprecated, or renamed.

This command will ask you to log-in with Hex.

This command can be run outside of a Gleam package.

hex unretire

Restore a package version that has been previous retired.

gleam hex unretire --package wobble --version 1.0.0

This command will ask you to log-in with Hex.

This command can be run outside of a Gleam package.

hex revert

Revert a package release. This removes the version from Hex entirely; Projects that were already using that version will no longer be able to download it.

Releases can only be reverted within 24 hours since they were published.

gleam hex revert --package wobble --version 1.0.0

This command will ask you to log-in with Hex.

This command can be run outside of a Gleam package.

hex owner add

Add a Hex user account as an additional owner of a package you own, given them permission to manage the package.

gleam hex owner add --user their_username --level maintainer my_package

The --user flag can be given a Hex username or the email address of a Hex account.

The --level flag specified what permissions the new owner has over the package. - maintainer: Has every package permission EXCEPT the ability to change who owns the package. - full: Has every package permission including the ability to change who owns the package.

This command will ask you to log-in with Hex.

This command can be run outside of a Gleam package.

hex owner transfer

Transfer ownership of a package to another Hex user. This action is not reversible, and you will no longer have permissions to make changes to the package.

gleam hex owner transfer --package my_package --to their_username

The --to flag can be given a Hex username or the email address of a Hex account.

This command will ask you to log-in with Hex.

This command can be run outside of a Gleam package.

hex authenticate

Log-in with Hex, saving a token to disc using an encryption password of your choice. Any pre-existing token saved locally is revoked and replaced.

gleam hex authenticate

lsp

Run the Gleam language server. This command it run by code editors, you do not need to run this command yourself.

gleam lsp

new

Create a new Gleam package at a specified location.

gleam new wibble

wibble/
├── .github
│   └── workflows
│       └── test.yml
├── .gitignore
├── gleam.toml
├── README.md
├── src/
│   └── wibble.gleam
└── test/
    └── wibble_test.gleam

These are the directories and files that are created by the command by default. The exact output can be configured by giving addition flags to the command.

gleam new gleam-wibble --name wibble

If the name of the directory given is not a valid Gleam module name then the --name flag can be used to specify a valid name. In this example the package name is wibble and the directory is called gleam-wibble/.

If the --skip-github flag is given then the .github/ directory is not created.

If the --skip-git flag is given then the .github/ and .git/ directories are not created.

If the --template flag is given the argument javascript then the package is created with the target property in gleam.toml set to "javascript".

publish

Publish the package to the Hex package repository.

Only publish production-ready packages

The package repository is for high quality code for others to depend on. It is not a way to share prototypes, experiments, or work-in-progress versions.

If you have non-production-ready code that you wish to share with other then publish it to GitHub or similar, and have your users add it as a git dependency. If you are looking for feedback on your project ask for it on the Gleam discord server.

gleam publish

The --replace function can be used to replace an existing release with new code, so long as that release it not more than 1 hour old. This can be used to correct any mistakes when publishing.

remove

Remove one or more dependencies from the package.

gleam remove dependency_one dependency_two

run

Compile and run the code.

gleam run

By default the main function in the module that has the same name as the package is run.

gleam run --module other/module

The --module or -m flag can be used to specify another module to run.

gleam run --target erlang

The --target flag is used to pick which target to use. It has two possible values, erlang and javascript. If this flag is not given then the target value from gleam.toml is used, and if neither are present then the Erlang target is used.

gleam run --target javascript --runtime deno

The --runtime flag is used to pick which JavaScript runtime to use. It has three possible values, nodejs, deno and bun. If this flag is not given then the javascript.runtime value from gleam.toml is used, and if neither are present then NodeJS is used. This flag is only valid when using the JavaScript target.

The --no-print-progress flag disables the progress messages that Gleam prints during compilation.

shell

Compile the package and start and Erlang REPL with the package's code available.

gleam shell

This is an Erlang REPL, not a Gleam one, so Erlang syntax is used.

test

Run the main function of the test module of the package, which is the module with the name of the package with _test appended. For example, if the package is called wibble, then the module is called wibble_test.

gleam test

update

An alias for gleam deps update.