Command Line and Headless

FlatCAM Evo starts from a terminal with options and file names. The headless mode runs Tcl scripts with no window, for automation on a server or in a build step.

Where to find it

• Start the program from a terminal: python flatcam.py [OPTION]... [FILE]...
• On Windows, the packaged program is FlatCAM.exe. It takes the same options.
• The man page is flatcam-evo.1 in the program folder. On Linux, install it to a man folder to read it with man flatcam-evo.
• Help text: flatcam.py -h.

Quick start

1. Open a terminal in the program folder.
2. Start a script without a window: python flatcam.py --headless --shellfile=my_job.tcl
3. Check the exit code. 0 means done. Run echo $? on Linux or echo %ERRORLEVEL% on Windows.

Parameters

Options

Option	Description	Default
FILE	Opens the file at startup. A .FlatPrj file opens as a project. A script runs. A Gerber, Excellon or G-code file opens by its extension. The file name must exist, or the program stops with an error. Quote a name that has spaces.	—
--shellfile=SCRIPT	Runs the Tcl script file after the program starts. The file must exist and be readable, or the program stops with exit code 2.	—
--shellvar=VALUE1,VALUE2,...	Sets the Tcl variables shellvar_0, shellvar_1, and so on, with these values. Each value is read as a Python literal when possible, for example a number or a list. Other values stay as text. Backslashes in Windows paths become forward slashes.	—
--command=COMMANDS	Runs the Tcl commands. Separate the commands with semicolons. Quote the commands to protect them from the system shell.	—
--headless	Runs without a window or an OpenGL canvas. Without --shellfile or --command, the Tcl commands are read from standard input.	Off
-h	Prints the help text and exits.	—

Without --headless, the options open the program with a window. The script or the commands run after the window opens. The Tcl shell dock opens for --command.

Environment variable

Variable	Description	Default
FLATCAM_DATA_PATH	The folder for the application data: the preferences, the Tools Database, the recent files lists, the log file, and the user preprocessors.	~/.FlatCAM on Linux and macOS. On Windows, %APPDATA%\FlatCAM.

Exit codes (headless mode)

Code	Meaning
0	The run is done.
1	A Tcl command failed.
2	The command line is not valid, or the --shellfile is not readable.
N	The Tcl command exit N sets the code to N.

Advanced

• Headless mode. Headless mode runs no window, no tray icon, and no update check. The order of the work is: --shellvar, then --shellfile, then --command. Without --shellfile and --command, the Tcl commands are read from standard input one line at a time.
• Files in headless mode. The FILE arguments do not open in headless mode. Use --shellfile or --command to open files with Tcl commands.
• Error messages. In headless mode, a Tcl error writes an ERROR Report with the script name and the Tcl error details to standard error.
• Machine safety. On a critical error in headless mode, the program stops the connected machines before it ends. See GCode Sender.
• Multiprocessing. The program starts worker processes. The option --multiprocessing-fork is used by these workers. Do not use it by hand.
• Tcl commands. The Tcl commands of the scripts are described in Tcl Command Reference. The Tcl scripting guide is Tcl Scripting.

See also

• Tcl Scripting: writing the scripts that run in headless mode.
• Tcl Command Reference: the commands that a script can run.
• Projects: opening and saving a .FlatPrj file.
• Importing Files: the file types that open at startup.
• FAQ and Troubleshooting: startup problems.