godot

Run the Godot game engine

TLDR

Run a project if the current directory contains a project.godot file, otherwise open the project manager

$ godot

Edit a project (the current directory must contain a project.godot file)

$ godot [[-e|--editor]]

Open the project manager even if the current directory contains a project.godot file

$ godot [[-p|--project-manager]]

Export a project for release using a given export preset (the preset must be defined in the project)

$ godot --export-release [preset] [output_path]

Execute a standalone GDScript file (the script must inherit from SceneTree or MainLoop)

$ godot [[-s|--script]] [script.gd]

SYNOPSIS

godot [options] [[path/to/]project.godot]

PARAMETERS

--help, -h
Display command-line help and exit

--version, -v
Display engine version and exit

--path

    Path to project directory or PCK file

--main-pack
    Main PCK file for exported projects

--headless
    Run without window or audio drivers

--no-window
    Disable window creation (headless)

--windowed
    Force windowed mode

--position ,
    Window startup position

--resolution x
    Window startup size

--fullscreen
    Start in fullscreen

--maximize
    Maximize window on startup

--always-on-top
    Keep window always on top

--fps
    Limit maximum frames per second

--renderer
    Renderer backend (e.g., 'gl', 'vulkan')

--audio-driver
    Audio driver (e.g., 'alsa', 'pulseaudio')

--quit
    Quit after project loading

--script
    Run a GDScript file

--export-release []
    Export project using release preset

--export-pack []
    Export project as PCK using preset

--doctool
    Generate project documentation

--verbose
    Verbose stdout output

--debug
    Enable debug features

--threads
    Set rendering threads count

DESCRIPTION

The godot command is the primary entry point for the Godot Engine, a free, open-source, cross-platform 2D and 3D game engine. It launches the Godot editor, runs exported game projects, executes GDScript files, performs project exports for various platforms, generates documentation, and supports headless operation for CI/CD pipelines or servers.

Usage typically involves specifying a project path (e.g., project.godot) or PCK file. Options allow customization of rendering backends (Vulkan, OpenGL), window properties, audio drivers, performance settings, and debugging features. Headless mode (--headless) is ideal for automated builds without a display. Export commands like --export-release produce platform-specific binaries or templates.

Godot's CLI excels in automation, enabling developers to script builds, test scenes, or profile performance from terminals. It's lightweight, with no external dependencies beyond the engine binary. Always check godot --help for version-specific options, as they evolve with releases.

CAVEATS

Options vary by Godot version (e.g., 3.x vs 4.x); requires installed Godot binary. Headless mode needs compatible drivers. Exports require templates downloaded via editor. Not a standard POSIX tool; install via package manager, Steam, or download from godotengine.org.

COMMON EXAMPLES

godot --headless --export-release "Linux/X11" game > /dev/null
Launch editor: godot myproject
Run script: godot --headless --script test.gd

DOCUMENTATION

Full options: godot --help. Online docs at docs.godotengine.org under 'Command line tutorial'.

HISTORY

Godot Engine originated in 2007 as an internal tool by Okam Studio, released open-source in 2014 by Juan Linietsky and Ariel Manzur. CLI support expanded in 2.x (2016), with major overhauls in 3.0 (2018, Vulkan/GL3) and 4.0 (2023, GDExtension, better exports). Usage grew with 1M+ downloads by 2020, popular for indie games.