.. _doc_command_line_tutorial: Command line tutorial ===================== .. highlight:: shell Some developers like using the command line extensively. Godot is designed to be friendly to them, so here are the steps for working entirely from the command line. Given the engine relies on almost no external libraries, initialization times are pretty fast, making it suitable for this workflow. .. note:: On Windows and Linux, you can run a Godot binary in a terminal by specifying its relative or absolute path. On macOS, the process is different due to Godot being contained within an ``.app`` bundle (which is a *folder*, not a file). To run a Godot binary from a terminal on macOS, you have to ``cd`` to the folder where the Godot application bundle is located, then run ``Godot.app/Contents/MacOS/Godot`` followed by any command line arguments. If you've renamed the application bundle from ``Godot`` to another name, make sure to edit this command line accordingly. Command line reference ---------------------- .. |release| image:: img/template_release.svg .. |debug| image:: img/template_debug.svg .. |editor| image:: img/editor.svg **Legend** - |release| Available in editor builds, debug export templates and release export templates. - |debug| Available in editor builds and debug export templates only. - |editor| Only available in editor builds. Note that unknown command line arguments have no effect whatsoever. The engine will **not** warn you when using a command line argument that doesn't exist with a given build type. **General options** +----------------------------+-----------------------------------------------------------------------------+ | Command | Description | +----------------------------+-----------------------------------------------------------------------------+ | ``-h``, ``--help`` | |release| Display the list of command line options. | +----------------------------+-----------------------------------------------------------------------------+ | ``--version`` | |release| Display the version string. | +----------------------------+-----------------------------------------------------------------------------+ | ``-v``, ``--verbose`` | |release| Use verbose stdout mode. | +----------------------------+-----------------------------------------------------------------------------+ | ``-q``, ``--quiet`` | |release| Quiet mode, silences stdout messages. Errors are still displayed. | +----------------------------+-----------------------------------------------------------------------------+ **Run options** +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Command | Description | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--``, ``++`` | |release| Separator for user-provided arguments. Following arguments are not used by the engine, but can be read from ``OS.get_cmdline_user_args()``. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``-e``, ``--editor`` | |editor| Start the editor instead of running the scene. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``-p``, ``--project-manager`` | |editor| Start the Project Manager, even if a project is auto-detected. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--debug-server `` | |editor| Start the editor debug server (``://[:]``, e.g. ``tcp://127.0.0.1:6007``) | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--quit`` | |release| Quit after the first iteration. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--quit-after`` | |release| Quit after the given number of iterations. Set to 0 to disable. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``-l``, ``--language `` | |release| Use a specific locale. ```` follows the format ``language_Script_COUNTRY_VARIANT`` where language is a 2 or 3-letter language code in | | | lowercase and the rest is optional. See :ref:`doc_locales` for more details. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--path `` | |release| Path to a project (```` must contain a 'project.godot' file). | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``-u``, ``--upwards`` | |release| Scan folders upwards for 'project.godot' file. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--main-pack `` | |release| Path to a pack (.pck) file to load. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--render-thread `` | |release| Render thread mode ('unsafe', 'safe', 'separate'). See :ref:`Thread Model ` | | | for more details. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--remote-fs
`` | |release| Remote filesystem (``[:]`` address). | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--remote-fs-password `` | |release| Password for remote filesystem. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--audio-driver `` | |release| Audio driver. Use ``--help`` first to display the list of available drivers. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--display-driver `` | |release| Display driver (and rendering driver). Use ``--help`` first to display the list of available drivers. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--rendering-method `` | |release| Renderer name. Requires driver support. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--rendering-driver `` | |release| Rendering driver (depends on display driver). Use ``--help`` first to display the list of available drivers. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--gpu-index `` | |release| Use a specific GPU (run with ``--verbose`` to get available device list). | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--text-driver `` | |release| Text driver (Fonts, BiDi, shaping). | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--tablet-driver `` | |release| Pen tablet input driver. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--headless`` | |release| Enable headless mode (``--display-driver headless --audio-driver Dummy``). Useful for servers and with ``--script``. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--write-movie `` | |release| 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. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ **Display options** +------------------------------------+----------------------------------------------------------------------------+ | Command | Description | +------------------------------------+----------------------------------------------------------------------------+ | ``-f``, ``--fullscreen`` | |release| Request fullscreen mode. | +------------------------------------+----------------------------------------------------------------------------+ | ``-m``, ``--maximized`` | |release| Request a maximized window. | +------------------------------------+----------------------------------------------------------------------------+ | ``-w``, ``--windowed`` | |release| Request windowed mode. | +------------------------------------+----------------------------------------------------------------------------+ | ``-t``, ``--always-on-top`` | |release| Request an always-on-top window. | +------------------------------------+----------------------------------------------------------------------------+ | ``--resolution x`` | |release| Request window resolution. | +------------------------------------+----------------------------------------------------------------------------+ | ``--position ,`` | |release| Request window position. | +------------------------------------+----------------------------------------------------------------------------+ | ``--screen `` | |release| Request window screen. | +------------------------------------+----------------------------------------------------------------------------+ | ``--single-window`` | |release| Use a single window (no separate subwindows). | +------------------------------------+----------------------------------------------------------------------------+ | ``--xr-mode `` | |release| Select XR mode ('default', 'off', 'on'). | +------------------------------------+----------------------------------------------------------------------------+ **Debug options** +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | Command | Description | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``-d``, ``--debug`` | |release| Debug (local stdout debugger). | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``-b``, ``--breakpoints`` | |release| Breakpoint list as source::line comma-separated pairs, no spaces (use ``%20`` instead). | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--profiling`` | |release| Enable profiling in the script debugger. | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--gpu-profile`` | |release| Show a GPU profile of the tasks that took the most time during frame rendering. | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--gpu-validation`` | |release| Enable graphics API :ref:`validation layers ` for debugging. | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--gpu-abort`` | |debug| Abort on GPU errors (usually validation layer errors), may help see the problem if your system freezes. | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--remote-debug `` | |release| Remote debug (``://[:]``, e.g. ``tcp://127.0.0.1:6007``). | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--single-threaded-scene`` | |release| Scene tree runs in single-threaded mode. Sub-thread groups are disabled and run on the main thread. | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--debug-collisions`` | |debug| Show collision shapes when running the scene. | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--debug-paths`` | |debug| Show path lines when running the scene. | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--debug-navigation`` | |debug| Show navigation polygons when running the scene. | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--debug-avoidance`` | |debug| Show navigation avoidance debug visuals when running the scene. | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--debug-stringnames`` | |debug| Print all StringName allocations to stdout when the engine quits. | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--frame-delay `` | |release| Simulate high CPU load (delay each frame by milliseconds). | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--time-scale `` | |release| Force time scale (higher values are faster, 1.0 is normal speed). | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--disable-vsync`` | |release| Forces disabling of vertical synchronization, even if enabled in the project settings. | | | Does not override driver-level V-Sync enforcement. | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--disable-render-loop`` | |release| Disable render loop so rendering only occurs when called explicitly from script. | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--disable-crash-handler`` | |release| Disable crash handler when supported by the platform code. | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--fixed-fps `` | |release| Force a fixed number of frames per second. This setting disables real-time synchronization. | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--delta-smoothing `` | |release| Enable or disable frame delta smoothing ('enable', 'disable'). | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ | ``--print-fps`` | |release| Print the frames per second to the stdout. | +--------------------------------+-----------------------------------------------------------------------------------------------------------------+ **Standalone tools** +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ | Command | Description | +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``-s``, ``--script