DolphinDB Terminal

DolphinDB Terminal is an interactive CLI tool used to connect to a remote DolphinDB server for command execution. However, it is not suitable for developing or executing complex scripts due to lack of GUI tools.

The DolphinDB Terminal and DolphinDB Server share the same executable program. If the parameters remoteHost and remotePort are specified when launching DolphinDB, it will start as the DolphinDB Terminal. If the DolphinDB server does not allow a guest user to log in, you can specify the uid and pwd during startup, or use the login function after the terminal has started.

The Terminal functions in a simple way: it takes user input, sends the input to the remote server for execution, and displays the result in the terminal. The DolphinDB Terminal does not require a license, nor does it need to be configured in the system initialization script dolphindb.dos or other configuration files. DolphinDB Terminal is cross-platform. For example, you can use a Terminal running on Windows to connect to a DolphinDB server deployed on Linux.

Basic Usage

Set the PATH

Add the DolphinDB directory (containing dolphindb.exe) to the system's search path for Terminal to access across any working directory:

  • Linux​

    Export to PATH.

    export PATH=/your/dolphindb/excutable/path:$PATH
  • Windows

    Add the executable path to the environment variable Path (use “;” as separator).

Start DolphinDB Terminal​

  • Linux​

    Use rlwrap to enable command history.

    rlwrap -r ./dolphindb -remoteHost 127.0.0.1 -remotePort 8848 -uid admin -pwd 123456
  • ​Windows​
    dolphindb.exe -remoteHost 127.0.0.1 -remotePort 8848 -uid admin -pwd 123456

The Terminal will displays its information upon successful startup:

DolphinDB Terminal 2.00.16 (Build:2025.05.07). Copyright (c) 2011~2025 DolphinDB, Inc.

If you haven’t specified the uid and pwd during startup, use login function after connecting.

>DolphinDB Terminal 2.00.16 (Build:2025.05.07). Copyright (c) 2011~2025 DolphinDB, Inc.
>login("admin","123456");

Execute Scripts​

  • Single-line​
    1 + 2;
  • ​Multi-line​
    def myFunc(x, y) {
        return x + y
    }
    myFunc(1, 2);
Avoid using “;” within function definitions to prevent parsing errors. Example of an ​​invalid​​ script:
def myFunc(x,y){
    return x+y;
}
myFunc(1,2);
// Syntax Error: [line #2] } expected to end function definition

Quit Terminal

​Type “quit” and press “Enter” to quit the Terminal.

Execute Local Scripts on Remote Server

If all required scripts are prepared in a local file, it is simple to run them on a remote server by specifying the -run parameter when running the DolphinDB Terminal​. The local script file specified by -run will be sent to the remote server for execution and the Terminal exits immediately upon completion. Example on Linux:

./dolphindb -remoteHost 127.0.0.1 -remotePort 8848 -uid admin -pwd 123456 -run /home/usr1/test.dos

In this way, we do not need to input the code in the Terminal. It is simpler for complex scripts and repeated tasks. However, it does not support real-time interaction during execution.

Note:​Note​​: The system will return a non-zero value if an exception occurs when using the -run method to execute a local script file on a remote server.

Execute Scripts Locally and Remotely

In certain scenarios, it is necessary to execute scripts both locally and remotely. For example, read a CSV file on local machine and append the data to a remote DolphinDB database. The following examples show how to do it on:

  • Linux
    ./dolphindb  -run /home/usr1/test.dos
  • Windows
    dolphindb.exe -run c:/users/usr1/test.dos

To execute a local script, specify the script path with the -run parameter without specifying remoteHost. This will run a DolphinDB ​workstation​ to execute the script and exit upon completion.

To interact with remote databases during local script execution, we should connect to the remote server using the xdb function and then execute scripts or RPC calls​​ via the remoteRun function. DolphinDB extends RPC calls to support invoking functions ​predefined on the remote server​​ and​​serializing local functions​​ and executing them on the remote server. For executing complex scripts, it is recommended to define them as a local function and call the function remotely​​ via remoteRun.

The following script file test.dos shows how to write data in a local CSV file into a remote distributed table:

def appendData(dbPath, partitionTable, t1){
    pt = loadTable(dbPath, partitionTable)
    return tableInsert(pt, t1)
}
conn=xdb("127.0.0.1",8848,"admin","123456")
remoteRun(conn, appendData, "dfs://db1", "pt", loadText("c:/users/usr1/data.csv"))

The script first defines a function appendData that writes an in-memory table to a specified table. It then creates a remote connection conn. Finally, it loads a local CSV file using the loadText function and call the appendData function via RPC.