Gleam コマンドラインリファレンス

原文: The Gleam command line reference ── © Louis Pilfold and the Gleam contributors, Apache-2.0。日本語訳 © 2026 Canonical。

Gleam のコマンドラインは、Gleam プロジェクトを操作するための主な手段です。

ほとんどのコマンドは Gleam パッケージ内、つまり gleam.toml ファイルと Gleam のコードが入った src ディレクトリを含むディレクトリ内で実行する必要があります。

add

パッケージに新しい依存を追加します。

そのパッケージと互換性のある最新バージョンが選択され、次に gleam.toml がそのバージョン以上を要求するように更新されます。この際、将来のパッチ更新やマイナー更新を許容する範囲が指定されます。

パッケージ「wibble」を追加します:

gleam add wibble

パッケージ「wibble」を、バージョン >= v2.0.0 かつ < v3.0.0 を要求するように追加します:

gleam add wibble@2

パッケージ「wibble」を、バージョン >= v2.5.1 かつ < v3.0.0 を要求するように追加します:

gleam add wibble@2.5.1

複数のパッケージを追加します:

gleam add wibble@2 warble@1

パッケージを開発時のみ利用する依存として追加します:

gleam add --dev wibble

パッケージの依存関係をさらに細かく制御したい場合は、gleam.toml を直接編集することもできます。その書式についてのドキュメントは、gleam help deps を実行して参照してください。

build

Gleam パッケージをコンパイルします。依存パッケージは必要に応じてダウンロードされ、コンパイルされます。パッケージがすでにコンパイルされている場合は、変更があった Gleam モジュールだけがコンパイルされます。

gleam build --target javascript

--target フラグは、どのコンパイルターゲットを使用するかを選択するために使います。指定できる値は erlang と javascript の 2 つです。このフラグが指定されなかった場合は gleam.toml の target の値が使われ、どちらも存在しない場合は Erlang ターゲットが使われます。

gleam build --warnings-as-errors

--warnings-as-errors フラグを指定した場合、コンパイル中に警告が 1 つでも出るとビルドは失敗とみなされ、ゼロ以外の終了コードが返されます。これは CI で実行する際に便利で、変更を main ブランチにマージする前にすべての警告が修正されていることを確認できます。

gleam build --no-print-progress

このフラグを指定すると、コンパイル中に Gleam が表示する進捗メッセージが無効になります。

check

プロジェクトを解析してエラーを探します。このコマンドは gleam build と似ていますが、型検査の後にコンパイルが停止し、最適化とコード生成が省かれる点が異なります。開発中に、コードを書きながらそれが妥当かどうかを素早く確認するのに便利です。

gleam check --target javascript

clean

ビルドディレクトリとすべてのビルド生成物を削除します。

gleam clean

compile-package

このコマンドは低レベルなコンパイル API であり、直接使用する人はごく少数です。最もよく使われるのは、他のビルドツールに Gleam 対応を追加する場合です。

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

--target フラグは、どのコンパイルターゲットを使用するかを選択するために使います。指定できる値は erlang と javascript の 2 つです。

--package フラグは、コンパイル対象の Gleam パッケージへのパスを指定します。

--out フラグは、パッケージのコンパイル結果を出力するパスを指定します。

--lib フラグは、コンパイル対象パッケージが依存しているコンパイル済みのパッケージを、コンパイラが見つけるためのパスを指定します。これらは同じバージョンの Gleam を使用してコンパイルされている必要があります。

--javascript-prelude フラグは、JavaScript の prelude モジュールへのパスを、out ディレクトリからの相対パスで指定します。JavaScript にコンパイルする際には必須です。

--no-beam フラグを指定すると、コンパイラは BEAM バイトコードファイルではなく Erlang ソースファイルを生成します。これを指定した場合、コンパイラにはどの非 Gleam の BEAM モジュールを含めるべきかを知る方法がないため、Erlang の .app ファイルは生成されません。このフラグは JavaScript にコンパイルする際には使用できません。

