TimechoCLI
About 8 min
TimechoCLI
1. Introduction
TimechoCLI is Timecho's unified command-line tool for end users, automation scripts, and AI Agents. Together with the official Skills, it connects TimechoDB, Apache IoTDB, and TimechoAI workflows through natural language, lowering the learning curve and bridging the final gap between databases and AI.
For TimechoDB, the CLI covers the complete workflow from deployment and activation to SQL execution, data import and export, operations, and diagnostics. For TimechoAI, it supports data loading, model inference, and result visualization. Its companion Skills help prevent invented commands and incorrect parameters, improving operational accuracy.
TimechoCLI is compatible with popular Agent environments such as Codex, Claude Code, and Hermes, providing a straightforward Agent interface for the full Timecho product line.
2. Installation
For installation and deployment, see TimechoCLI Deployment.
3. Natural Language Interaction Examples with LLMs
3.1 Prerequisite: The LLM Installs the CLI and Connects the Skills First
Say to the LLM:
Help me install Timecho CLI: https://timecho.com/timecho-cli/installation-guide.md
Help me update Timecho CLI: https://timecho.com/timecho-cli/installation-guide.md3.2 Prerequisite: One-Click Standalone TimechoDB Deployment + Activation
Say to the LLM:
Deploy a standalone (1C1D) TimechoDB instance under D:\timecho on this machine, using the package D:\TimechoDB\timechodb-2.0.10.2-bin.zip. After deployment, activate the license and verify that the service is available.3.3 Scenario 1: Start TimechoDB
Say to the LLM:
Check whether my TimechoDB is running. If it is not, start it and verify that the service is available.3.4 Scenario 2: Connection Inspection + Deep Health Check + Diagnostic Bundle (Operations · Inspection)
Say to the LLM:
Perform a comprehensive TimechoDB inspection: check the overall health status, look for disk, memory, WAL, or Compaction issues, and generate an inspection report.3.5 Scenario 3: Configuration Inspection and Tuning (Operations · Configuration)
Say to the LLM:
Compare the current TimechoDB configuration with the recommended values. Tune key parameters such as memory, WAL, and Compaction for this machine's resources, but do not apply any changes yet.3.6 Scenario 4: SQL Development / Text2SQL + Data Import & Export (Operations · Data Development)
Say to the LLM:
Import this CSV file table_metrics.csv into the test database in the TimechoDB Table model. If the table already exists, delete it first. Then let me query the data in natural language, for example: "Return the average temperature of each device over the last hour as CSV."3.7 Scenario 5: SQL Development / Object Data Import
Say to the LLM:
Create the object_test database in the Table model, and create the table device_obj with the following DDL:
CREATE TABLE "device_obj" (
"device_id" STRING TAG,
"file_name" STRING ATTRIBUTE,
"file_size" INT32 FIELD,
"file_data" OBJECT FIELD
) WITH (ttl='INF')
Insert the images in the D:\TimechoDB directory into the device_obj table.3.8 Scenario 6: Fault Diagnosis + Log Analysis (Operations · Troubleshooting)
Say to the LLM:
My database reports the following error. Identify the root cause and provide the steps to fix it.
There is not enough memory to execute current fragment instance, current remaining free memory is 86762854, estimated memory usage for current fragment instance is 270139392My database reports the following error. Identify the root cause and provide the steps to fix it.
2026-08-21 10:12:33.815 [main] ERROR o.a.i.db.service.DataNodeStartUpCheck:70 - Reject DataNode restart.
Please clean the data directory before starting.
org.apache.iotdb.exceptions.StartupException: 203: Start up error. DataNode has been registered to cluster,
but data directory is not empty. Please clean the data/datanode/ directory and restart.
at org.apache.iotdb.db.service.DataNodeStartUpCheck.check(DataNodeStartUpCheck.java:68)
at org.apache.iotdb.db.service.IoTDB.startup(IoTDB.java:120)
at org.apache.iotdb.db.service.IoTDBEntryPoint.main(IoTDBEntryPoint.java:45)
2026-08-21 10:12:33.820 [main] ERROR org.apache.iotdb.db.service.IoTDB:152 - Failed to start IoTDB DataNode
because: 203: Start up error. DataNode has been registered to cluster, but data directory is not empty.My database reports the following error. Identify the root cause and provide the steps to fix it.
2026-08-21 14:25:07.332 [pool-3-thread-1] WARN o.a.i.db.mpp.execution.FragmentInstanceManager:218 -
Failed to execute fragment instance, instance_id=20260821_142507_00001_00003
org.apache.iotdb.exceptions.QueryProcessException: 709: MPP task execution memory is not enough.
current remaining free memory is 86762854, estimated memory usage for current fragment instance is 270139392.
Please try to reduce the query range or increase the memory allocation.
at org.apache.iotdb.db.mpp.execution.FragmentInstanceManager.checkMemory(FragmentInstanceManager.java:210)
at org.apache.iotdb.db.mpp.execution.FragmentInstanceManager.start(FragmentInstanceManager.java:165)
at org.apache.iotdb.db.mpp.plan.planner.DistributionPlanner.plan(DistributionPlanner.java:98)
at org.apache.iotdb.db.mpp.plan.Planner.planQuery(Planner.java:76)
at org.apache.iotdb.db.mpp.sql.Analyzer.analyzeQuery(Analyzer.java:112)
2026-08-21 14:25:07.335 [pool-3-thread-1] ERROR org.apache.iotdb.db.mpp.plan.PlanProcessor:89 -
Failed to process query: SELECT * FROM root.sg_1.d_1.* WHERE time > 2026-08-01T00:00:00.000+08:00My database reports the following error. Identify the root cause and provide the steps to fix it.
2026-08-21 09:03:15.441 [disk-space-monitor-1] WARN o.a.i.db.engine.StorageEngine:342 -
Disk space is insufficient. Path: D:\TimechoDB\data\datanode\data,
usage: 89.2%, threshold: 85.0%. System will switch to read-only mode.
2026-08-21 09:03:15.443 [disk-space-monitor-1] ERROR o.a.i.db.engine.StorageEngine:356 -
611: Disk space is insufficient. Triggering system read-only protection.
2026-08-21 09:03:15.445 [disk-space-monitor-1] WARN o.a.i.db.service.IoTDB:430 -
System is now in READ_ONLY mode. All write operations will be rejected.
To restore write capability: clean up disk space and execute 'SET SYSTEM TO RUNNING ON CLUSTER;'.
2026-08-21 09:05:22.118 [ClientPool-thread-3] ERROR org.apache.iotdb.db.writelog.WriteLogManager:178 -
Failed to write WAL: 600: System is read-only. Write operation rejected.
insert into root.sg_1.d_1(timestamp, s_1) values (2026-08-21T09:05:22.000+08:00, 42.5)4. Skills
| # | Skill Name | Description |
|---|---|---|
| 1 | timecho-cli-guide | Timecho CLI command usage guide. Used to resolve current command syntax, select safe parameters, perform validation, and avoid inventing commands, parameters, or database configurations. |
| 2 | timecho-forecast | Forecast, plot, and save prediction results for CSV, TSV, or JSON time-series data with Timecho CLI, with support for history covariates, future covariates, and model selection. |
| 3 | timechoai-cli-guide | TimechoAI CLI usage guide. Used to check AI connectivity, manage API keys, execute implemented AI commands, inspect AI output, and confirm whether a capability is available. |
| 4 | timechodb-backup-restore | TimechoDB backup and restore, including schema export, TsFile backup, full and incremental strategies, PITR disaster recovery, and tree and table model handling. |
| 5 | timechodb-benchmark | Integrate iot-benchmark to automatically scale the test size by machine resources (write points per second, latency percentiles, mixed query load) and produce structured metrics. |
| 6 | timechodb-client-ref | TimechoDB or Apache IoTDB client integration reference, covering Java, JDBC, C++, Python, REST, Spring Boot, MyBatis, Go, C, and MQTT, as well as connection pooling and client troubleshooting. |
| 7 | timechodb-config-advisor | TimechoDB configuration advisory. Recommends key parameters such as memory, replicas, WAL, and Compaction based on CPU, memory, disk, and deployment topology, and compares the current configuration with the recommended one. |
| 8 | timechodb-config-manage | View, modify, and validate TimechoDB configuration, with support for --dry-run preview, immutable parameter interception, and high-risk operation confirmation. |
| 9 | timechodb-data-ops | Batch data operations, including executing SQL files, initializing test data, cleaning data, importing TsFiles, setting TTL, and configuring continuous queries. |
| 10 | timechodb-deploy-2active | TimechoDB dual-active deployment guide, covering two independent instances, bidirectional Pipe sync, breakpoint resume validation, activation, and license check. |
| 11 | timechodb-deploy-cluster | TimechoDB distributed cluster deployment, supporting 3C3D or custom Cn/Dn scale, including seed node join, multi-replica setup, and cross-node connectivity checks. |
| 12 | timechodb-deploy-docker | Deploy TimechoDB with Docker or Docker Compose, providing 1C1D, 1C2D, and 3C3D templates, plus persistent volumes, port mapping, and image version pinning. |
| 13 | timechodb-deploy-standalone | TimechoDB standalone deployment guide, supporting custom ports, paths, and memory parameters, with automatic validation of node running status and node count. |
| 14 | timechodb-development-guide | TimechoDB and Apache IoTDB application development guide, covering Java, JDBC, Python, C++, REST, tree/table model selection, connection lifecycle, read and write limits, and production troubleshooting. |
| 15 | timechodb-faq-diag | TimechoDB FAQ and fault diagnosis, including startup failures, connection rejection, OOM, replica inconsistency, WAL anomalies, and configuration errors, with semantic positioning based on ERROR/WARN logs. |
| 16 | timechodb-health-check | Perform read-only health inspections based on the inspection report Word template and generate a .docx report that preserves the original layout. |
| 17 | timechodb-knowledge-base | TimechoDB official user manual knowledge base, covering Release Notes, configuration items, error codes, tree/table model differences, SQL syntax, deployment and operations guides, and version comparison. |
| 18 | timechodb-log-analyze | Analyze ERROR/WARN patterns in TimechoDB logs, including OOM, GC, WAL flush, Compaction anomalies, thread surges, and connection pool exhaustion, and generate a summary report. |
| 19 | timechodb-monitor-integrate | Integrate Prometheus and Grafana monitoring, including enabling metric reporters, configuring ports, importing TimechoDB dashboards, and correlating OS metrics. |
| 20 | timechodb-node-ops | Node operations, including scaling, data migration, Region balancing, hot node draining, ConfigNode/DataNode start and stop order, and jstack thread and deadlock analysis. |
| 21 | timechodb-pipe-sync | Configure Pipe data sync, including station-to-center, full/incremental/cascade sync, air-gap penetration, encrypted compression, dual-active mirroring, and sync lag monitoring. |
| 22 | timechodb-rn-issue-resolver | Convert RN or Issue text into executable operations, including parameter adjustments, config patching, and reproduction steps, for requirement validation and issue reproduction. |
| 23 | timechodb-schema-gen | Generate conservative TimechoDB or Apache IoTDB Tree/Table schema DDL from an explicit device hierarchy or table model, including CREATE DATABASE, CREATE TIMESERIES, CREATE TABLE, and TAG/FIELD mapping. |
| 24 | timechodb-sql-dev | Develop, review, and debug TimechoDB or Apache IoTDB SQL with explicit Tree/Table dialect boundaries, covering path binding, aggregation, time predicates, function selection, and rewrites of parser or runtime failures. |
| 25 | timechodb-test-gen | Generate test cases from the knowledge base, including deployment verification, RN defects, and performance regression tests, and output test steps, expected results, and reports. |
| 26 | timechodb-text2sql | Convert natural-language requests into one executable TimechoDB or Apache IoTDB SQL statement, supporting Tree/Table dialect selection, path binding, filters, aggregations, and SQL validation. |
| 27 | timechodb-tier-storage | Multi-tier storage design, including hot (SSD), warm, and cold (object storage/HDD) auto-tiering, access frequency rules, query scheduling logic, and parameter tuning. |
| 28 | timechodb-tree-table-guide | Explain and select TimechoDB or Apache IoTDB Tree versus Table models, covering hierarchical path design, TAG/ATTRIBUTE/FIELD mapping, device and measurement boundaries, and schema migration planning. |
| 29 | timechodb-upgrade-rollback | TimechoDB upgrade and rollback guide, including target version download, config and metadata backup, rolling or stop upgrade, RN compatibility validation, and rollback commands on failure. |
5. Command Overview
timecho-cli
├── activate Activation management (machine-code/apply/status)
├── ai TimechoAI services
│ ├── ping Test AI connectivity and authentication
│ ├── dimensions List data quality evaluation dimensions
│ ├── evaluate Evaluate time-series table data quality
│ └── forecast Sequence forecasting (single/multiple targets)
├── completion Shell completion (bash/zsh/fish/powershell)
├── config Configuration management (get/set/diff/tune/schema)
├── ctx Connection Context management (add/list/show/use/update/remove/discover)
├── data Data import and export
│ ├── import
│ │ ├── csv Bulk CSV import (Tree/Table mapping)
│ │ └── tsfile LOAD a server-side TsFile path
│ └── export
├── diagnose Redacted remote and local diagnostic bundle
├── setup
│ └── skills Install Skills for Claude/Codex/OpenClaw/Hermes
├── sql Execute SQL (tree/table dialects; supports -f/--stdin)
├── status Health summary (version/activation/cluster/Region/disk)
└── version Display the CLI versionNote: TsFile export is not a native CLI operation. Use the
tsfile-backupscript or the Pipetsfile-local-sink. AI commands do not use a database Context.
For detailed command usage, see TimechoCLI Command Examples.
6. Global Parameters
All subcommands can be prefixed with the following parameters:
| Parameter | Short Form | Description |
|---|---|---|
| --ctx | - | Specify the database connection Context (not supported by ai commands) |
| --help | -h | Display command help |
| --json | - | Output a stable JSON Envelope containing fields such as api_version, kind, and data |
| --no-color | - | Disable colored output |
| --non-interactive | - | Disable interactive input for automation such as CI/CD scripts |
| --output | -o | Specify the output format: human (default), json, or csv |
| --sql-dialect | - | Temporarily override the database SQL dialect with tree or table (not supported by ai commands) |
| --timeout | - | Set the overall command timeout, such as 30s, 2m, or 1h |
| --trace-id | - | Attach a custom Trace ID to structured output for request tracing |
| --verbose | -v | Enable detailed diagnostic logs on stderr |
| --yes | -y | Confirm high-risk operations without interactive confirmation |
Notes:
--jsonis equivalent to selecting JSON output; do not explicitly pass in conflicting--output humanor--output csvat the same time.--output csvis intended primarily forsqlqueries that return result sets. Non-query SQL does not support CSV output.- Global parameters can appear before or after subcommands. For readability, team scripts should place them before the top-level command.
--non-interactiveis only responsible for suppressing prompts and does not automatically consent to high-risk operations;--yesshould still be passed in when authorization is required.--yesonly confirms write operations; it does not bypass parameter, security, version, or checksum validation.- Diagnostic information for
--verboseis written to stderr and should not be mixed with JSON/CSV stdout. aireuses global output, timeout, automation, and diagnostic parameters, but rejects explicit--ctxand--sql-dialectparameters.
6.1 Global Parameter Examples
timecho-cli --ctx prod sql "show version"timecho-cli --ctx prod --json statustimecho-cli --ctx prod --timeout 30s sql "show cluster"timecho-cli \
--ctx prod \
--json \
--non-interactive \
--trace-id request-20260721-001 \
statusTemporarily override the SQL dialect:
timecho-cli --ctx prod --sql-dialect table sql "show databases"Enable verbose logging:
timecho-cli --ctx prod --verbose diagnoseJSON conflicts with an explicit output format, and the following fails before connecting to the database:
timecho-cli --json --output csv version7. MCP Server
IoTDB MCP Server is a server implementation based on Model Context Protocol (MCP) that provides database interaction and business intelligence capabilities through IoTDB. The server supports the execution of SQL queries and can interact with IoTDB through different SQL dialects (tree model and table model).
MCP is open source and can be downloaded directly from GitHub iotdb-mcp-server.