Command line tutorial
Some developers like using the command line extensively. Godot isdesigned to be friendly to them, so here are the steps for workingentirely from the command line. Given the engine relies on almost noexternal libraries, initialization times are pretty fast, making itsuitable for this workflow.
Note
On Windows and Linux, you can run a Godot binary in a terminal by specifyingits relative or absolute path.
On macOS, the process is different due to Godot being contained within an.app bundle (which is afolder, not a file). To run a Godot binaryfrom a terminal on macOS, you have tocd to the folder where the Godotapplication bundle is located, then runGodot.app/Contents/MacOS/Godotfollowed by any command line arguments. If you've renamed the applicationbundle fromGodot to another name, make sure to edit this command lineaccordingly.
Command line reference
Legend
Available in editor builds, debug export templates and release export templates.
Available in editor builds and debug export templates only.
Only available in editor builds.
Note that unknown command line arguments have no effect whatsoever. The enginewillnot warn you when using a command line argument that doesn't exist with agiven build type.
General options
Command | Description |
|
|
|
|
|
|
|
|
Run options
Command | Description |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Display options
Command | Description |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Debug options
Command | Description |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Standalone tools
Command | Description |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Path
It is recommended to place your Godot editor binary in yourPATH environmentvariable, so it can be executed easily from any place by typinggodot.You can do so on Linux by placing the Godot binary in/usr/local/bin andmaking sure it is calledgodot (case-sensitive).
To achieve this on Windows or macOS easily, you can install Godot usingScoop (on Windows) orHomebrew(on macOS). This will automatically make the copy of Godot installedavailable in thePATH:
# Add "Extras" bucketscoopbucketaddextras# Standard editor:scoopinstallgodot# Editor with C# support (will be available as `godot-mono` in `PATH`):scoopinstallgodot-mono
# Standard editor:brewinstallgodot# Editor with C# support (will be available as `godot-mono` in `PATH`):brewinstallgodot-mono
Setting the project path
Depending on where your Godot binary is located and what your currentworking directory is, you may need to set the path to your projectfor any of the following commands to work correctly.
When running the editor, this can be done by giving the path to theproject.godot fileof your project as either the first argument, like this:
godotpath_to_your_project/project.godot[other][commands][and][args]
For all commands, this can be done by using the--path argument:
godot--pathpath_to_your_project[other][commands][and][args]
For example, the full command for exporting your game (as explained below) might look like this:
godot--headless--pathpath_to_your_project--export-releasemy_export_preset_namegame.exe
When starting from a subdirectory of your project, use the--upwards argument for Godot toautomatically find theproject.godot file by recursively searching the parent directories.
For example, running a scene (as explained below) nested in a subdirectory might look like thiswhen your working directory is in the same path:
godot--upwardsnested_scene.tscn
Creating a project
Creating a project from the command line can be done by navigating theshell to the desired place and making aproject.godot file.
mkdirnewgamecdnewgametouchproject.godotThe project can now be opened with Godot.
Running the editor
Running the editor is done by executing Godot with the-e flag. Thismust be done from within the project directory or by setting the project path as explained above,otherwise the command is ignored and the Project Manager appears.
godot-e
When passing in the full path to theproject.godot file, the-e flag may be omitted.
If a scene has been created and saved, it can be edited later by runningthe same code with that scene as argument.
godot-escene.tscn
Erasing a scene
Godot is friends with your filesystem and will not create extra metadata files.Userm to erase a scene file. Make sure nothing references that scene.Otherwise, an error will be thrown upon opening the project.
rmscene.tscn
Running the game
To run the game, execute Godot within the project directory or with the project path as explained above.
godot
Note that passing in theproject.godot file will always run the editor instead of running the game.
When a specific scene needs to be tested, pass that scene to the command line.
godotscene.tscn
Debugging
Catching errors in the command line can be a difficult task because theyscroll quickly. For this, a command line debugger is provided by adding-d. It works for running either the game or a single scene.
godot-d
godot-dscene.tscn
Exporting
Exporting the project from the command line is also supported. This isespecially useful for continuous integration setups.
Note
Using the--headless command line argument isrequired on platformsthat do not have GPU access (such as continuous integration). On platformswith GPU access,--headless prevents a window from spawning while theproject is exporting.
# `godot` must be a Godot editor binary, not an export template.# Also, export templates must be installed for the editor# (or a valid custom export template must be defined in the export preset).godot--headless--export-release"Linux/X11"/var/builds/projectgodot--headless--export-releaseAndroid/var/builds/project.apk
The preset name must match the name of an export preset defined in theproject'sexport_presets.cfg file. If the preset name contains spaces orspecial characters (such as "Windows Desktop"), it must be surrounded with quotes.
To export a debug version of the game, use the--export-debug switch insteadof--export-release. Their parameters and usage are the same.
To export only a PCK file, use the--export-pack option followed by thepreset name and output path, with the file extension, instead of--export-release or--export-debug. The output path extension determinesthe package's format, either PCK or ZIP.
Warning
When specifying a relative path as the path for--export-release,--export-debugor--export-pack, the path will be relative to the directory containingtheproject.godot file,not relative to the current working directory.
Running a script
It is possible to run a.gd script from the command line.This feature is especially useful in large projects, e.g. for batchconversion of assets or custom import/export.
The script must inherit fromSceneTree orMainLoop.
Here is an examplesayhello.gd, showing how it works:
#!/usr/bin/env -S godot -sextendsSceneTreefunc_init():print("Hello!")quit()
And how to run it:
# Prints "Hello!" to standard output.godot-ssayhello.gdIf noproject.godot exists at the path, current path is assumed to be thecurrent working directory (unless--path is specified).
The script path will be interpreted as a resource path relative tothe project, hereres://sayhello.gd. You can also use an absolutefilesystem path instead, which is useful if the script is locatedoutside of the project directory.
The first line ofsayhello.gd above is commonly referred to asashebang. If the Godot binary is in yourPATH asgodot,it allows you to run the script as follows in modern Linuxdistributions, as well as macOS:
# Mark script as executable.chmod+xsayhello.gd# Prints "Hello!" to standard output../sayhello.gd
If the above doesn't work in your current version of Linux or macOS, you canalways have the shebang run Godot straight from where it is located as follows:
#!/usr/bin/godot -s