The Freerouting Command Line Interface (CLI) allows you to automate PCB routing tasks without using the graphical user interface (GUI). This is particularly useful for integrating Freerouting into scripts, build systems, or other software tools where automated routing is required.

This document provides detailed information on how to use Freerouting via the CLI, including available command-line options and how to adjust internal settings for advanced configurations.

To run Freerouting from the command line, use the following syntax:

java -jar freerouting-2.2.2.jar [options]

Replace freerouting-2.2.2.jar with the actual filename of the Freerouting JAR file you are using.

Below is a comprehensive list of command-line options available in Freerouting, organized by category.

• -de [design input file]
  Loads a design file at startup. The input can be:

  • Specctra board (.dsn)
  • Specctra session file (.ses - optional)
  • Freerouting design rules file (.rules - optional)

  The DSN file is mandatory, while the SES and RULES files are optional.
  They can be provided in any order, separately or appended by the + sign (e.g. -de myboard.dsn+myboard.ses+myboard.rules).

• -do [design output file]
  Saves the routing results when the routing is finished. The output can be:

  • Specctra board (.dsn)
  • Specctra session file (.ses)
  • Eagle session script file (.scr)

  The output format is determined by the file extension provided.

• -di [design input directory]
  Sets the default folder for the open design dialogs when using the GUI.

• -dr [design rules file]
  Reads design rules from a previously saved .rules file.

• -drc [design rules check json file]
  Writes the design rules check report in KiCad JSON DRC schema format.

• -mp [number of passes]
  Sets the upper limit for the number of autorouter passes to perform. More passes may result in better optimization but will take longer.

• -mt [number of threads]
  Sets the thread pool size for route optimization:

  • Default: One less than the number of logical processors on the system.
  • Set to 0 to disable route optimization.
  • Increasing the number may improve performance on multi-core systems.

• -oit [percentage]
  Specifies the optimizer improvement threshold per pass:

  • Default: 0.1%
  • The optimizer stops if the improvement falls below this threshold.
  • Setting -oit 0 continues optimization until manually stopped or no further improvements are possible.

• -inc [net class names]
  Lists net classes to ignore during autorouting:

  • Provide a comma-separated list (e.g., -inc GND,VCC).
  • The autorouter will not route nets belonging to these classes.

• -im
  Enables saving of intermediate steps in a version-specific binary format:

  • Allows resuming interrupted optimizations from the last checkpoint.
  • Disabled by default.

• -us [greedy | global | hybrid]
  Sets the board updating strategy for route optimization:

  • greedy (default): Accepts any immediate improvement.
  • global: Only accepts changes that result in a global optimum.
  • hybrid: Combines both strategies; requires -hr to specify the ratio.

• -hr [m:n]
  Specifies the hybrid ratio when using the hybrid update strategy:

  • Format: #_global_optimal_passes:#_prioritized_passes (e.g., 1:1).
  • Only effective with -us hybrid.

• -is [sequential | random | prioritized]
  Sets the item selection strategy for route optimization:

  • sequential: Processes items in order.
  • random: Processes items in a random order.
  • prioritized (default): Selects items based on calculated scores from previous rounds.

• -l [language code]
  Sets the language for the user interface:
  • Supported codes:
    • en: English
    • de: German
    • zh: Simplified Chinese
  • If unsupported, defaults to the system language or English.

• -host [host_name host_version]
  Specifies the name and version of the host application if Freerouting is run as an external library or plugin.

• --debug.enable_detailed_logging=[true|false] Enables detailed trace logging to the log file. Default is false.

  • Effect: Sets the file logging level to TRACE. Note that this can generate very large log files.

• --debug.single_step_execution=[true|false] Enables single-step execution mode. Default is false.

  • Effect: Shows "Play", "Pause", "Next", and "Previous" buttons in the toolbar. The autorouter will start valid pauses at breakpoints (e.g. trace insertion).

• --debug.trace_insertion_delay=[milliseconds] Adds a delay in milliseconds after each trace insertion or major routing step. Default is 0.

  • Effect: Slows down the routing process for visual debugging.