--no-dev フラグを指定すると、コンパイラは開発用のコードを飛ばします。つまり dev/ と test/ のディレクトリを飛ばし、Erlang にコンパイルする場合は .app ファイルに dev_dependencies を含めません。

deps list

パッケージが依存しているすべてのパッケージの名前とバージョンを表示します。

gleam deps list

deps download

パッケージの依存をダウンロードします。これは依存を必要とする他のあらゆるコマンドが自動的に行うため、通常は直接実行することはありません。

gleam deps download

gleam.toml に記載された依存パッケージのバージョンがまだ確定していない場合、このコマンドはバージョン解決を行い、使用するバージョンを固定するための manifest.toml ファイルを生成します。

deps outdated

最新バージョンになっていないすべての依存パッケージについて、名前、現在のバージョン、および利用可能な最新バージョンを表示します。

gleam deps outdated

deps update

gleam.toml で指定された要件を満たす範囲で、依存パッケージを利用可能な最新バージョンに更新します。

gleam deps update

特定の依存パッケージだけを更新したい場合は、コマンドの引数としてその名前を指定できます。

gleam deps update gleam_stdlib lustre

このコマンドは gleam.toml で指定された要件自体は変更しません。要件を変更したい場合は、ファイルを直接編集する必要があります。

deps tree

すべての依存パッケージの名前とバージョンをツリー形式で表示し、どのパッケージがどのパッケージに依存しているかを示します。あるパッケージ A が複数の他のパッケージから依存されている場合、A はツリー内に複数回表示されます。

gleam deps tree

--package フラグを使うと、特定のパッケージを起点にしてツリーを表示し、そのパッケージの依存関係だけを確認できます。

gleam deps tree --package pearl

--invert フラグを使うと、特定の依存パッケージからルートパッケージに至るまでのすべての経路を表示できます。これは、特定のパッケージやバージョンがなぜプロジェクトに含まれているのかを理解するのに便利です。

gleam deps tree --invert splitter

dev

パッケージの開発用モジュールにある main 関数を実行します。開発用モジュールとは、パッケージ名に _dev を付けた名前のモジュールのことです。たとえばパッケージ名が wibble なら、モジュール名は wibble_dev になります。

gleam dev

docs build

パッケージのドキュメントをビルドし、HTML ファイルとしてローカルのディスクに保存します。

gleam docs build --open

--open フラグを指定すると、生成されたドキュメントのインデックスページがコンピュータのデフォルト Web ブラウザで開かれます。

docs publish

パッケージのドキュメントをビルドし、そのパッケージの最新バージョンとして HexDocs に公開します。

gleam docs publish

このコマンドを実行すると、Hex へのログインが求められます。

docs remove

Hex に公開済みの特定のパッケージとバージョンについて、HexDocs からドキュメントを削除します。

gleam docs remove --package wibble_package --version 1.0.0

このコマンドを実行すると、Hex へのログインが求められます。

このコマンドは Gleam パッケージ以外のディレクトリからでも実行できます。

export escript

Gleam パッケージを escript としてビルドします。

escript とは Erlang ベースのプログラムを 1 つのファイルにまとめたもので、互換性のあるバージョンの Erlang がインストールされているコンピュータならどこでも実行できます。1 つのファイルで簡単に共有できるため、コマンドラインプログラムで最もよく使われます。

gleam export escript

export erlang-shipment

Gleam パッケージを、コンパイル済みの Erlang バイトコード、設定ファイル、および起動スクリプトを含むディレクトリとしてビルドします。これはサーバーへのデプロイやデスクトップソフトウェアなど、ファイルのディレクトリをそのまま配置しても問題にならない場面に最も適しています。

gleam export erlang-shipment

この形式は、パッケージの priv ディレクトリを利用できるため escript よりも好まれ、将来的に Erlang shipment に代わる「OTP リリース」へ移行しやすくなるという利点もあります。

export hex-tarball

パッケージを公開する際に Hex パッケージマネージャへ送信される tarball をビルドします。これはデバッグや監査に役立つことがあります。

gleam export hex-tarball

export javascript-prelude

