Connect to LindormTable using Lindorm-cli - Lindorm - Alibaba Cloud Documentation Center

Lindorm-cli is a lightweight command line interface (CLI) provided by Lindorm for connecting to and managing Lindorm databases. Use Lindorm-cli to perform basic SQL operations such as creating tables, querying data, writing data, and exporting data. This topic describes how to connect to and use the Lindorm wide table engine with Lindorm-cli.

Prerequisites

We define the environment where you run lindorm-cli as the client environment. Before using lindorm-cli to access the Lindorm wide table engine, confirm the following:

Add the client IP address to the Lindorm whitelist. For more information, see Configure a whitelist.

Determine the network type between the client environment and Lindorm.

The following network types are supported when connecting to the wide table engine with lindorm-cli:

Network type	Description
Virtual private cloud (VPC) (recommended)	A virtual private cloud (VPC) is your private network in the cloud. Different VPCs are isolated at layer 2 logical isolation, providing high security. When you deploy lindorm-cli on an ECS instance, connecting to the Lindorm wide table engine over a VPC provides higher security and lower network latency.
Public network	The public network refers to the Internet. When you need to test or manage the Lindorm wide table engine from an on-premises device, deploy lindorm-cli on the local device and connect to the Lindorm wide table engine over the public network. Note Connecting over the public network does not incur traffic fees but poses a security risk. We recommend using a VPC for higher security. You must enable the public endpoint in the console. For more information, see Procedure.

Installation

Download the Lindorm-cli installation package that matches your operating system. The download links are listed in the following table.

Note

The SHA256 checksums in the table can be used to verify the integrity and authenticity of the downloaded Lindorm-cli packages.

Operating system	Download link	SHA256 checksum
Linux	lindorm-cli for linux Direct download command: `wget https://tsdbtools.oss-cn-hangzhou.aliyuncs.com/lindorm-cli-linux-latest.tar.gz`	3a9ee33e24769cf47b3a90c3a1bba29d26f8aede7a64dbc13ea1f4f5426f04e4
Linux-arm64	lindorm-cli for linux-arm64 Direct download command: `wget https://tsdbtools.oss-cn-hangzhou.aliyuncs.com/lindorm-cli-linux-arm64-latest.tar.gz`	bc723d4a3a14a85c973c7082a56bb4934a40d2b9cccd72b5767352b8c334ce19
Mac (Intel chip)	lindorm-cli for mac	34efd3f43a700e1fea72ee5e5933b9df3cf624569bcf59a2f8a6752dc7faab6c
Mac (Arm chip)	lindorm-cli for mac	0be9b346404a37d953714377b59f06b6492ff9c4e46dba4d5bf07c390ee284ad
Windows	lindorm-cli for windows-x64	54a447f263b93b158533f7ccd542cbf52e42fb66ce287d38065a798b7801fc48

Decompress the Lindorm-cli package.
Use the standard decompression method for your operating system to extract the downloaded package.
For Linux, run the following command to decompress the package. After decompression, you get the lindorm-cli file. This executable file can be run directly in a shell terminal without additional installation steps.
```
tar zxvf lindorm-cli-linux-latest.tar.gz
```

Connection methods

Lindorm-cli supports connecting to the Lindorm wide table engine using either the MySQL protocol or the Avatica protocol. We recommend using the MySQL protocol.

Important

Only lindorm-cli versions 2.0.0 and later support connecting to the wide table engine using the MySQL protocol.

Connect to the wide table engine using the MySQL protocol (recommended)

Client deployed on Linux or Mac

Go to the directory that contains Lindorm-cli.
```
cd <Lindorm-cli directory>
```

Run the following command to connect to the wide table engine.

./lindorm-cli -url <mysql url> -username <username> -password <password>

Parameter description

Parameter	Description
mysql url	The MySQL-compatible endpoint of the Lindorm wide table engine. For more connection configuration details, see Connection configuration.
username	The username for connecting to the Lindorm wide table engine.
password	The password for connecting to the Lindorm wide table engine. Important If you forget your password, you can reset the user password in the Lindorm wide table engine cluster management system. After resetting the password, restart the engine in the console.

Connection configuration

Supported connection configurations

Description

mysql:// protocol header

You can prepend the mysql:// protocol header to the mysql url.

