IOTDB 为用户提供 cli/Shell 工具用于启动客户端和服务端程序。下面介绍每个 cli/Shell 工具的运行方式和相关参数。
$IOTDB_HOME 表示 IoTDB 的安装目录所在路径。
安装后的 IoTDB 中有一个默认用户：root，默认密码为TimechoDB@2021（V2.0.6.x 版本之前为root）。用户可以使用该用户尝试运行 IoTDB 客户端以测试服务器是否正常启动。客户端启动脚本为$IOTDB_HOME/sbin 文件夹下的start-cli脚本。启动脚本时需要指定运行 IP 和 RPC PORT。以下为服务器在本机启动，且用户未更改运行端口号的示例，默认端口为 6667。若用户尝试连接远程服务器或更改了服务器运行的端口号，请在-h 和-p 项处使用服务器的 IP 和 RPC PORT。
用户也可以在启动脚本的最前方设置自己的环境变量，如 JAVA_HOME 等。
Linux 系统与 MacOS 系统启动命令如下：
# V2.0.6.x 版本之前 Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root # V2.0.6.x 版本及之后 Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw TimechoDB@2021
Windows 系统启动命令如下：
# V2.0.4.x 版本之前 Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root # V2.0.4.x 版本及之后, V2.0.6.x 版本之前 Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root # V2.0.6.x 版本及之后 Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw TimechoDB@2021
回车后即可成功启动客户端。启动后出现如图提示即为启动成功。
_____ _________ ______ ______ |_ _| | _ _ ||_ _ `.|_ _ \ | | .--.|_/ | | \_| | | `. \ | |_) | | | / .'`\ \ | | | | | | | __'. _| |_| \__. | _| |_ _| |_.' /_| |__) | |_____|'.__.' |_____| |______.'|_______/ version <version> Successfully login at 127.0.0.1:6667
输入quit或exit可退出 cli 结束本次会话，cli 输出quit normally表示退出成功。
| 参数名 | 参数类型 | 是否为必需参数 | 说明 | 示例 |
|---|---|---|---|---|
-h <host> | string 类型 | 否 | IoTDB 客户端连接 IoTDB 服务器的 IP 地址， 默认使用：127.0.0.1。 | -h 127.0.0.1 |
-p <rpcPort> | int 类型 | 否 | IoTDB 客户端连接服务器的端口号，IoTDB 默认使用 6667。 | -p 6667 |
-u <username> | string 类型 | 否 | IoTDB 客户端连接服务器所使用的用户名，默认使用 root。 | -u root |
-pw <password> | string 类型 | 否 | IoTDB 客户端连接服务器所使用的密码，默认使用 TimechoDB@2021（V2.0.6版本之前为root）。 | -pw root |
-sql_dialect <sql_dialect> | string 类型 | 否 | 目前可选 tree（树模型） 、table（表模型），默认 tree | -sql_dialect table |
-e <execute> | string 类型 | 否 | 在不进入客户端输入模式的情况下，批量操作 IoTDB。 | -e “show databases” |
| -c | 空 | 否 | 如果服务器设置了 rpc_thrift_compression_enable=true， 则 CLI 必须使用 -c | -c |
| -disableISO8601 | 空 | 否 | 如果设置了这个参数，IoTDB 将以数字的形式打印时间戳 （timestamp）。 | -disableISO8601 |
-usessl <use_ssl> | Boolean 类型 | 否 | 否开启 ssl 连接 | -usessl true |
-ts <trust_store> | string 类型 | 否 | ssl 证书存储路径 | -ts /path/to/truststore |
-tpw <trust_store_pwd> | string 类型 | 否 | ssl 证书存储密码 | -tpw myTrustPassword |
-timeout <queryTimeout> | int 类型 | 否 | 查询超时时间（秒）。如果未设置，则使用服务器的配置。 | -timeout 30 |
| -help | 空 | 否 | 打印 IoTDB 的帮助信息。 | -help |
下面展示一条客户端命令，功能是连接 IP 为 10.129.187.21 的主机，端口为 6667 ，用户名为 root，密码为 root，以数字的形式打印时间戳，IoTDB 命令行显示的最大行数为 10。
Linux 系统与 MacOS 系统启动命令如下：
Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10
Windows 系统启动命令如下：
# V2.0.4.x 版本之前 Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 # V2.0.4.x 版本及之后 Shell > sbin\windows\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10
下面列举了一些CLI的特殊命令。
| 命令 | 描述 / 例子 |
|---|---|
set time_display_type=xxx | 例如： long, default, ISO8601, yyyy-MM-dd HH:mm:ss |
show time_display_type | 显示时间显示方式 |
set time_zone=xxx | 例如： +08:00, Asia/Shanghai |
show time_zone | 显示CLI的时区 |
set fetch_size=xxx | 设置从服务器查询数据时的读取条数 |
show fetch_size | 显示读取条数的大小 |
set max_display_num=xxx | 设置 CLI 一次展示的最大数据条数， 设置为-1表示无限制 |
help | 获取CLI特殊命令的提示 |
exit/quit | 退出CLI |
当您想要通过脚本的方式通过 Cli / Shell 对 IoTDB 进行批量操作时，可以使用-e 参数。通过使用该参数，您可以在不进入客户端输入模式的情况下操作 IoTDB。
为了避免 SQL 语句和其他参数混淆，现在只支持-e 参数作为最后的参数使用。
针对 cli/Shell 工具的-e 参数用法如下：
Linux 系统与 MacOS 指令：
Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb}
Windows 系统指令
# V2.0.4.x 版本之前 Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} # V2.0.4.x 版本及之后 Shell > sbin\windows\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb}
在 Windows 环境下，-e 参数的 SQL 语句需要使用``对于" "进行替换
为了更好的解释-e 参数的使用，可以参考下面在 Linux 上执行的例子。
假设用户希望对一个新启动的 IoTDB 进行如下操作：
创建名为 root.demo 的 database
创建名为 root.demo.s1 的时间序列
向创建的时间序列中插入三个数据点
查询验证数据是否插入成功
那么通过使用 cli/Shell 工具的 -e 参数，可以采用如下的脚本：
# !/bin/bash host=127.0.0.1 rpcPort=6667 user=root pass=root bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "CREATE DATABASE root.demo" bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo"
打印出来的结果显示如下，通过这种方式进行的操作与客户端的输入模式以及通过 JDBC 进行操作结果是一致的。
Shell > bash ./shell.sh +-----------------------------+------------+ | Time|root.demo.s1| +-----------------------------+------------+ |1970-01-01T08:00:00.001+08:00| 10| |1970-01-01T08:00:00.002+08:00| 11| |1970-01-01T08:00:00.003+08:00| 12| +-----------------------------+------------+ Total line number = 3 It costs 0.267s
需要特别注意的是，在脚本中使用 -e 参数时要对特殊字符进行转义。
IoTDB V2.0.9.1 起支持开启访问历史功能，即客户端登录成功后展示关键的历史访问信息，支持分布式场景。管理员与普通用户仅可查看自身访问历史，核心展示内容包括：
支持通过修改 iotdb-system.properties 文件中的相关参数来控制是否开启访问历史功能，修改参数后需重启生效，例如：
# 用于控制是否启用审计日志功能 enable_audit_log=false
使用示例：
--------------------- Starting IoTDB Cli --------------------- _____ _________ ______ ______ |_ _| | _ _ ||_ _ `.|_ _ \ | | .--.|_/ | | \_| | | `. \ | |_) | | | / .'`\ \ | | | | | | | __'. _| |_| \__. | _| |_ _| |_.' /_| |__) | |_____|'.__.' |_____| |______.'|_______/ Enterprise version 2.0.9.1 (Build: xxxxxxx) ---Last Successful Session------------------ Time: 2026-03-24T10:25:47.759+08:00 IP Address: 127.0.0.1 ---Last Failed Session---------------------- Time: 2026-03-24T10:27:26.314+08:00 IP Address: 127.0.0.1 Cumulative Failed Attempts: 1 Successfully login at 127.0.0.1:6667 IoTDB>
root 用户及具有 AUDIT 权限的用户可以通过 SQL 语句查看访问历史记录。
语法定义：
select * from root.__audit.login.u_{userid}.**
其中 userid 可通过 list user 语句查看。
示例：
IoTDB> select * from root.__audit.login.** +-----------------------------+------------------------------------+--------------------------------+--------------------------------------+ | Time|root.__audit.login.u_0.node_1.result|root.__audit.login.u_0.node_1.ip|root.__audit.login.u_0.node_1.username| +-----------------------------+------------------------------------+--------------------------------+--------------------------------------+ |2026-03-25T10:55:58.240+08:00| true| 127.0.0.1| root| +-----------------------------+------------------------------------+--------------------------------+--------------------------------------+ Total line number = 1 It costs 0.039s IoTDB> select * from root.__audit.login.u_0.** +-----------------------------+------------------------------------+--------------------------------+--------------------------------------+ | Time|root.__audit.login.u_0.node_1.result|root.__audit.login.u_0.node_1.ip|root.__audit.login.u_0.node_1.username| +-----------------------------+------------------------------------+--------------------------------+--------------------------------------+ |2026-03-25T10:55:58.240+08:00| true| 127.0.0.1| root| +-----------------------------+------------------------------------+--------------------------------+--------------------------------------+ Total line number = 1 It costs 0.020s