whale-town-front/.claude/skills/godot-cli-test-runner/references/godot-cli-commands.md

Godot CLI Commands Summary

This reference summarizes the provided godot --help output for fast command selection.

1. Core inspection

• Help: godot --help
• Version: godot --version
• Verbose logs: godot --verbose
• Quiet mode: godot --quiet

2. Project targeting and run mode

• Point to project directory: godot --path .
• Run specific scene: godot --path . --scene res://scenes/MainScene.tscn
• Headless mode: godot --headless --path . ...
• Quit quickly: godot --path . --quit
• Quit after N frames: godot --path . --quit-after 120

3. Script execution and tests

• Run script: godot --headless --path . --script tests/unit/test_xxx.gd
• Parse-only script check: godot --headless --path . --script tests/unit/test_xxx.gd --check-only
• Pass custom user args to script: godot --headless --path . --script tests/unit/test_runner.gd -- --case websocket
• Autoload-safe smoke test (preferred when test uses singleton globals): godot --headless --path . --scene res://scenes/MainScene.tscn --quit-after 120 --log-file .godot/smoke_main.log

4. Debug and diagnostics

• Local debugger: godot --debug --path .
• Remote debug: godot --remote-debug tcp://127.0.0.1:6007 --path .
• Print FPS: godot --path . --print-fps
• Log to file: godot --path . --log-file logs/godot.log
• Disable VSync for profiling: godot --path . --disable-vsync

5. Display and runtime controls

• Fullscreen: godot --path . --fullscreen
• Windowed: godot --path . --windowed
• Resolution: godot --path . --resolution 1920x1080
• Max FPS: godot --path . --max-fps 60
• Fixed FPS: godot --path . --fixed-fps 60
• Time scale: godot --path . --time-scale 0.5

6. Export operations (editor build only)

• Release export: godot --path . --export-release "Web" build/web/index.html
• Debug export: godot --path . --export-debug "Web" build/web/index.html
• Pack export: godot --path . --export-pack "Web" build/web/game.pck
• Check preset syntax only: godot --path . --export-debug "Web" --check-only

7. Common quick recipes

• Run a unit test script (isolated logic): godot --headless --path . --script tests/unit/test_websocket_close_code.gd --log-file .godot/test_websocket_close_code.log
• Validate script syntax without running: godot --headless --path . --script tests/unit/test_websocket_close_code.gd --check-only --log-file .godot/check_websocket.log
• Run game with verbose logs: godot --verbose --path . --log-file .godot/main_verbose.log
• Run scene and auto-exit after startup checks: godot --headless --path . --scene res://scenes/MainScene.tscn --quit-after 120 --log-file .godot/smoke_main.log

8. Windows explicit executable pattern

When godot is not in PATH, call the executable directly:

& "D:\technology\biancheng\Godot\Godot_v4.5.1-stable_win64.exe" --headless --path . --script tests/unit/test_websocket_close_code.gd

9. Notes for AI execution

• Prefer --headless for tests and scripts in terminal/CI.
• Always include --path . for reproducibility.
• Use --check-only for parse checks when execution is not needed.
• If a script depends on autoload singleton names from project.godot (SceneManager, LocationManager, EventSystem, etc.), validate in scene/project context before concluding regression.
• Prefer --log-file for reliable diagnostics and environment-specific logging issues.
• Add --verbose when failure context is insufficient.