Example: mysql://ld-8vbn68478unu8****-proxy-sql-lindorm.lindorm.rds.aliyuncs.com:33060.

Server-side custom connection parameters

You can append server-side custom connection parameters to the mysql url in the format key1=value1&key2=value2.

The following parameter is currently supported:

operationTimeout: Specifies the query timeout period. The format is <mysql url>?operationTimeout=<timeout>, where the timeout unit is milliseconds (ms). Example: ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060?operationTimeout=120000.

Important

Only wide table engine versions 2.7.7 and later support the operationTimeout parameter. For information about how to view or upgrade your current version, see Wide table engine version guide and Minor version update.

Connection examples

./lindorm-cli -url ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 -username user -password test

--Add mysql:// protocol header
./lindorm-cli -url mysql://ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 -username user -password test

--Specify query timeout
./lindorm-cli -url mysql://ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060?operationTimeout=120000 -username user -password test

A successful connection returns the following result:

lindorm-cli version: 2.0.x

Here, 2.0.x is the Lindorm-cli version number.

Client deployed on Windows

Method 1

Open Command Prompt (CMD) and go to the directory that contains lindorm-cli.exe.
```
cd <lindorm-cli.exe directory>
```

Run the following command in CMD to connect to the wide table engine.

lindorm-cli -url <mysql url> -username <username> -password <password>

Parameter description

Parameter	Example value	How to obtain
mysql url	ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060	The MySQL-compatible endpoint of the Lindorm wide table engine. For more connection configuration details, see Connection configuration.
username	user	The username for connecting to the Lindorm wide table engine.
password	test	The password for connecting to the Lindorm wide table engine. Important If you forget your password, you can reset the user password in the Lindorm wide table engine cluster management system. After resetting the password, restart the engine in the console.

Connection configuration

Supported connection configurations

Description

mysql:// protocol header

You can prepend the mysql:// protocol header to the mysql url.

Example: mysql://ld-8vbn68478unu8****-proxy-sql-lindorm.lindorm.rds.aliyuncs.com:33060.

Server-side custom connection parameters

You can append server-side custom connection parameters to the mysql url in the format key1=value1&key2=value2.

The supported parameters are as follows:

Important

Connection examples

lindorm-cli -url ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 -username user -password test

--Add mysql:// protocol header
lindorm-cli -url mysql://ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 -username user -password test

--Specify query timeout
lindorm-cli -url mysql://ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060?operationTimeout=120000 -username user -password test

A successful connection returns the following result:

Connected to ld-bp187uwcx5f40****-proxy-sql-lindorm-public.lindorm.rds.aliyuncs.com:33060
lindorm-cli version: 2.0.x

Here, 2.0.x is the Lindorm-cli version number.

Method 2

Double-click to open the Lindorm-cli.exe program and run the following command:

connect <mysql url> <username> <password>

Connection example

connect ld-bp13y790c91f4****-proxy-lindorm-pub.lindorm.aliyuncs.com:33060  user test

A successful connection returns no output.

Connect to the wide table engine using the Avatica protocol

Client deployed on Linux or Mac

Go to the directory that contains Lindorm-cli.
```
cd <Lindorm-cli directory>
```

Run the following command to connect to the wide table engine.

./lindorm-cli -url <url> -username <username> -password <password>

Parameter description

Parameter	Example value	How to obtain
jdbc url	jdbc:lindorm:table:url=http://ld-bp17j28j2y7pm****-proxy-lindorm-pub.lindorm.rds.aliyuncs.com:30060	The wide table SQL endpoint of the Lindorm wide table engine.
username	user	The username for connecting to the Lindorm wide table engine.
password	test	The password for connecting to the Lindorm wide table engine. Important If you forget your password, you can reset the user password in the Lindorm wide table engine cluster management system. After resetting the password, restart the engine in the console.

Connection example

./lindorm-cli -url jdbc:lindorm:table:url=http://ld-bp17j28j2y7pm****-proxy-lindorm-pub.lindorm.rds.aliyuncs.com:30060 -username user -password test

A successful connection returns the following result:

lindorm-cli version: 2.0.xx

Here, 2.0.xx is the Lindorm-cli version number.

Client deployed on Windows

Method 1

Open Command Prompt (CMD) and go to the directory that contains lindorm-cli.exe.
```
cd <lindorm-cli.exe directory>
```

Run the following command in CMD to connect to the wide table engine.

