FreeCAD Command Line Arguments Guide

FreeCAD offers a variety of command-line arguments that allow users and developers to customize startup behavior, run automated background tasks, diagnose bugs, and execute Python scripts without loading the graphical user interface. By executing FreeCAD from a terminal or command prompt, you can bypass default settings, isolate add-on issues, and streamline automated CAD workflows.

Basic Information Options

  • -h or --help: Displays a summary of all supported command-line options and terminates the application immediately.
  • -v or --version: Outputs the installed version of FreeCAD along with platform build information, then exits.

Running Modes and GUI Control

  • -c or --console: Launches FreeCAD in pure console mode. This suppresses the graphical user interface (GUI) and launches an interactive Python shell with the FreeCAD base modules pre-loaded, which is ideal for headless servers or automated script processing.
  • --safe-mode: Starts FreeCAD with all third-party add-ons, workbenches, and custom macros disabled. This helps isolate whether a crash or bug is caused by core FreeCAD code or a community-installed extension.

Configuration and Logging

  • --user-cfg <filename>: Specifies an alternative file path to load and save user configuration settings, overriding the default user.cfg location.
  • --system-cfg <filename>: Loads an alternative system configuration file instead of the default system.cfg.
  • -d or --write-log: Directs FreeCAD to output runtime diagnostic logs to a file named FreeCAD.log in the user directory.
  • --log-file <filename>: Enables logging and writes the diagnostic output directly to the specified file path.
  • --verbose: Increases the detail of log messages printed to the console or log file, useful for troubleshooting startup issues and module loading errors.

Script Execution and File Handling

  • [filename ...]: Any file paths supplied without specific flags will be loaded automatically on launch. If you provide a .fcstd or other supported 3D format file, FreeCAD opens it in a new document tab. If you supply a .py script, FreeCAD executes the script immediately upon startup.
  • --response-file <filename>: Allows you to pass a text file containing multiple command-line arguments, which is useful when handling complex batch execution parameters.