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 a.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.
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
-h,--help
Display the list of command line options.
--version
Display the version string.
-v,--verbose
Use verbose stdout mode.
-q,--quiet
Quiet mode, silences stdout messages. Errors are still displayed.
--no-header
Do not print engine version and rendering method header on startup.
Run options
Command
Description
--,++
Separator for user-provided arguments. Following arguments are not used by the engine, but can be read fromOS.get_cmdline_user_args().
-e,--editor
Start the editor instead of running the scene.
-p,--project-manager
Start the Project Manager, even if a project is auto-detected.
--recovery-mode
"Start the editor in recovery mode, which disables features that can typically cause startup crashes, such as tool scripts, editor plugins,GDExtension addons, and others.
--debug-server<uri>
Start the editor debug server (<protocol>://<host/IP>[:<port>], e.g.tcp://127.0.0.1:6007)
--dap-port<port>
Use the specified port for the GDScript Debug Adapter Protocol. Recommended port range[1024,49151].
--lsp-port<port>
Use the specified port for the GDScript Language Server Protocol. Recommended port range[1024,49151].
--quit
Quit after the first iteration.
--quit-after
Quit after the given number of iterations. Set to 0 to disable.
-l,--language<locale>
Use a specific locale.<locale> follows the formatlanguage_Script_COUNTRY_VARIANT where language is a 2 or 3-letter language code inlowercase and the rest is optional. SeeLocale codes for more details.
--path<directory>
Path to a project (<directory> must contain a 'project.godot' file).
scene<path>
Path or UID of a scene in the project that should be started.
-u,--upwards
Scan folders upwards for 'project.godot' file.
--main-pack<file>
Path to a pack (.pck) file to load.
--render-thread<mode>
Render thread mode ('unsafe', 'safe', 'separate'). SeeThread Modelfor more details.
--remote-fs<address>
Remote filesystem (<host/IP>[:<port>] address).
--remote-fs-password<password>
Password for remote filesystem.
--audio-driver<driver>
Audio driver. Use--help first to display the list of available drivers.
--display-driver<driver>
Display driver (and rendering driver). Use--help first to display the list of available drivers.
--audio-output-latency <ms>
Override audio output latency in milliseconds (default is 15 ms). Lower values make sound playback more reactive but increase CPU usage, and mayresult in audio cracking if the CPU can't keep up
--rendering-method<renderer>
Renderer name. Requires driver support.
--rendering-driver<driver>
Rendering driver (depends on display driver). Use--help first to display the list of available drivers.
--gpu-index<device_index>
Use a specific GPU (run with--verbose to get available device list).
--text-driver<driver>
Text driver (Fonts, BiDi, shaping).
--tablet-driver<driver>
Pen tablet input driver.
--headless
Enable headless mode (--display-driverheadless--audio-driverDummy). Useful for servers and with--script.
--log-file
Write output/error log to the specified path instead of the default location defined by the project. <file> path should be absolute or relative tothe project directory.
--write-movie<file>
Run the engine in a way that a movie is written (usually with .avi or .png extension).--fixed-fps is forced when enabled, but can be used to change movie FPS.--disable-vsync can speed up movie writing but makes interaction more difficult.--quit-after can be used to specify the number of frames to write.
Abort on GPU errors (usually validation layer errors), may help see the problem if your system freezes.
--generate-spirv-debug-info
Generate SPIR-V debug information. This allows source-level shader debugging with RenderDoc.
--extra-gpu-memory-tracking
Enables additional memory tracking (see class reference forRenderingDevice.get_driver_and_device_memory_report() and linked methods). Currently only implemented forVulkan. Enabling this feature may cause crashes on some systems due to buggy drivers or bugs in the VulkanLoader. Seehttps://github.com/godotengine/godot/issues/95967
--accurate-breadcrumbs
Force barriers between breadcrumbs. Useful for narrowing down a command causing GPU resets. Currentlyonly implemented for Vulkan.
Scene tree runs in single-threaded mode. Sub-thread groups are disabled and run on the main thread.
--debug-collisions
Show collision shapes when running the scene.
--debug-paths
Show path lines when running the scene.
--debug-navigation
Show navigation polygons when running the scene.
--debug-avoidance
Show navigation avoidance debug visuals when running the scene.
--debug-stringnames
Print all StringName allocations to stdout when the engine quits.
--debug-canvas-item-redraw
Display a rectangle each time a canvas item requests a redraw (useful to troubleshoot low processormode).
--max-fps<fps>
Set a maximum number of frames per second rendered (can be used to limit power usage). A value of 0results in unlimited framerate.
--frame-delay<ms>
Simulate high CPU load (delay each frame by <ms> milliseconds). Do not use as a FPS limiter; use--max-fps instead.
--time-scale<scale>
Force time scale (higher values are faster, 1.0 is normal speed).
--disable-vsync
Forces disabling of vertical synchronization, even if enabled in the project settings.Does not override driver-level V-Sync enforcement.
--disable-render-loop
Disable render loop so rendering only occurs when called explicitly from script.
--disable-crash-handler
Disable crash handler when supported by the platform code.
--fixed-fps<fps>
Force a fixed number of frames per second. This setting disables real-time synchronization.
--delta-smoothing<enable>
Enable or disable frame delta smoothing ('enable', 'disable').
--print-fps
Print the frames per second to the stdout.
--editor-pseudolocalization
Enable pseudolocalization for the editor and the project manager.
Standalone tools
Command
Description
-s,--script<script>
Run a script.<script> must be a resource path relative to the project (myscript.gd will be interpreted asres://myscript.gd)or an absolute filesystem path (for example on WindowsC:/tmp/myscript.gd)
--main-loop<main_loop_name>
Run a MainLoop specified by its global class name.
--check-only
Only parse for errors and quit (use with--script).
--import
Starts the editor, waits for any resources to be imported, and then quits. Implies--editor and--quit.
--export-release<preset><path>
Export the project in release mode using the given preset and output path. The preset name should match one defined in 'export_presets.cfg'.<path> should be absolute or relative to the project directory, and include the filename for the binary (e.g. 'builds/game.exe'). The targetdirectory must exist.
--export-debug<preset><path>
Like--export-release, but use debug template. Implies--import.
--export-pack<preset><path>
Like--export-release, but only export the game pack for the given preset. The<path> extension determines whether it will be in PCKor ZIP format. Implies--import.
--export-patch<preset><path>
Export pack with changed files only. See --export-pack description for other considerations.
--patches<paths>
List of patches to use with --export-patch. The list is comma-separated.
--install-android-build-template
Install the Android build template. Used in conjunction with --export-release or --export-debug.
Show what elements will be renamed when converting project from Godot 3.x to Godot 4.x.
--doctool[<path>]
Dump the engine API reference to the given<path> in XML format, merging if existing files are found.
--no-docbase
Disallow dumping the base types (used with--doctool).
--gdscript-docs<path>
Rather than dumping the engine API, generate API reference from the inline documentation in the GDScript files found in <path>(used with--doctool).
--build-solutions
Build the scripting solutions (e.g. for C# projects). Implies--editor and requires a valid project to edit.
--dump-gdextension-interface
Generate GDExtension header file 'gdnative_interface.h' in the current folder. This file is the base file required to implement a GDExtension.
--dump-extension-api
Generate JSON dump of the Godot API for GDExtension bindings named 'extension_api.json' in the current folder.
--validate-extension-api<path>
Validate an extension API file dumped (with the option above) from a previous version of the engine to ensure API compatibility.If incompatibilities or errors are detected, the return code will be non-zero.
--benchmark
Benchmark the run time and print it to console.
--benchmark-file<path>
Benchmark the run time and save it to a given file in JSON format. The path should be absolute.
--test[--help]
Run unit tests. Use --test --help for more information.
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
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:
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:
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 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.
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.
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.
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:
# Prints "Hello!" to standard output.godot-ssayhello.gd
If 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:
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.