lindorm-cli -url <jdbc url> -username <username> -password <password>

Parameter description

Parameter	Example value	How to obtain
jdbc url	jdbc:lindorm:table:url=http://ld-bp17j28j2y7pm****-proxy-lindorm-pub.lindorm.rds.aliyuncs.com:30060	The wide table SQL endpoint of the Lindorm wide table engine.
username	user	The username for connecting to the Lindorm wide table engine.
password	test	The password for connecting to the Lindorm wide table engine. Important If you forget your password, you can reset the user password in the Lindorm wide table engine cluster management system. After resetting the password, restart the engine in the console.

Connection example

lindorm-cli -url jdbc:lindorm:table:url=http://ld-bp13y790c91f4****-proxy-lindorm-pub.lindorm.aliyuncs.com:30060 -username user -password test

A successful connection returns the following result:

Connected to jdbc:lindorm:table:url=http://ld-bp13y790c91f4****-proxy-lindorm-pub.lindorm.rds.aliyuncs.com:30060
lindorm-cli version: 2.0.xx

Here, 2.0.xx is the Lindorm-cli version number.

Method 2

Double-click to open the Lindorm-cli.exe program and run the following command:

connect <jdbc url> <username> <password>

Connection example

connect jdbc:lindorm:table:url=http://ld-bp13y790c91f4****-proxy-lindorm-pub.lindorm.aliyuncs.com:30060 user test

A successful connection returns no output.

Usage

Lindorm-cli supports both interactive and non-interactive modes for executing SQL statements against the wide table engine.

Execute SQL statements in interactive mode

In most cases, you start lindorm-cli in interactive mode to operate the wide table engine. The workflow is as follows:

Start lindorm-cli
After connecting to the Lindorm wide table engine using any protocol described in the previous section, your terminal enters the lindorm-cli interactive interface and waits for further commands.
Note
On Windows, double-clicking lindorm-cli.exe opens a CMD terminal window. This starts the lindorm-cli interactive interface but does not establish a connection to the Lindorm wide table engine. You must use the connect subcommand to establish a connection before running SQL statements. For more information, see Client deployed on Windows and Method 2.
Enter SQL statements to access the wide table engine
After establishing a connection and entering the interactive interface, enter SQL statements to access the wide table engine. For supported SQL syntax, see SQL reference.
Exit lindorm-cli
After completing your operations in the interactive interface, exit lindorm-cli by running the exit subcommand or pressing the ctrl+d keyboard shortcut.

Note

After starting lindorm-cli in interactive mode and successfully connecting to the wide table engine, the client maintains a session with the engine until you exit. All SQL operations during this period run in the same session. Note that if the session remains idle for too long, the system automatically disconnects to reclaim resources.

Execute SQL statements in non-interactive mode

When writing O&M scripts, to directly execute Lindorm SQL statements without entering the interactive command line, you can use the non-interactive mode of lindorm-cli to work with LindormTable. This mode directly runs SQL via command parameters and returns the results, making it suitable for automated tasks such as performing queries or statistical operations.

To execute an SQL statement in non-interactive mode from a shell terminal, append the -execute parameter followed by the SQL statement enclosed in single or double quotes to the connection parameters (such as host address and port) described in Connection methods. This quickly establishes a short-lived connection and executes the command. Example:

lindorm-cli -url mysql://ld-xxxxxx-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 -username user -password XXXX -execute "CREATE TABLE tb (id VARCHAR, name VARCHAR, address VARCHAR,  PRIMARY KEY(id, name));"

You can also export wide table query results to a CSV file using non-interactive mode.

Important

Exporting to CSV requires lindorm-cli version 2.2.0 or later. To check your current version:

Run lindorm-cli -version in the command line.
Check the version displayed in the welcome message when entering interactive mode.

lindorm-cli -url mysql://ld-xxxxxx-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 -username user -password XXXX -format csv -output ~/result.csv -execute "SELECT * FROM tb;"

Note

Short-lived connections: In non-interactive mode, lindorm-cli establishes a new connection for each SQL statement and closes it immediately after execution.
Output control: Results are printed to the terminal screen (stdout) by default. To redirect output to a file, use the -output parameter.

Use lindorm-cli with AI Agent

