Skip to main content
Version: 20

Command Line Interface

You can use the macOS Terminal or the Windows console to drive your 4D applications (4D, 4D Server, merged application, and tool4d) using command lines. More particularly, this functionality allows you to:

  • launch a database remotely, which can be especially useful for administering Web servers.
  • run automatic tests for your applications.

Basic information​

You can execute command lines for 4D applications using the macOS Terminal or the Windows Console.

  • Under macOS, you should use the open command.
  • Under Windows, you can just pass the arguments directly.

Under macOS, you can pass the arguments directly by going to the folder where the application is found inside the package (Contents/MacOS path), which allows to address the stderr stream. For example, if the 4D package is located in the MyFolder folder, you must write the command line as follows: /MyFolder/4D.app/Contents/MacOS/4D. However, we recommend that you use the open command whenever you do not need to access the stderr stream.

Launch a 4D application​

Here is a description of command lines and arguments supported to launch 4D applications.

Syntax:

<applicationPath> [--version] [--help] [--project] [<projectPath | packagePath | 4dlinkPath> [--data <dataPath>]]
[--opening-mode interpreted | compiled] [--create-data] [--user-param <user string>] [--headless] [--dataless]  
[--webadmin-settings-file] [--webadmin-access-key] [--webadmin-auto-start] [--webadmin-store-settings]  
[--utility] [--skip-onstartup] [--startup-method <methodName string>]
ArgumentValueDescription
applicationPathPath of 4D, 4D Server, merged application, or tool4dLaunches the application.
If not headless: identical to double-clicking the application; when called without structure file argument, the application is executed and the 'select database' dialog box appears.
--versionDisplays application version and exits
--helpDisplays help and exits. Alternate arguments: -?, -h
--projectprojectPath | packagePath | 4dlinkPathProject file to open with the current data file. No dialog box appears.
--datadataPathData file to open with the designated project file. If not specified, the last opened data file is used.
--opening-modeinterpreted | compiledRequests database to open in interpreted or compiled mode. No error is thrown if the requested mode is unavailable.
--create-dataAutomatically creates a new data file if no valid data file is found. No dialog box appears. 4D uses the file name passed in the "--data" argument if any (generates an error if a file with the same name already exists).
--user-paramCustom user stringA string that will be available within the application through the Get database parameter command (the string must not start with a "-" character, which is reserved).
--headlessLaunches the 4D, 4D Server or merged application without interface (headless mode). In this mode:
  • The Design mode is not available, database starts in Application mode
  • No toolbar, menu bar, MDI window or splash screen is displayed
  • No icon is displayed in the dock or task bar
  • The opened database is not registered in the "Recent databases" menu
  • The diagnostic log is automatically started (see SET DATABASE PARAMETER, selector 79)
  • Every call to a dialog box is intercepted and an automatic response it provided (e.g. OK for the ALERT command, Abort for an error dialog...). All intercepted commands(*) are logged in the diagnostic log.

    • For maintenance needs, you can send any text to standard output streams using the LOG EVENT command. Note that headless 4D applications can only be closed by a call to QUIT 4D or using the OS task manager.
    --datalessLaunches 4D, 4D Server, merged application or tool4d in dataless mode. Dataless mode is useful when 4D runs tasks with no need for data (project compilation for example). In this mode:
  • No file containing data is opened, even if specified in the command line or the .4DLink file, or when using the CREATE DATA FILE and OPEN DATA FILE commands.
  • Commands that manipulate data will throw an error. For example, CREATE RECORD throws “no table to apply the command to”.

    • Note:
  • If passed in the command line, dataless mode applies to all databases opened in 4D, as long as the application is not closed.
  • If passed using the .4DLink file, dataless mode only applies to the database specified in the .4DLink file. For more information on .4DLink files, see Project opening shortcuts.
    • --webadmin-settings-fileFile pathPath of the custom WebAdmin .4DSettings file for the WebAdmin web server. Not available with tool4d.
    --webadmin-access-keyStringAccess key for the WebAdmin web server. Not available with tool4d.
    --webadmin-auto-startBooleanStatus of the automatic startup for the WebAdmin web server. Not available with tool4d.
    --webadmin-store-settingsStore the access key and automatic starting parameters in the currently used settings file (i.e. the default WebAdmin.4DSettings file or a custom file designated with the --webadmin-settings-path parameter). Use the --webadmin-store-settings argument to save these settings if necessary. Not available with tool4d.
    --utilityOnly available with 4D Server. Launches 4D Server in utility mode.
    --skip-onstartupLaunches the project without executing any "automatic" methods, including the On Startup and On Exit database methods
    --startup-methodProject method name (string)Project method to execute immediately after the On Startup database method (if not skipped with --skip-onstartup).

    (*) Some dialogs are displayed before the database is opened, so that it's impossible to write into the Diagnostic log file (licence alert, conversion dialog, database selection, data file selection). In such case, an error message is thrown both in the stderr stream and the system event log, and then the application quits.

    Examples​

    The current folder of the user is reached using the "~ " command under macOS and the "%HOMEPATH%" command under Windows.

    Launch a 4D application stored on the desktop:

    • macOS:
    open ~/Desktop/4D.app
    open "~/Desktop/4D Server.app"
    • Windows:
    %HOMEPATH%\Desktop\4D\4D.exe
    %HOMEPATH%\Desktop\"4D Server.exe"

    Open a package file on macOS:

    --args ~/Documents/myDB.4dbase

    Open a project file:

    • macOS:
    --args ~/Documents/myProj/Project/myProj.4DProject
    • Windows:
    %HOMEPATH%\Documents\myProj\Project\myProj.4DProject

    Open a project file and a data file:

    • macOS:
    --args --project ~/Documents/myProj/Project/myProj.4DProject --data ~/Documents/data/myData.4DD
    • Windows:
    --project %HOMEPATH%\Documents\myProj\Project\myProj.4DProject --data %HOMEPATH%\Documents\data\myData.4DD
    or:
    /project %HOMEPATH%\Documents\myProj\Project\myProj.4DProject /data %HOMEPATH%\Documents\data\myData.4DD

    Open a .4DLink file:

    • macOS:
    ~/Desktop/MyDatabase.4DLink
    • Windows:
    %HOMEPATH%\Desktop\MyDatabase.4DLink

    Open compiled mode and create a data file if not available:

    • macOS:
    ~/Documents/myBase.4dbase --args --opening-mode compiled --create-data true
    • Windows:
    %HOMEPATH%\Documents\myBase.4dbase\myDB.4db --opening-mode compiled --create-data true

    Open a project file and a data file and pass a string as a user parameter:

    • macOS:
    --args --project ~/Documents/myProj/Project/myProj.4DProject --data ~/Documents/data/myData.4DD --user-param "Hello world"
    • Windows:
    --project %HOMEPATH%\Documents\myProj\Project\myProj.4DProject --data %HOMEPATH%\Documents\data\myData.4DD --user-param "Hello world"

    Open without interface (headless mode):

    • macOS:
    --args --project ~/Documents/myProj/Project/myProj.4DProject --data ~/Documents/data/myData.4DD --headless
    • Windows:
    --project %HOMEPATH%\Documents\myProj\Project\myProj.4DProject --data %HOMEPATH%\Documents\data\myData.4DD --headless

    tool4d​

    tool4d is a free, lightweight, stand-alone application allowing you to open a 4D project in headless mode and execute some 4D code using the CLI.

    tool4d is available on Windows and macOS and is always associated to a 4D release (same version and build number). It is only provided in English localization.

    tool4d is a perfect tool if you want to:

    • implement a CI/CD chain for your 4D application,
    • use a light 4D executable to run 4D scripts, for example to execute automatic unit tests.

    Using tool4d​

    You can get tool4d from the 4D Product download page.

    You use tool4d by executing a command line with a standard 4D project. You can use all arguments described in the above table, except --webadmin since this component is disabled in tool4d. With tool4d, the following specific sequence is launched:

    1. tool4d executes the On Startup database method (and all "automatic" methods such as user method), except if the --skip-onstartup argument is passed.
    2. tool4d executes the method designated by the --startup-method argument, if any.
    3. tool4d executes the On Exit database method, except if the --skip-onstartup argument is passed.
    4. tool4d quits.

    On Windows, tool4d is a console application so that the stdout stream is displayed in the terminal (cmd, powershell...).

    Notes
    • tool4d is always executed headless (the headless command line option is useless).
    • The Application type command returns the value 6 ("tool4d") when called from the tool4d application.
    • the diagnostic log file is prefixed with "4DDiagnosticLogTool".

    Disabled 4D features​

    Keep in mind that tool4d runs automatically in headless mode (see --headless in this table), and does neither give access to the 4D IDE nor any of its servers. In particular, the following features are disabled:

    • application server, Web server, SQL server,
    • backup scheduler,
    • ODBC and SQL pass-through,
    • all components such as 4D View Pro, 4D SVG, 4D NetKit...,
    • hunspell spell checker,
    • japanese spellchecker (mecab library),
    • WebAdmin,
    • CEF,
    • PHP,
    • remote debugger (local debugger, TRACE command and breakpoints are ignored in headless applications).

    4D Server in utility mode​

    You can launch a 4D Server instance in a utility mode (headless) by using the --utility CLI option. In this case, the following workflow is triggered:

    1. 4D Server executes the On Startup database method (and all "automatic" methods such as user method), except if the --skip-onstartup parameter is passed.
    2. 4D Server executes the method designated by the --startup-method, if any.
    3. 4D Server executes the On Exit database method, except if the --skip-onstartup parameter is passed.
    4. 4D Server quits.
    info

    Unlike tool4d, 4D Server in utility mode has all its features enabled. However, the application server and all other servers are not started.

    See also

    See this blog post for examples of how to use tool4d and 4D Server in utility mode.