JavaScript の prelude モジュールを表示します。このコマンドはおそらく、gleam compile-package コマンドを使用する人にしか役立ちません。

gleam export javascript-prelude

export typescript-prelude

TypeScript の prelude モジュールを表示します。このコマンドはおそらく、gleam compile-package コマンドを使用する人にしか役立ちません。

gleam export typescript-prelude

export package-interface

パッケージ内のコードに関する情報を含む JSON ファイルを出力します。

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

このデータのデコーダは gleam_package_interface パッケージで提供されています。

export package-information

パッケージに関する情報を、gleam.toml ファイルの内容も含めて JSON ファイルとして出力します。

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

fix

パッケージのコードに存在する問題に対して自動修正を実行します。以前は Gleam v1.0.0 より前に、コードを新しい言語バージョンへ移行するのを支援するために使われていました。現在、このコマンドは何もしません。

gleam fix

format

Gleam のコードフォーマッタを実行し、コードを Gleam の標準的な書式に書き換えます。

gleam format

デフォルトでは、カレントディレクトリ内にある Gleam ファイルのうち、Gleam のビルドディレクトリに含まれないものをすべてフォーマットします。

gleam format projects/wibble projects/wobble another_file.gleam

特定のファイルやディレクトリをフォーマットするために、コマンドの引数としてパスを指定することもできます。

gleam format --check

--check フラグを指定すると、コードが正しい書式になっているかを確認するだけで、実際の書き換えは行いません。書式が正しくないコードが見つかった場合、コマンドはエラーを返します。

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

--stdin フラグを使うと、Gleam のソースコードを標準入力から読み込めます。このフラグを指定すると、フォーマットされたコードは標準出力に出力されるため、シェルのパイプラインに組み込むのに適しています。

help

help コマンドを使うと、このドキュメントと同じようなコマンドラインに関する説明を閲覧できます。さらに詳しく知りたいコマンドの前に help を付けると、そのコマンドのドキュメントが表示されます。

gleam help build

これを実行すると、gleam build コマンドのドキュメントが表示されます。

hex retire

Hex に公開済みのパッケージのバージョンを retire(引退)させます。retire されたバージョンは、すでにそれに依存しているプロジェクトのためにリポジトリ上で引き続き利用できますが、それらのプロジェクトは別のバージョンへ更新すべきであり、新しいパッケージでそれを使用するべきではありません。

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

retire させる理由を説明する詳しいメッセージを記載するべきです。CVE 番号がある場合は、それをメッセージに含めてください。

--reason フラグには other、invalid、security、deprecated、renamed のいずれかを指定する必要があります。

このコマンドを実行すると、Hex へのログインが求められます。

このコマンドは Gleam パッケージ以外のディレクトリからでも実行できます。

hex unretire

以前 retire されたパッケージのバージョンを元に戻します。

gleam hex unretire --package wobble --version 1.0.0

このコマンドを実行すると、Hex へのログインが求められます。

このコマンドは Gleam パッケージ以外のディレクトリからでも実行できます。

hex revert

パッケージのリリースを取り消します。これにより、そのバージョンは Hex から完全に削除されます。すでにそのバージョンを使用していたプロジェクトは、以後それをダウンロードできなくなります。

リリースを取り消せるのは、公開から 24 時間以内に限られます。

gleam hex revert --package wobble --version 1.0.0

このコマンドを実行すると、Hex へのログインが求められます。

このコマンドは Gleam パッケージ以外のディレクトリからでも実行できます。

hex owner add

自分が所有するパッケージの追加の所有者として Hex ユーザーを追加し、そのパッケージを管理する権限を付与します。

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

--user フラグには、Hex のユーザー名または Hex アカウントのメールアドレスを指定できます。

--level フラグは、新しい所有者がそのパッケージに対してどのような権限を持つかを指定します。

maintainer: パッケージの所有者を変更する権限を除く、すべての権限を持ちます。
full: パッケージの所有者を変更する権限を含め、すべての権限を持ちます。

このコマンドを実行すると、Hex へのログインが求められます。