In addition to interactive and non-interactive modes, lindorm-cli can also be invoked by AI Agents. When you want to use natural language to let an AI Agent automatically perform Lindorm data queries, result analysis, or O&M script generation, you can combine Lindorm Agent Skill with lindorm-cli.

Note

The AI Agent-oriented capabilities described below require lindorm-cli version 2.3.0 or later.

Scenarios

Using lindorm-cli through an AI Agent is suitable for the following scenarios:

Natural language data queries: Describe your query intent in natural language. The Agent generates and executes SQL statements and returns structured results.
Batch O&M script generation: Let the Agent generate scripts that call lindorm-cli based on your requirements for scheduled tasks or batch data processing.
Structured result export: Use the Agent to export query results directly in machine-parseable formats such as JSON or JSONL for downstream processing.

Install Lindorm Agent Skill

Lindorm Agent Skill provides AI Agents with the context needed to call lindorm-cli. It guides the Agent to automatically detect the local lindorm-cli installation, select appropriate parameters, and construct commands.

You can download Lindorm Agent Skill from: alibabacloud-lindorm-agent-skill

After installation, the Agent can call lindorm-cli to access the Lindorm wide table engine directly in conversations. The Skill固化 (solidifies) the CLI capabilities and parameters described below, so you typically do not need to enter these parameters manually.

Agent usage

After installing Lindorm Agent Skill, you only need to describe your requirements in natural language. The Agent automatically performs detection, queries, security controls, and credential injection under the guidance of the Skill.

Agent automatically detects lindorm-cli capabilities

Before the first call, the Agent detects the lindorm-cli version, supported protocols, output formats, and exit code definitions in the current environment. This allows the Agent to choose the correct invocation method based on the actual environment rather than relying on hardcoded assumptions.

Note

This behavior is built into Lindorm Agent Skill and corresponds to the --capabilities parameter of lindorm-cli.

Agent returns results in structured format

When the Agent executes a query, it requires lindorm-cli to output results in JSON or JSONL format. Only query result data is sent to stdout; status messages and warnings go to stderr. The two streams are isolated for easy parsing by the Agent.

For large result sets, the Agent uses JSONL format to consume results line by line, avoiding loading all data at once.

Note

This behavior is built into Lindorm Agent Skill and corresponds to the -format json and -format jsonl parameters of lindorm-cli.

Agent enables safety guardrails

Lindorm Agent Skill enables safe mode by default, intercepting high-risk write operations such as DROP TABLE, TRUNCATE TABLE, and DELETE FROM at the client side to prevent the Agent from accidentally executing destructive SQL. The Skill also limits the maximum number of rows returned per query to prevent large result sets from exhausting the Agent's context window.

Note

This behavior is built into Lindorm Agent Skill and corresponds to the --safe-mode and --max-rows parameters of lindorm-cli.

Agent securely injects credentials

When the Agent calls lindorm-cli, the Skill prioritizes injecting usernames and passwords through environment variables or standard input, preventing credentials from appearing in command line arguments, Shell history, or process listings.

Note

This behavior is built into Lindorm Agent Skill and corresponds to the environment variable credential injection and the --password-stdin parameter of lindorm-cli.

Command line parameters and subcommands

Command line parameters

When starting lindorm-cli in a terminal, you can specify the following command line parameters:

Parameter name	Requires value	Value	Description
url	Yes	Protocol name + SQL connection string (including port) for the Lindorm wide table engine	Specifies the protocol and connection string for lindorm-cli to connect to the wide table engine. When using the MySQL protocol, specify the MySQL-compatible endpoint of the wide table engine. When using the Avatica protocol, specify the wide table SQL endpoint of the wide table engine.
username	Yes	Username for the connection	The specified username must be a Lindorm user already created in the wide table engine.
password	Yes	Password for the username	-
database	Yes	Database name to connect to	If not specified, the default database is used. If specified, the database must already exist in the wide table engine.
execute	Yes	SQL statement to execute	When the execute parameter is specified, lindorm-cli runs in non-interactive mode. Enclose the SQL statement in single or double quotes. Note When using double quotes to enclose the SQL statement, escape internal double quotes with a backslash `\`. Single quotes do not support escaping.
output	Yes	Output location for SQL execution results in non-interactive mode	In non-interactive mode, if output is not specified, results are printed to standard output. If specified, results are written to the file at the given path. If the file does not exist, it will be created.
format	Yes	One of the following: horizontal, vertical, csv, json, column	Changes the format of SQL execution results returned by the wide table engine. The default format is column. column: Displays results in a common table format. horizontal: Displays data horizontally by column. vertical: Displays data vertically by row, similar to the `\G` format in the MySQL command line. csv: Displays results in CSV format without table borders. json: Displays results in JSON format.
pretty	No	-	Use with format set to JSON. When enabled, results are output as pretty-printed JSON. By default, results are output as compact JSON.
csvNoHeader	No	-	Use with format set to CSV. When enabled, results are output in CSV format without column headers.
nullString	Yes	String to replace NULL values	Use with format set to CSV. When specified, NULL values in query results are replaced with the given string. If nullString is not specified, NULL values are output as follows: When connected via the MySQL protocol, NULL values are represented as `\N`. When connected via the Avatica protocol, NULL values are represented as empty strings.
version	No	-	Displays the lindorm-cli version information. Lindorm-cli does not start or enter interactive mode when this parameter is used.
format	Yes	One of: horizontal, vertical, csv, json, jsonl, column	Changes the format of SQL execution results returned by the wide table engine. The default is column. column: Displays results in a standard table format. horizontal: Displays data horizontally by column. vertical: Displays data vertically by row. csv: Displays results in CSV format without table borders. json: Displays results in JSON format for Agent parsing. jsonl: One independent JSON object per line, suitable for Agents to consume large result sets in a streaming manner.
capabilities	No	-	Outputs a JSON capability declaration of lindorm-cli, including supported engines, formats, exit codes, and parameters. In AI Agent scenarios, this is automatically called by Lindorm Agent Skill.
safe-mode	No	-	When enabled, the client intercepts high-risk write operations such as DROP TABLE, TRUNCATE TABLE, and DELETE FROM. In AI Agent scenarios, this is enabled by default by Lindorm Agent Skill.
max-rows	Yes	Positive integer	Limits the maximum number of rows returned by the client. Excess rows are truncated. In AI Agent scenarios, this is set by default by Lindorm Agent Skill to prevent large result sets from exhausting the Agent's context window.
password-stdin	No	-	Reads the password from standard input to prevent it from appearing in command line arguments. In AI Agent scenarios, Lindorm Agent Skill prioritizes this over the plain `-password` parameter.

Note

All lindorm-cli command line parameters must be prefixed with a hyphen -.

Common subcommands

After starting lindorm-cli in interactive mode, you can run lindorm-cli subcommands in the interactive interface to control its behavior, in addition to sending SQL statements to the Lindorm wide table engine. Common subcommands are listed below:

Subcommand	Parameters	Description
connect	<url> <username> <password>	When lindorm-cli is started in interactive mode without a connection, use the connect subcommand to establish a connection to the Lindorm wide table engine. The url, username, and password parameters have the same meanings as the command line parameters `url`, `username`, and `password`.
format	One of the following: horizontal, vertical, csv, json	Same as the `format` parameter.
help	None	Displays a list of common subcommands.
history	None	Displays recently executed SQL statements or subcommands.
exit or quit	None	Exits lindorm-cli and disconnects from the Lindorm wide table engine.

FAQ

Why am I experiencing connection timeouts or failures?

Connection timeouts or failures return errors such as Failed to connect to <wide table endpoint> connection check failed or connection timeout.

Possible causes and solutions are listed below. Check them in order:

Cause	Solution
Using a public network connection without adding the public IP address to the whitelist.	Add the client public IP address to the Lindorm whitelist. To find your client public IP address, run `curl ipinfo.io/ip` or `curl ifconfig.me` in Windows Command Prompt (CMD).
The public IP address is added to the whitelist, but connection timeouts persist.	Network instability may be the cause. We recommend switching to a VPC connection.
Accessing from an ECS instance without adding the ECS IP address to the Lindorm whitelist.	Obtain the ECS IP address and add it to the Lindorm whitelist.
Using an incorrect endpoint.	Lindorm endpoints differ for VPC and public network connections. Use the correct endpoint based on your network environment.

If none of these solutions resolve your issue, contact Lindorm technical support (DingTalk ID: s0s3eg3).

References

For information about Lindorm wide table SQL syntax, see SQL reference.
Other connection methods: Connect to and use the wide table engine with the MySQL command line, Use the MySQL protocol (recommended).