• --debug.filter_by_net=[net1,net2,...] Restricts debug actions (stepping, delays) to specific nets.

  • Format: Comma-separated list of net names or numbers (e.g. Net1,Net #2,3).
  • Effect: Other nets are routed at full speed.

• -dct [seconds]
  Sets the dialog confirmation timeout:

  • Specifies the number of seconds before dialogs proceed with the default action.
  • Default is 20 seconds.

• -da
  Disables the collection of anonymous analytics data.

• --logging.console.enabled=[true|false] Enables or disables console logging. Default is true.

• --logging.console.level=[level] Sets the console logging level.

  • Valid values: OFF, FATAL, ERROR, WARN, INFO (default), DEBUG, TRACE, ALL.

• --logging.file.enabled=[true|false] Enables or disables file logging. Default is true.

• --logging.file.level=[level] Sets the file logging level. Default is INFO.

• --logging.file.location=[directory] Defines the directory where freerouting.log is stored.

• -dl (Legacy) Disables file logging. Equivalent to --logging.file.enabled=false.

• -ll [level] (Legacy) Sets the console logging level. Equivalent to --logging.console.level=[level].

• --user_data_path=[directory] Defines the directory where configuration and log files are stored.

  • Purpose:
    • freerouting.log will be created in this directory.
    • freerouting.json (settings) will be read from this directory if it exists, or created there if it doesn't.
  • Format constraint: Must use the --user_data_path=path syntax with an equals sign.
  • If the directory does not exist when Freerouting starts, it is created automatically on the first write (e.g. when freerouting.json is saved for the first time). A warning is printed to stderr if the initial mkdirs() attempt fails; the path is still registered and the directory will be created later.
  • This option takes priority over the FREEROUTING__USER_DATA_PATH environment variable and over FREEROUTING__LOGGING__FILE__LOCATION.

• -help Displays help information and exits.

Freerouting allows you to fine-tune its internal settings beyond the standard command-line options. To modify these settings, use the double dash -- prefix followed by the setting name and its value.

Syntax:

java -jar freerouting-2.2.2.jar --setting_name=value

Examples:

• Disable the GUI:

  java -jar freerouting-2.2.2.jar --gui.enabled=false

• Adjust the via cost:

  java -jar freerouting-2.2.2.jar --router.via_costs=150

Settings whose value is a list (e.g. api_server.endpoints) accept a comma-separated string when set via CLI argument or environment variable. Whitespace around each comma is stripped automatically.

# Single endpoint
java -jar freerouting-2.2.2.jar --api_server-endpoints=http://0.0.0.0:37864

# Multiple endpoints (comma-separated)
java -jar freerouting-2.2.2.jar --api_server-endpoints=http://0.0.0.0:37864,http://127.0.0.1:37864

The equivalent environment-variable syntax is:

FREEROUTING__API_SERVER__ENDPOINTS=http://0.0.0.0:37864,http://127.0.0.1:37864

Note: Commas are the chosen delimiter because URL characters that would normally include a comma are percent-encoded by browsers/tools, so plain commas in the string unambiguously mark element boundaries.

Example — expose to all network interfaces without authentication (Docker or LAN):

java -jar freerouting-executable.jar \
  --gui.enabled=false \
  --api_server.enabled=true \
  --api_server.authentication.enabled=false \
  --api_server-endpoints=http://0.0.0.0:37864

For a complete self-hosting walkthrough — including Docker Compose, systemd, and platform-specific notes — see the Self-Hosting Guide.

Below are some common usage examples to help you get started.

Autoroute a design and save the results:

java -jar freerouting-2.2.2.jar -de MyBoard.dsn -do MyBoard.ses

• Loads MyBoard.dsn.
• Performs autorouting.
• Saves the routed design to MyBoard.ses.

Ignore the GND and VCC net classes during routing:

java -jar freerouting-2.2.2.jar -de MyBoard.dsn -do MyBoard.ses -inc GND,VCC

• Nets in the GND and VCC classes will not be routed.
• Useful when you plan to route these nets manually.

Limit the autorouter to 10 passes and use 4 threads:

java -jar freerouting-2.2.2.jar -de MyBoard.dsn -do MyBoard.ses -mp 10 -mt 4

• Sets a cap on routing time and resource usage.
• Adjust -mt based on your system's capabilities.

By leveraging Freerouting's CLI, you can integrate advanced PCB routing into your automated workflows, scripts, or applications. The flexibility of command-line options and internal settings allows for customized routing solutions tailored to your project's requirements.

For further customization and advanced configurations, refer to the Settings Documentation and other resources provided with Freerouting.