このコマンドは Gleam パッケージ以外のディレクトリからでも実行できます。

hex owner transfer

パッケージの所有権を別の Hex ユーザーに移譲します。この操作は取り消すことができず、あなたはそのパッケージに変更を加える権限を失います。

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

--to フラグには、Hex のユーザー名または Hex アカウントのメールアドレスを指定できます。

このコマンドを実行すると、Hex へのログインが求められます。

このコマンドは Gleam パッケージ以外のディレクトリからでも実行できます。

hex authenticate

Hex にログインし、自分で選んだ暗号化パスワードを使用してトークンをディスクに保存します。ローカルに保存されている既存のトークンは無効化され、新しいものに置き換えられます。

gleam hex authenticate

lsp

Gleam の言語サーバを実行します。このコマンドはコードエディタが実行するものであり、直接実行する必要はありません。

gleam lsp

new

指定した場所に新しい Gleam パッケージを作成します。

gleam new wibble

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

これらは、このコマンドがデフォルトで作成するディレクトリとファイルです。コマンドに追加のフラグを指定することで、出力内容を設定できます。

gleam new gleam-wibble --name wibble

指定したディレクトリ名が Gleam のモジュール名として不適切な場合、--name フラグを使って適切な名前を指定できます。この例では、パッケージ名は wibble であり、ディレクトリ名は gleam-wibble/ になります。

--skip-github フラグを指定すると、.github/ ディレクトリは作成されません。

--skip-git フラグを指定すると、.github/ ディレクトリと .git/ ディレクトリは作成されません。

--template フラグに引数 javascript を指定すると、gleam.toml の target プロパティが "javascript" に設定された状態でパッケージが作成されます。

publish

パッケージを Hex パッケージリポジトリに公開します。

注意
本番で使える品質のパッケージだけを公開してください
パッケージリポジトリは、他の人が依存するための高品質なコードを提供する場所です。プロトタイプや実験的なコード、または作成途中のバージョンを共有するための手段ではありません。
本番レベルの品質に達していないコードを他の人と共有したい場合は、GitHub などに公開し、利用者にはそれを git 依存として追加してもらってください。自分のプロジェクトに対するフィードバックが欲しい場合は、Gleam の Discord サーバーで質問してください。

gleam publish

--replace フラグを使うと、既存のリリースを新しいコードで置き換えることができます。ただし、そのリリースが公開から 1 時間以内の場合に限られます。これは公開時のミスを修正するために使用できます。

remove

パッケージから 1 つ以上の依存を削除します。

gleam remove dependency_one dependency_two

run

コードをコンパイルして実行します。

gleam run

デフォルトでは、パッケージと同じ名前を持つモジュールの main 関数が実行されます。

gleam run --module other/module

--module または -m フラグを使うと、実行するモジュールを指定できます。

gleam run --target erlang

--target フラグは、どのターゲットを使用するかを選択するために使います。指定できる値は erlang と javascript の 2 つです。このフラグが指定されなかった場合は gleam.toml の target の値が使われ、どちらも存在しない場合は Erlang ターゲットが使われます。

gleam run --target javascript --runtime deno

--runtime フラグは、どの JavaScript ランタイムを使用するかを選択するために使います。指定できる値は nodejs、deno、bun の 3 つです。このフラグが指定されなかった場合は gleam.toml の javascript.runtime の値が使われ、どちらも存在しない場合は NodeJS が使われます。このフラグは JavaScript ターゲットを使用する場合にのみ有効です。

--no-print-progress フラグは、コンパイル中に Gleam が表示する進捗メッセージを無効にします。

shell

パッケージをコンパイルし、パッケージのコードが使える状態で Erlang の REPL を起動します。

gleam shell

これは Gleam の REPL ではなく Erlang の REPL であるため、Erlang の構文を使用します。

test

パッケージのテストモジュールにある main 関数を実行します。テストモジュールとは、パッケージ名に _test を付けた名前のモジュールのことです。たとえばパッケージ名が wibble なら、モジュール名は wibble_test になります。

gleam test

update

gleam deps update の別名です。