TimechoCLI

About 32 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 Timecho AI 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 Timecho AI, 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. Download and Install

2.1 Requirements

Target machine: Linux/macOS/Windows (amd64, arm64)
Zero-dependency static binary (CGO_ENABLED=0); Node.js, Python, and JRE are not required
The RPC port of the target TimechoDB instance must be reachable (default: 6667)

2.2 Installation Methods

Method A: Quick installation through an Agent

Install TimechoCLI for me: https://timecho.com/timecho-cli/installation-guide.md

Method B: Install globally with npm (Windows, macOS, and Linux)

npm install -g @timecho/timecho-cli

2.3 Verification

timecho-cli version
timecho-cli --help

3. Command Overview

timecho-cli
├── activate         Activation management (machine-code/apply/status)
├── ai               Timecho AI 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 version

Note: TsFile export is not a native CLI operation. Use the tsfile-backup script or the Pipe tsfile-local-sink. AI commands do not use a database Context.

4. 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:

--json is equivalent to selecting JSON output; do not explicitly pass in conflicting --output human or --output csv at the same time.
--output csv is intended primarily for sql queries 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-interactive is only responsible for suppressing prompts and does not automatically consent to high-risk operations; --yes should still be passed in when authorization is required.
--yes only confirms write operations; it does not bypass parameter, security, version, or checksum validation.
Diagnostic information for --verbose is written to stderr and should not be mixed with JSON/CSV stdout.
ai reuses global output, timeout, automation, and diagnostic parameters, but rejects explicit --ctx and --sql-dialect parameters.

4.1 Global Parameter Examples

timecho-cli --ctx prod sql "show version"

timecho-cli --ctx prod --json status

timecho-cli --ctx prod --timeout 30s sql "show cluster"

timecho-cli \
  --ctx prod \
  --json \
  --non-interactive \
  --trace-id request-20260721-001 \
  status

Temporarily override SQL dialect:

timecho-cli --ctx prod --sql-dialect table sql "show databases"

Turn on detailed logging:

timecho-cli --ctx prod --verbose diagnose

JSON conflicts with the explicit output format, and the following fails before connecting to the database:

timecho-cli --json --output csv version

5. Skills

#	Skill Name	Description
1	`timecho-cli-guide`	Unified timecho-cli command guide: must be read before running/writing/interpreting/debugging/validating/automating any timecho-cli command, subject to the runtime `--help`, without inventing flags and parameters.
2	`timecho-forecast`	Time series prediction and plotting: Predicting CSV/TSV/JSON through timecho-cli, supporting prediction steps, history/future covariates, model selection, result saving and chart generation.
3	`timechoai-cli-guide`	Timecho AI Command Guide: `ai ping`/`ai forecast`/`ai key` usage, connectivity check, API key management, output and credential behavior.
4	`timechodb-backup-restore`	Backup and recovery: schema export, TsFile backup, full/incremental strategy, PITR disaster recovery walkthrough, tree/table model processing.
5	`timechodb-benchmark`	Benchmark: Integrates iot-benchmark to automatically scale machine resources (write points per second, delay percentiles, hybrid queries) to output structured metrics.
6	`timechodb-client-ref`	Client access reference: Selection and review of Java, JDBC, C++, Python, rest, Spring Boot, MyBatis, Go, C, MQTT and other accesses.
7	`timechodb-config-advisor`	Configuration Consulting: Recommend and compare key parameters by CPU/memory/disk versus deployment scenario (1C1D/3C3D/dual-active).
8	`timechodb-config-manage`	Configuration management: View/modify/validate configurations, support `--dry-run` preview, immutable parameter interception, high-risk operation confirmation.
9	`timechodb-data-ops`	Data O&M: batch execute SQL, initialize test data, data cleanup, import TsFile, TTL, continuous query, etc.
10	`timechodb-deploy-2active`	Dual live deployment: two instances of bi-directional pipe synchronization, breakpoint continuation verification.
11	`timechodb-deploy-cluster`	Cluster deployment: 3C3D or custom Cn/Dn scale, seed join, multiple replicas, cross-node connectivity.
12	`timechodb-deploy-docker`	Docker deployment: 1C1D/1C2D/3C3D Compose templates, persistent volumes, port mappings, version locks.
13	`timechodb-deploy-standalone`	Stand-alone deployment: 1C1D one-click deployment, custom ports/paths/memory, automatic verification of node operational status.
14	`timechodb-faq-diag`	Troubleshooting: question-and-answer root cause analysis for startup failure, connection rejection, OOM, copy inconsistency, Wal exception, misconfiguration, etc.
15	`timechodb-health-check`	Deep Health Checks: Disk, CPU, Memory, Wal Backlog, Write Throughput, Pipe Delay, TsFile Count, Compaction Queue.
16	`timechodb-knowledge-base`	Knowledge base: Official user manual, check Release Notes, configuration items, error codes, tree table differences, SQL syntax, deployment operations documentation, and compare local and latest versions.
17	`timechodb-log-analyze`	Log analysis: error/warn analysis such as OOM, GC, Wal flush, Compaction exception, thread surge, connection pool depletion, etc. is reported.
18	`timechodb-monitor-integrate`	Monitoring integration: Prometheus + Grafana, open metrics, configure ports, import dashboards, associate OS metrics.
19	`timechodb-node-ops`	Node operation and maintenance: scaling capacity, data migration, Region equalization, hot node drainage, start/stop sequence, jstack deadlock diagnosis.
20	`timechodb-pipe-sync`	Pipe data synchronization: station to center, full/incremental/cascading, gate penetration, encryption compression, dual live mirroring, latency monitoring.
21	`timechodb-rn-issue-resolver`	Requirements/Issue Resolution: Turn Release Notes or Issues into actionable actions (parameter adjustments, patches, recurrence steps).
22	`timechodb-schema-gen`	Schema generation: spanning tree/table DDL (create database, create timeseries, etc.) by device hierarchy or table model.
23	`timechodb-sql-dev`	SQL Development: Develop/review/debug SQL, clarify tree-table dialect boundaries, query templates, path bindings, aggregations, etc.
24	`timechodb-test-gen`	Test generation: Generate deployment validation, RN defects, performance regression test cases from the knowledge base (step + expected + report).
25	`timechodb-text2sql`	Natural Language to SQL: Turns a natural language request into an executable SQL, handling tree/table dialects, path bindings, time semantics.
26	`timechodb-tier-storage`	Tiered storage: hot (SSD)→→ warm\ (object storage/HDD) automatic tiering, access frequency rules, query scheduling and parameter tuning.
27	`timechodb-tree-table-guide`	Tree Table Model Guide: Tree Model vs. Table Model Selection, Hierarchical Path Design, tag/attribute/field Mappings.
28	`timechodb-upgrade-rollback`	Upgrade and rollback: download target version, backup configuration and metadata, scroll/downtime upgrade, compatibility check, rollback.

6. LLM Interaction Examples

The following prompts can be sent directly to an LLM:

6.1 Prerequisites

6.1.1 Install the CLI and Add Skills

Install TimechoCLI for me: https://timecho.com/timecho-cli/installation-guide.md
Update TimechoCLI for me: https://timecho.com/timecho-cli/installation-guide.md

6.1.2 One-click Standalone TimechoDB Deployment and Activation

Deploy a standalone (1C1D) TimechoDB instance under D:\timecho using D:\TimechoDB\timechodb-2.0.10.2-bin.zip. After deployment, activate the license and verify that the service is available.

6.2 Scenarios

6.2.1 Scenario 1: Start TimechoDB

Check whether my TimechoDB service is running. If it is not, start it and verify that the service is available.

6.2.2 Scenario 2: Connection Check, Deep Health Check, and Diagnostic Bundle

Perform a comprehensive TimechoDB inspection. Check the overall health status and look for disk, memory, WAL, or Compaction issues, then generate an inspection report.

6.2.3 Scenario 3: Configuration Check and Tuning

Compare the current TimechoDB configuration with the recommended values. Suggest how to tune key parameters such as memory, WAL, and Compaction for this machine's resources, but do not apply any changes yet.

6.2.4 Scenario 4: SQL/Text2SQL Development and Data Import/Export

Import 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."

6.2.5 Scenario 5: SQL Development and OBJECT Data Import

Create the object_test database in the Table model, then create the device_obj table.

Use 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 under D:\TimechoDB into the device_obj table.

6.2.6 Scenario 6: Troubleshooting and Log Analysis

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 270139392

My 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:00

My 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)

7. Example of command line usage

7.1 Connection Context Management

7.1.1 `ctx add`: Add a Context

Basic Grammar

timecho-cli ctx add NAME [flags]

Add Remote Tree Schema Database

timecho-cli ctx add prod \
  --host db.example.com \
  --port 6667 \
  --user root \
  --dialect tree

If it is currently an interactive terminal, the command will prompt for the password, and you can skip saving it by entering it directly in the carriage, or you can enter it via stdin and save it to the system Keychain:

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli ctx add prod \
    --host db.example.com \
    --port 6667 \
    --user root \
    --dialect tree \
    --password-stdin

No password prompt appears in --json or --non-interactive mode. If --password-stdin is not used, the Context can still be created, but its credential status will be missing. Subsequent database commands must obtain the password from an environment variable or Keychain.

Add Table Mode Context

timecho-cli ctx add table-prod \
  --host db.example.com \
  --port 6667 \
  --user root \
  --dialect table \
  --database telemetry

To add the local installation context Linux:

timecho-cli ctx add local-dev \
  --kind local \
  --local /opt/timecho \
  --host 127.0.0.1 \
  --port 6667

Windows PowerShell:

timecho-cli ctx add local-dev `
  --kind local `
  --local "D:\timecho" `
  --host 127.0.0.1 `
  --port 6667

Add Cluster Node

timecho-cli ctx add cluster-prod \
  --host db1.example.com \
  --port 6667 \
  --nodes db1.example.com:6667,db2.example.com:6667,db3.example.com:6667 \
  --user root

It is also possible to specify repeatedly:

timecho-cli ctx add cluster-prod \
  --nodes db1.example.com:6667 \
  --nodes db2.example.com:6667 \
  --nodes db3.example.com:6667

Configure query parameters

timecho-cli ctx add prod \
  --host db.example.com \
  --connect-timeout 10s \
  --query-timeout 2m \
  --fetch-size 4096 \
  --rpc-compression

Add TLS Context

timecho-cli ctx add prod-tls \
  --host db.example.com \
  --port 6667 \
  --tls \
  --ca /etc/timecho/tls/ca.pem \
  --server-name db.example.com

Add Mutual TLS Context

timecho-cli ctx add prod-mtls \
  --host db.example.com \
  --port 6667 \
  --tls \
  --ca /etc/timecho/tls/ca.pem \
  --cert /etc/timecho/tls/client.pem \
  --key /etc/timecho/tls/client-key.pem \
  --server-name db.example.com

7.1.2 `ctx list`: List Contexts

timecho-cli ctx list

JSON Output:

timecho-cli ctx list --json

7.1.3 `ctx show`: Show a Context

To view the current context:

timecho-cli ctx show

To view a specified context:

timecho-cli ctx show prod

JSON Output:

timecho-cli ctx show prod --json

The output does not return the plaintext password saved in the Keychain.

7.1.4 `ctx use`: Switch the Current Context

timecho-cli ctx use prod

After switching, subsequent commands can omit --ctx prod:

timecho-cli status
timecho-cli sql "show version"

7.1.5 `ctx update`: Update a Context

Modify only the explicitly passed parameters.

Modify host and port

timecho-cli ctx update prod \
  --host new-db.example.com \
  --port 6668

Change username and password

printf '%s\n' "$NEW_TIMECHODB_PASSWORD" |
  timecho-cli ctx update prod \
    --user admin \
    --password-stdin

Modify SQL dialect

timecho-cli ctx update prod \
  --dialect table \
  --database telemetry

Start_tls

timecho-cli ctx update prod \
  --tls \
  --ca /etc/timecho/tls/ca.pem \
  --server-name db.example.com

Modify Timeout and Fetch Size

timecho-cli ctx update prod \
  --connect-timeout 20s \
  --query-timeout 5m \
  --fetch-size 8192

Modify Cluster Node List

timecho-cli ctx update prod \
  --nodes db1.example.com:6667,db2.example.com:6667

7.1.6 `ctx remove`: Remove a Context

Only delete the contextual configuration, do not delete the Keychain password, and do not require confirmation:

timecho-cli ctx remove old-prod

Also deleting passwords saved in the Keychain is a confirmation action:

timecho-cli ctx remove old-prod \
  --delete-secret \
  --yes

--yes can be omitted in interactive terminals and acknowledged as prompted; --non-interactive must be explicitly passed in JSON or --yes mode.

7.1.7 `ctx discover`: Discover Local Installations

Automatic search for common installation directories:

timecho-cli ctx discover

Specify candidate root directory:

timecho-cli ctx discover --root /opt

Specify multiple directories:

timecho-cli ctx discover \
  --root /opt/timecho \
  --root /srv/iotdb

Windows:

timecho-cli ctx discover `
  --root "C:\Timecho" `
  --root "D:\Apache-IoTDB"

JSON Output:

timecho-cli ctx discover --json

ctx discover only finds the installation directory and does not automatically modify the Context configuration.

7.2 SQL execution

7.2.1 Direct execution of SQL

timecho-cli --ctx prod sql "show version"

timecho-cli --ctx prod sql "show cluster"

timecho-cli --ctx prod sql "select * from root.sg.d1 limit 100"

7.2.2 JSON output

timecho-cli --ctx prod --json sql "show version"

timecho-cli --ctx prod --output json sql \
  "select * from root.sg.d1 limit 100"

7.2.3 CSV output

Output to terminal:

timecho-cli --ctx prod --output csv sql \
  "select * from root.sg.d1 limit 100"

Redirect to file:

timecho-cli --ctx prod --output csv sql \
  "select * from root.sg.d1" > result.csv

7.2.4 Executing from a SQL file

To create a SQL file:

select * from root.sg.d1 limit 100

Performed by:

timecho-cli --ctx prod sql --file query.sql

ABBREVATION

timecho-cli --ctx prod sql -f query.sql

7.2.5 Execute from stdin

printf '%s\n' "show version" |
  timecho-cli --ctx prod sql --stdin

Input from file pipeline:

cat query.sql |
  timecho-cli --ctx prod sql --stdin

PowerShell:

Get-Content .\query.sql -Raw |
  timecho-cli --ctx prod sql --stdin

7.2.6 Force Query Execution

When SQL cannot automatically determine the type:

timecho-cli --ctx prod sql \
  --query \
  "show cluster"

7.2.7 Force Non-query Execution

timecho-cli --ctx prod sql \
  --non-query \
  "create database root.demo"

7.2.8 Using the Table Dialect

Use the Table dialect configured in Context:

timecho-cli --ctx table-prod sql "show databases"

Temporary overlay dialect:

timecho-cli \
  --ctx prod \
  --sql-dialect table \
  sql "show databases"

7.2.9 Entering the database password via stdin

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod \
    sql "show version" \
    --password-stdin

7.2.10 Setting a timeout

timecho-cli --ctx prod \
  --timeout 2m \
  sql "select * from root.sg.**"

7.2.11 Safely Display BLOB Binary Columns

Queries such as READ_OBJECT(...) return BLOB. By default, human mode displays only a safe size summary and does not write arbitrary binary bytes directly to the terminal:

timecho-cli --ctx table-prod sql \
  "select read_object(file_data) from object_test where device_id='pile-img-001'"

When copyable content is required, explicitly select Base64 or Hexadecimal:

timecho-cli --ctx table-prod sql \
  --binary-encoding base64 \
  "select read_object(file_data) from object_test where device_id='pile-img-001'"

timecho-cli --ctx table-prod sql \
  --binary-encoding hex \
  "select read_object(file_data) from object_test where device_id='pile-img-001'"

When encoding is explicitly selected, the binary values in the human and CSV outputs are prefixed with base64: or hex:;

Without an explicit encoding, human output continues to show the size summary. Binary values in JSON query output are encoded strings without a prefix; the column type and encoding are reported in data.types and data.binary_encoding. JSON and CSV default to Base64 when no encoding is specified. --binary-encoding accepts only base64 or hex.

SQL commands only allow one input source: location parameter, --file or --stdin, and cannot be used at the same time.
Only one SQL is allowed for a single call; multi-statement input is rejected.
--query and --non-query are mutually exclusive.
--stdin and --password-stdin cannot share stdin.
Generic sql command disables execution of activation SQL; database activation must use activate apply.

7.3 CSV Data Import

7.3.1 `data import csv`: Import official Tree CSV

CSV example

Time,root.demo.device1.temperature,root.demo.device1.status
2026-07-21T08:00:00Z,25.1,true
2026-07-21T08:01:00Z,25.3,true
2026-07-21T08:02:00Z,25.7,false

Import From:

timecho-cli --ctx prod data import csv data.csv

Specify the batch size:

timecho-cli --ctx prod data import csv data.csv \
  --batch-size 5000

7.3.2 Allow a Limited Number of Invalid Rows

timecho-cli --ctx prod data import csv data.csv \
  --max-bad-rows 10

7.3.3 Write Invalid Rows to a File

timecho-cli --ctx prod data import csv data.csv \
  --max-bad-rows 10 \
  --error-file rejected.csv

7.3.4 Importing Table Data Using Mapping

Raw CSV:

ts,host,region,temperature,online
2026-07-21T08:00:00Z,server-01,beijing,25.1,true
2026-07-21T08:01:00Z,server-02,shanghai,26.3,true

mapping.yaml:

dialect: table
timeColumn: ts
database: telemetry
table: server_metrics
columns:
  - name: host
    target: host
    category: TAG
    type: STRING
  - name: region
    target: region
    category: TAG
    type: STRING
  - name: temperature
    target: temperature
    category: FIELD
    type: DOUBLE
  - name: online
    target: online
    category: FIELD
    type: BOOLEAN

Import From:

timecho-cli --ctx table-prod data import csv metrics.csv \
  --mapping mapping.yaml

7.3.5 Importing Tree Data Using Mapping

Raw CSV:

ts,temperature,status
2026-07-21T08:00:00Z,25.1,true
2026-07-21T08:01:00Z,25.3,false

tree-mapping.yaml:

dialect: tree
timeColumn: ts
device: root.demo.device1
columns:
  - name: temperature
    target: temperature
    type: DOUBLE
  - name: status
    target: status
    type: BOOLEAN

Import From:

timecho-cli --ctx prod data import csv device1.csv \
  --mapping tree-mapping.yaml

7.3.6 Entering the database password via stdin

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod data import csv data.csv \
    --password-stdin

7.3.7 Output Import Results as JSON

timecho-cli --ctx prod --json data import csv data.csv \
  --batch-size 1000 \
  --max-bad-rows 10 \
  --error-file rejected.csv

7.4 CSV Data Export

7.4.1 `data export csv`: Export to a File

timecho-cli --ctx prod data export csv \
  --sql "select * from root.demo.device1" \
  --out device1.csv

7.4.2 Export to stdout

timecho-cli --ctx prod data export csv \
  --sql "select * from root.demo.device1" \
  --out -

You can also omit --out and write to stdout by default:

timecho-cli --ctx prod data export csv \
  --sql "select * from root.demo.device1"

Redirect to file via shell:

timecho-cli --ctx prod data export csv \
  --sql "select * from root.demo.device1" > device1.csv

7.4.3 Exporting a Table Query

timecho-cli --ctx table-prod data export csv \
  --sql "select * from server_metrics limit 1000" \
  --out server-metrics.csv

7.4.4 Export BLOB Columns

Binary values in CSV default to Base64 with the base64: prefix; hexadecimal can also be selected:

timecho-cli --ctx table-prod data export csv \
  --sql "select read_object(file_data) from object_test" \
  --binary-encoding hex \
  --out object-content.csv

The cell now uses the hex: prefix. --binary-encoding accepts only base64 or hex.

If you need to restore an original object file, do not go through the CSV, use the data export object in the next section.

7.4.5 Entering the database password via stdin

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod data export csv \
    --sql "select * from root.demo.device1" \
    --out device1.csv \
    --password-stdin

CSV cannot be used with JSON output mode when writing to stdout.

7.5 OBJECT File Import and Export

OBJECT is a TimechoDB Enterprise Edition Table model capability. Before importing, confirm the database version, license status, target table DDL, all TAG columns, and the OBJECT FIELD column. Do not confuse the BLOB type in Apache IoTDB Community Edition with the OBJECT type in TimechoDB Enterprise Edition.

7.5.1 `data import object`: Write a Local File

The following command writes a local normal file to the same Table line in 4 MiB (default) segments and sets the EoF in the last segment:

timecho-cli --ctx table-prod data import object ./photo.png \
  --table telemetry.object_test \
  --object-column file_data \
  --timestamp 1700000000000 \
  --tag device_id=pile-img-001 \
  --tag file_type=image/png \
  --verify

Rules and boundaries:

The Context must use the table dialect. --table accepts table or database.table. When database.table is used, that database is used for this import connection.
--timestamp is a required millisecond timestamp. Repeat --tag name=value for each TAG column. --object-column identifies the OBJECT FIELD column.
--chunk-size defaults to 4194304 bytes and allows a range of 1 to 256 MiB.
--verify is enabled by default. After writing, the CLI reads the file back in chunks and compares its byte count and SHA-256 digest. Use --verify=false only when skipping verification is explicitly acceptable.
Local verification only accepts normal documents. If a segment fails to be written in the middle, the segments that have been written by the server cannot be automatically rolled back by the CLI; the target row should be checked or deleted before deciding whether to retry.

Example of JSON automation:

timecho-cli --ctx table-prod --json --non-interactive data import object ./photo.png \
  --table telemetry.object_test \
  --object-column file_data \
  --timestamp 1700000000000 \
  --tag device_id=pile-img-001

7.5.2 `data export object`: Restore the Original File

A single query must return exactly one row, one column, non-null blob via READ_OBJECT(...):

timecho-cli --ctx table-prod data export object \
  --sql "select read_object(file_data) from object_test where device_id='pile-img-001' and time=1700000000000" \
  --out ./photo-restored.png

Large objects can use chunked query templates that contain only one {{offset}} and one {{length}} placeholder:

timecho-cli --ctx table-prod data export object \
  --sql-template "select read_object(file_data, {{offset}}, {{length}}) from object_test where device_id='pile-img-001' and time=1700000000000" \
  --chunk-size 4194304 \
  --out ./photo-restored.png

The export must use --out FILE to disallow writing the original binary to stdout. Conflicts are returned by default when the target already exists; only explicitly pass in --force to replace it. The CLI first writes a temporary file with the same directory, and then releases it atomically after the complete success, and returns the number of bytes and SHA-256; a query failure will not release the half-target file.

7.6 TsFile Import

7.6.1 `data import tsfile`

timecho-cli --ctx prod data import tsfile \
  "/data/import/2026-07-21.tsfile"

Windows database server side path:

timecho-cli --ctx prod data import tsfile `
  "D:\timecho-data\import\2026-07-21.tsfile"

JSON Output:

timecho-cli --ctx prod --json data import tsfile \
  "/data/import/2026-07-21.tsfile"

Enter database password via stdin:

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod data import tsfile \
    "/data/import/2026-07-21.tsfile" \
    --password-stdin

The parameter is the ** path that the database server can access **, not the client local path that executes the CLI.
TsFile export is not supported in the first version of the CLI.

7.7 Database activation

7.7.1 `activate machine-code`: Query the Machine Code

timecho-cli --ctx prod activate machine-code

JSON Output:

timecho-cli --ctx prod --json activate machine-code

Enter database password via stdin:

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod activate machine-code \
    --password-stdin

7.7.2 `activate apply`: Apply the activation code

It is recommended to enter the activation code via stdin:

printf '%s' "$ACTIVATION_CODE" |
  timecho-cli --ctx prod activate apply --stdin

PowerShell:

$env:ACTIVATION_CODE |
  timecho-cli --ctx prod activate apply --stdin

Incoming directly via arguments:

timecho-cli --ctx prod activate apply \
  --code "YOUR-ACTIVATION-CODE"

JSON Output:

printf '%s' "$ACTIVATION_CODE" |
  timecho-cli --ctx prod --json activate apply --stdin

It is recommended to use --stdin to prevent the activation code from entering the shell history.
After activation, the CLI queries the activation status again. The operation succeeds only if the resulting status is ACTIVATED.
The activation code and the database password cannot be read from the same stdin pipe at the same time; the database password should be saved in the Keychain in advance or provided via the TIMECHODB_PASSWORD environment variable.

7.7.3 `activate status`: Check Activation Status

timecho-cli --ctx prod activate status

JSON Output:

timecho-cli --ctx prod --json activate status

Enter database password via stdin:

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod activate status \
    --password-stdin

7.8 Local Configuration Management

The configuration command only manipulates the local installation directory, the explicit configuration file, or the context of kind: local, and does not modify the remote server file through SSH.

7.8.1 `config get`: Read Configuration

Read via Local Context

timecho-cli --ctx local-dev config get dn_rpc_port \
  --db-version 2.0.6.1

If the exact versionHint already exists in the Context configuration file, --db-version can be omitted. The current ctx add/update commands have no parameter for setting versionHint, so the normal CLI workflow should pass the database version explicitly.

Read by installation directory

timecho-cli config get dn_rpc_port \
  --home /opt/timecho \
  --db-version 2.0.6.1

Read by specifying Properties file

timecho-cli config get dn_rpc_port \
  --file /opt/timecho/conf/iotdb-system.properties \
  --db-version 2.0.6.1

Read all existing configuration items

timecho-cli config get \
  --all \
  --home /opt/timecho \
  --db-version 2.0.6.1

JSON Output:

timecho-cli --json config get \
  --all \
  --home /opt/timecho \
  --db-version 2.0.6.1

7.8.2 `config set`: Modify Configuration

Verify and View Diff Only

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --dry-run

Formally write interactive after confirmation:

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1

Non-interactive:

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --yes

Modify Time Accuracy

timecho-cli config set timestamp_precision ms \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --yes

Modify Data Directory

timecho-cli config set dn_data_dirs "/data1/iotdb,/data2/iotdb" \
  --file /opt/timecho/conf/iotdb-system.properties \
  --db-version 2.0.6.1 \
  --yes

Windows:

timecho-cli config set dn_data_dirs "D:\data1,D:\data2" `
  --home "D:\timecho" `
  --db-version 2.0.6.1 `
  --yes

On a formal write, Diff is displayed, a backup is created, concurrent changes are checked, and atomic replacements with the same directory are performed.

7.8.3 `config diff`: Compare Configuration Differences

Compared to Schema defaults

timecho-cli config diff \
  --home /opt/timecho \
  --db-version 2.0.6.1

Compare two Properties files

timecho-cli config diff \
  --file /opt/timecho/conf/iotdb-system.properties \
  --against ./iotdb-system.expected.properties \
  --db-version 2.0.6.1

JSON Output:

timecho-cli --json config diff \
  --home /opt/timecho \
  --db-version 2.0.6.1

7.8.4 `config tune`: View Tuning Recommendations

timecho-cli config tune \
  --home /opt/timecho \
  --db-version 2.0.6.1

JSON Output:

timecho-cli --json config tune \
  --home /opt/timecho \
  --db-version 2.0.6.1

The current implementation does not automatically apply tuning suggestions. Even when --apply is passed, it returns the stable error tune_apply_unavailable:

timecho-cli config tune \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --apply \
  --yes

The correct process is to review the recommendations and then use the config set for each confirmed configuration:

timecho-cli config tune \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --json

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --dry-run

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --yes

The built-in conservative Schema does not contain guessed hardware tuning values; recommendations is empty and returns an explanatory notice when there are no authoritative recommendations.

7.9 Configuration Schema Management

7.9.1 `config schema list`: List Schema fields

Use default database version:

timecho-cli config schema list

Specify database version:

timecho-cli config schema list \
  --db-version 2.0.6.1

JSON Output:

timecho-cli --json config schema list \
  --db-version 2.0.6.1

7.9.2 `config schema show`: View Schema

View the full Schema:

timecho-cli config schema show \
  --db-version 2.0.6.1

To view a specified configuration item:

timecho-cli config schema show \
  --db-version 2.0.6.1 \
  --key dn_rpc_port

View Time Precision Definitions:

timecho-cli config schema show \
  --db-version 2.0.6.1 \
  --key timestamp_precision

JSON Output:

timecho-cli --json config schema show \
  --db-version 2.0.6.1 \
  --key dn_rpc_port

7.9.3 `config schema update`: Update Schema

Update from default publishing address:

timecho-cli config schema update \
  --version 1.0.0

Specify a custom publishing address:

timecho-cli config schema update \
  --version 1.0.0 \
  --base-url https://downloads.example.com/timecho-schemas

JSON Output:

timecho-cli --json config schema update \
  --version 1.0.0

The CLI will download:

timechodb-schema-1.0.0.tar.gz
checksums.txt

and performs HTTPS, SHA-256, archive-path, and Schema-content validation. SHA-256 proves that the asset matches checksums.txt, but the current protocol does not claim to independently verify the publisher's identity or signature authenticity.

7.10 Database status check

7.10.1 `status`

Check Current Context:

timecho-cli status

Check the specified Context:

timecho-cli --ctx prod status

JSON Output:

timecho-cli --ctx prod --json status

Add timeout:

timecho-cli --ctx prod \
  --timeout 1m \
  status

Enter database password via stdin:

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod status \
    --password-stdin

Automated calls:

timecho-cli \
  --ctx prod \
  --json \
  --non-interactive \
  --timeout 30s \
  --trace-id health-check-001 \
  status

The status results contain checks such as database version, activation, cluster, Region, run variable, and disk occupancy, each of which returns:

pass
warn
fail
skip

The disk-usage check selects its query according to the Context's SQL dialect: the Tree model uses SHOW DISK_USAGE FROM root.**, while the Table model uses SELECT * FROM information_schema.table_disk_usage. The two model syntaxes cannot be mixed.

7.11 Diagnostic Commands

7.11.1 Remote Database Diagnostics

timecho-cli --ctx prod diagnose

JSON Output:

timecho-cli --ctx prod --json diagnose

7.11.2 Generate a Redacted Diagnostic Bundle

timecho-cli --ctx prod diagnose \
  --bundle ./timecho-diagnose.zip

7.11.3 Including local diagnostics based on remote diagnostics

timecho-cli --ctx local-dev diagnose \
  --local

7.11.4 Specifying the local installation directory

timecho-cli --ctx prod diagnose \
  --local \
  --home /opt/timecho

Windows:

timecho-cli --ctx prod diagnose `
  --local `
  --home "D:\timecho" `
  --bundle ".\timecho-diagnose.zip"

7.11.5 Perform both remote and local diagnostics

timecho-cli --ctx local-dev diagnose \
  --local \
  --bundle ./timecho-full-diagnose.zip

7.11.6 Enter the database password via stdin

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod diagnose \
    --password-stdin \
    --bundle ./timecho-diagnose.zip

The diagnosis results will desensitize sensitive information such as passwords, tokens, activation codes, etc. When a single acquisition item fails, the other acquisition items can continue and return partial success.
The current diagnose always parses the Context, creates a database Session, and performs a remote read-only query; --local and --home just append the local OS/JDK/configuration/log collection, not the offline diagnostic mode. Even if you only care about the local directory, there must be a database context that you can connect to.

7.12 Timecho AI

Timecho AI is a command group under the unified timecho-cli; there is no separate timechoai-cli executable. The currently available commands are ping, forecast, and key.

evaluate, dimensions are still registered in the migration contract, but have been hidden and returned service_not_open, which cannot be called or declared as supported by the available capabilities until the server is open; runtime help is the final command contract.

7.12.1 View AI Commands

timecho-cli ai --help
timecho-cli ai ping --help
timecho-cli ai forecast --help
timecho-cli ai key --help
timecho-cli ai key set --help
timecho-cli ai key show --help
timecho-cli ai key remove --help

7.12.2 Checking Connectivity and Authentication

export TIMECHOAI_API_KEY="your-api-key"
timecho-cli ai ping
timecho-cli ai ping --name World

Prioritize avoiding writing API Keys to shell history:

printf '%s\n' "$TIMECHOAI_API_KEY" |
  timecho-cli ai ping --api-key-stdin

7.12.3 Predicting a target sequence

Input supports CSV, TSV, and JSON. The Forecast contract accepts only one --input, and the same table contains both time, target, and optional covariate columns.

Parameter description:

--input: Enter a CSV, TSV, or JSON file.
--target: target column name, must and can only be passed once.
--time-col: time column name; automatically recognizes case-insensitive time columns when omitted.
--output-start-time: Predict the start time. Lines of time < boundary provide future covariates as historical data, lines of time >= boundary provide future covariates.
--output-length: number of predicted steps. When omitted, inferred by the service from future covariates or model defaults.
--model/--model-id: Specify a model or use a compatible alias.
--history-cov: columns of historical covariates, either repeated or separated by commas.
--future-cov: columns of future covariates, either repeatable or separated by commas, must be a subset of historical covariates.
--no-auto-adapt: Strictly rejects covariate length mismatches, without auto-completion or truncation.

timecho-cli ai forecast \
  --input ./data.csv \
  --target OT \
  --output-start-time 2024-01-17T00:00:00 \
  --output-length 96

For example, to explicitly specify a model:

timecho-cli --json ai forecast \
  --input ./data.json \
  --target load \
  --output-start-time 2024-01-17T00:00:00 \
  --model Timer-3.5 \
  --output-length 24

For example, to specify historical and future covariates:

timecho-cli ai forecast \
  --input ./data.csv \
  --target OT \
  --history-cov temperature,humidity \
  --history-cov holiday \
  --future-cov temperature,holiday \
  --output-start-time 2024-01-17T00:00:00 \
  --output-length 48 \
  --no-auto-adapt

Strict alignment of time columns in the Python SDK: Only ISO date or date-time formats are accepted; entire columns must use consistent precision, time zone representations, and fixed sampling intervals. Numeric timestamps, repetition times, mixed date/date times, mixed time zone representations, and irregular intervals all fail before networking.

The results can be output as human, JSON envelope, or pure CSV, or written to a CSV/JSON file:

timecho-cli --output csv ai forecast \
  --input ./data.csv \
  --target OT \
  --output-start-time 2024-01-17T00:00:00 \
  --output-length 96

timecho-cli ai forecast \
  --input ./data.csv \
  --target OT \
  --output-start-time 2024-01-17T00:00:00 \
  --output-length 96 \
  --out ./prediction.csv

timecho-cli --json ai forecast \
  --input ./data.csv \
  --target OT \
  --output-start-time 2024-01-17T00:00:00 \
  --out ./prediction.json

7.12.4 Managing the Timecho AI API Key

Only viewing the state does not echo the Key; setting/rotating takes precedence over reading from stdin, avoiding writing the key to command parameters or shell history:

printf '%s\n' "$TIMECHOAI_API_KEY" |
  timecho-cli ai key set --api-key-stdin

timecho-cli ai key show
timecho-cli ai key remove

ai key uses the service timecho-cli, account ai/api-key of the system Keychain.

For set, the resolution order is --api-key-stdin, TIMECHOAI_API_KEY, the compatible TIMER_CLIENT_API_KEY, and finally a secure prompt in an interactive terminal. JSON and non-interactive modes never prompt for input.

7.12.5 AI services not yet available

evaluate and dimensions are still recognizable by the installed binary, but have been hidden from ai --help and a direct call will return the typing error service_not_open. Do not use the following commands as a path to success or as a promise of availability until the server is open:

timecho-cli ai evaluate
timecho-cli ai dimensions

The AI-specific parameters are --api-key-stdin and --base-url. API keys are resolved from stdin, TIMECHOAI_API_KEY, the compatible TIMER_CLIENT_API_KEY, and finally the system Keychain. The root-level --timeout, --json, --output, --non-interactive, --verbose, and --trace-id parameters continue to apply. AI JSON uses the same timecho.com/timecho-cli/v1alpha1 API version as other commands, and Forecast uses the TimechoAIForecast kind.

MCPs are still not part of this migration, and do not construct MCP calls based on planning documents.

7.12.6 Using Forecast Agent Skill

Install the built-in 'timecho-forecast' workflow when the Agent is required → to automatically complete the Check Data → Selection Routing → Prediction → Drawing Report:

timecho-cli setup skills \
  --agent codex \
  --skill timecho-forecast \
  --dry-run

timecho-cli setup skills \
  --agent codex \
  --skill timecho-forecast

When this workflow is selected, the installer automatically adds timechoai-cli-guide and the shared timecho-cli-guide to the plan when they are present in the source. The workflow first checks the unified CLI root and AI help, runs only timecho-cli ai, and gives runtime --help precedence over static examples.

7.13 Skills Installation and Upload Package Export

timecho-cli setup skills undertakes two types of deliveries simultaneously:

** File system installation **: Codex, Claude, CodeBuddy, OpenClaw, Hermes, TRAE, TRAE CN;
** Upload package export **: TRAE Work, WorkBuddy.

The upload package export does not call the platform private API, nor does it automatically complete the remote import.

7.13.1 Default Behavior: Installing Binary Built-in Skills

When --source, --bundle, and --version are omitted, the installer uses the offline Skills catalog embedded in the binary:

timecho-cli setup skills

The default parameters are equivalent to:

--agent all --scope user

where all expands only to the following file system agents:

claude
codex
codebuddy
openclaw
hermes
trae
trae-cn

all does not include trae-work or workbuddy, avoiding accidental upload-package generation when no export directory is specified.

First, review the installation plan for the built-in catalog:

timecho-cli --json setup skills \
  --agent codex \
  --dry-run

Key fields in the output:

Field	Meaning
`source_mode: embedded`	Use binary built-in catalog
`bundle_version: embedded-<digest>`	catalog summary tag at build time
`sha256_verified: false`	External `checksums.txt` not used
`delivery_mode: filesystem`	Write directly to the Agent Skills directory
`delivery_status: planned`	Dry Run, generate plans only

The built-in catalog is a snapshot at build time and does not represent the latest version of the official website or remote release. Use --version when a release version needs to be specified.

7.13.2 Install from official release

When --version is specified without --source or --bundle, the installer downloads from a Release:

timechodb-skills-1.0.0.tar.gz
checksums.txt

To install into the Codex user directory:

timecho-cli setup skills \
  --version 1.0.0 \
  --agent codex

Use JSON output:

timecho-cli --json setup skills \
  --version 1.0.0 \
  --agent codex

Use a custom HTTPS Release address:

timecho-cli setup skills \
  --version 1.0.0 \
  --base-url https://downloads.example.com/timechodb-skills \
  --agent codex

The actual download address consists of the following parts:

<base-url>/<version>/timechodb-skills-<version>.tar.gz
<base-url>/<version>/checksums.txt

Remote downloads must use HTTPS and pass SHA-256 verification before secure unpacking. The checksum proves only that the asset matches checksums.txt; it is not an independent publisher-signature verification.

7.13.3 Installing from the repository Skills directory

Specification source directories can be used directly for local development:

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --dry-run

Formal installation after confirmation of plan:

timecho-cli setup skills \
  --source ./skills \
  --agent codex

Windows PowerShell:

timecho-cli setup skills `
  --source .\skills `
  --agent codex `
  --dry-run

The local directory mode does not require an external checksum, the output is:

source_mode: directory
sha256_verified: false
bundle_version: local

If both --source and --version are passed in, --version will only act as a local bundle tag in manifest and will not trigger a remote download:

timecho-cli setup skills \
  --source ./skills \
  --version dev-20260729 \
  --agent codex

--source and --bundle are mutually exclusive.

7.13.4 Installing from a Local Bundle

The local .tar.gz bundle must also provide checksums.txt containing the file digest:

timecho-cli setup skills \
  --bundle ./timechodb-skills-local.tar.gz \
  --checksums ./checksums.txt \
  --agent codex \
  --dry-run

Formal installation:

timecho-cli setup skills \
  --bundle ./timechodb-skills-local.tar.gz \
  --checksums ./checksums.txt \
  --agent codex

The output of this mode should contain:

source_mode: bundle
sha256_verified: true

Bash: Generate a test bundle containing only the Skill directory

stage="$(mktemp -d)"
cp -R skills/timechodb-* skills/timechoai-* skills/timecho-cli-guide skills/timecho-forecast "$stage/"
tar -czf timechodb-skills-local.tar.gz -C "$stage" .
sha256sum timechodb-skills-local.tar.gz > checksums.txt
rm -rf "$stage"

PowerShell: Generate a test bundle containing only the Skill directory

$stage = Join-Path $env:TEMP ("timechodb-skills-stage-" + [guid]::NewGuid())
New-Item -ItemType Directory -Path $stage | Out-Null

Get-ChildItem -LiteralPath .\skills -Directory |
  Where-Object { $_.Name -like 'timechodb-*' -or $_.Name -like 'timechoai-*' -or $_.Name -eq 'timecho-cli-guide' -or $_.Name -eq 'timecho-forecast' } |
  ForEach-Object {
    Copy-Item -LiteralPath $_.FullName -Destination $stage -Recurse
  }

tar -czf .\timechodb-skills-local.tar.gz -C $stage .

$asset = (Resolve-Path .\timechodb-skills-local.tar.gz).Path
$hash = (Get-FileHash -Algorithm SHA256 -LiteralPath $asset).Hash.ToLowerInvariant()
"$hash  $([IO.Path]::GetFileName($asset))" |
  Set-Content -LiteralPath .\checksums.txt -Encoding ascii

Remove-Item -LiteralPath $stage -Recurse -Force

Do not enter the entire repository root directly into the Skills bundle. If you are packaging from skills/ in this repository, it is also recommended to select only timechodb-*, timechoai-*, timecho-cli-guide and timecho-forecast specification directories to avoid mixing embed.go, test files or other non-Skill assets into the release package.

7.13.5 Select Section Skill

--skill can be repeated or separated by commas:

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --skill timechodb-knowledge-base \
  --skill timechodb-sql-dev

Forecast workflows can be selected individually:

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --skill timecho-forecast \
  --dry-run

Equivalence:

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --skill timechodb-knowledge-base,timechodb-sql-dev

Selecting a Skill that does not exist or has an illegal name format will fail before writing to the destination directory.

If a selected Skill calls timecho-cli in SKILL.md and the source contains timecho-cli-guide, the installer automatically adds that guide to the installation or export plan. When timecho-forecast is explicitly selected, timechoai-cli-guide is also added when present. This lets the Agent confirm the current syntax with runtime --help and the layered command references before running a dependent Skill. Unrelated Skills are not given the guide, and an explicitly selected guide is not duplicated.

Therefore, automation scripts should use plan.install and plan.export in dry-run or regular results as the final selection sets, rather than assuming they exactly match the --skill arguments.

7.13.6 File System Agent and Default Directory

User Scope

Agent	Target Directory
`claude`	`~/.claude/skills`
`codex`	`~/.agents/skills`
`codebuddy`	`~/.codebuddy/skills`
`openclaw`	`~/.openclaw/skills`
`hermes`	`~/.hermes/skills`
`trae`	`~/.trae/skills`
`trae-cn`	`~/.trae-cn/skills`

Example:

timecho-cli setup skills --agent claude
timecho-cli setup skills --agent codex
timecho-cli setup skills --agent codebuddy
timecho-cli setup skills --agent openclaw
timecho-cli setup skills --agent hermes
timecho-cli setup skills --agent trae
timecho-cli setup skills --agent trae-cn

Project Scope

Agent	Target Directory
`claude`	`<project>/.claude/skills`
`codex`	`<project>/.agents/skills`
`codebuddy`	`<project>/.codebuddy/skills`
`openclaw`	`<project>/.agents/skills`
`hermes`	`<project>/.agents/skills`
`trae`	`<project>/.trae/skills`
`trae-cn`	`<project>/.trae/skills`

Codex Project Level Installation:

timecho-cli setup skills \
  --agent codex \
  --scope project \
  --project-dir /workspace/my-project

Windows PowerShell:

timecho-cli setup skills `
  --agent codex `
  --scope project `
  --project-dir "D:\projects\my-project"

If --project-dir is omitted, the project scope uses the current working directory. Automation scripts are still recommended to explicitly pass in the project root.

OpenClaw project-level default multiplexing .agents/skills. To get to the OpenClaw native project directory:

timecho-cli setup skills \
  --agent openclaw \
  --scope project \
  --project-dir /workspace/my-project \
  --native-target

The goal will become:

<project>/skills

--native-target is only available for OpenClaw.

After a Hermes project-scope installation, if Hermes does not automatically discover the directory, the CLI prompts you to add the target directory to Hermes external_dirs.

7.13.7 Installing to Multiple File System Agents Simultaneously

--agent can be repeated or separated by commas:

timecho-cli setup skills \
  --source ./skills \
  --agent codex,claude,codebuddy \
  --scope project \
  --project-dir /workspace/my-project \
  --dry-run

Equivalence:

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --agent claude \
  --agent codebuddy \
  --scope project \
  --project-dir /workspace/my-project

The CLI generates a plan for all targets before starting the application on a per-target basis; however, current multi-target execution is not a cross-directory global transaction. If subsequent target writes fail, preamble targets that have succeeded are not automatically rolled back as a whole.

7.13.8 Overwrite the target directory of a file system agent

--target-dir only works with one file system agent:

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --target-dir ./tmp/codex-skills \
  --dry-run

The following combinations will fail:

timecho-cli setup skills \
  --agent codex,claude \
  --target-dir ./shared-skills

The CLI does not implicitly reuse a custom directory to multiple Agents.

7.13.9 Dry Run, Conflict and `--force`

Dry Run generates only plans and does not create Skill, manifest, backup, or export packages:

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --dry-run

The file system installation uses the following under the target directory:

.timechodb-skills-manifest.json

Record the bundle version and file SHA-256.

If the contents of the installed Skill and the manifest record are inconsistent, the conflict is reported by default and user modifications are preserved:

timecho-cli setup skills \
  --source ./skills \
  --agent codex

When substitution is expressly permitted:

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --force

The current --force may also replace the Skill directory with the same name but not managed by manifest. You must run --dry-run and confirm the target path before using it.

An installation of a single file system target will staging the target file system and attempt to roll back if the Skill/manifest commit fails.

7.13.10 Exporting Upload Packages for TRAE Work

TRAE Work is an upload target and must be explicitly selected and provided with --export-dir:

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work \
  --export-dir ./dist/trae-work-skills \
  --dry-run

Formal Export zip:

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work \
  --export-dir ./dist/trae-work-skills \
  --package-format zip

To export the .skill package:

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work \
  --export-dir ./dist/trae-work-skills \
  --package-format skill

auto currently resolves to zip for TRAE Work.

7.13.11 Exporting an upload package for WorkBuddy

timecho-cli setup skills \
  --source ./skills \
  --agent workbuddy \
  --export-dir ./dist/workbuddy-skills

WorkBuddy currently only accepts zip:

timecho-cli setup skills \
  --source ./skills \
  --agent workbuddy \
  --export-dir ./dist/workbuddy-skills \
  --package-format zip

The following will fail:

timecho-cli setup skills \
  --source ./skills \
  --agent workbuddy \
  --export-dir ./dist/workbuddy-skills \
  --package-format skill

7.13.12 Workspace Level Upload Package

The workspace scope is used only for TRAE Work and WorkBuddy upload-package exports and requires --workspace:

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work \
  --scope workspace \
  --workspace telemetry-team \
  --export-dir ./dist/trae-workspace-skills

timecho-cli setup skills \
  --source ./skills \
  --agent workbuddy \
  --scope workspace \
  --workspace telemetry-team \
  --export-dir ./dist/workbuddy-workspace-skills

File system agent does not accept workspace scope; upload type agent does not accept project scope.

7.13.13 Export for both TRAE Work and WorkBuddy

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work,workbuddy \
  --export-dir ./dist/upload-skills

When two upload agents are selected at the same time, the output is written separately:

./dist/upload-skills/trae-work
./dist/upload-skills/workbuddy

Because WorkBuddy does not accept .skill, the default auto or explicit zip should be used when exporting:

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work,workbuddy \
  --export-dir ./dist/upload-skills \
  --package-format zip

7.13.14 Perform both file system installation and upload package export

Mixed targets must provide --export-dir. Since the scope accepted by both the file system and the upload destination is only user, hybrid execution should use the default user scope:

timecho-cli setup skills \
  --source ./skills \
  --agent codex,workbuddy \
  --export-dir ./dist/workbuddy-skills \
  --dry-run

Formal Execution:

timecho-cli setup skills \
  --source ./skills \
  --agent codex,workbuddy \
  --export-dir ./dist/workbuddy-skills

7.13.15 Uploading Package Content and Status

Each Skill generates a separate package, the package root directory directly contains:

SKILL.md
scripts/       # Only when present in the original Skill
references/    # Only when present in the original Skill
assets/        # Only when present in the original Skill

The export directory also contains:

export-manifest.json
checksums.txt
IMPORT.md
<skill-name>.zip or <skill-name>.skill

After a normal export, the status is:

delivery_mode: import-package
delivery_status: awaiting-import

This means that the package has been generated and still needs to be manually imported in TRAE Work or WorkBuddy. The current implementation does not perform automatic browser uploads, private API calls, remote status queries, start-stop or rollback.

Existing export directories managed by export-manifest.json are skipped when their contents are identical. Different contents produce a conflict and can be replaced with --force. A non-empty directory without a manifest is unmanaged and will not be overwritten, even with --force.

7.13.16 Agent name and alias

Official name:

claude
codex
codebuddy
openclaw
hermes
trae
trae-cn
trae-work
workbuddy
all

The following compatible aliases are currently reserved:

Input	Normalized Results
`claude-code`	`claude`
`code-buddy`	`codebuddy`
`traework`	`trae-work`
`work-buddy`	`workbuddy`

Names are not case-sensitive, but it is recommended that documents and automation scripts always use formal lowercase names.

7.13.17 Security and Conduct Boundaries

Skill names can only contain lowercase letters, numbers, and hyphens, are 1–64 in length, and cannot begin or end with a hyphen.
The directory name must match the name in the SKILL.md frontmatter.
SKILL.md must contain name and description.
The symlink in the Skill source or package will be rejected.
The installer only copies/packages files and does not execute scripts in Skill.
The archive checks for traversal, absolute paths, links, size limits, and abnormal entries.
--dry-run does not produce installation or export side effects.
The upload package uses deterministic file order, fixed timestamps, and permissions for stable verification.

7.14 Version Information

7.14.1 `version`

timecho-cli version

JSON Output:

timecho-cli version --json

It can also be written as:

timecho-cli --json version

Output includes:

CLI version.
Git commit.
Build date.
Publication Channel
Go version.
Operating system and CPU architecture.

7.15 Shell Completion

7.15.1 Bash

Current terminal temporarily enabled:

source <(timecho-cli completion bash)

Permanent installation:

timecho-cli completion bash \
  > ~/.local/share/bash-completion/completions/timecho-cli

7.15.2 Zsh

timecho-cli completion zsh \
  > "${fpath[1]}/_timecho-cli"

Then restart Zsh:

exec zsh

7.15.3 Fish

mkdir -p ~/.config/fish/completions

timecho-cli completion fish \
  > ~/.config/fish/completions/timecho-cli.fish

7.15.4 PowerShell

Current session temporarily enabled:

timecho-cli completion powershell |
  Out-String |
  Invoke-Expression

To write a PowerShell Profile:

timecho-cli completion powershell |
  Out-File -Append -Encoding utf8 $PROFILE

If Profile does not exist:

New-Item -ItemType File -Force $PROFILE
timecho-cli completion powershell |
  Out-File -Append -Encoding utf8 $PROFILE

7.16 Structured output, exit codes and automation

7.16.1 JSON Successful Envelope

timecho-cli --json \
  --trace-id build-check-001 \
  version

Output structure:

{
  "ok": true,
  "api_version": "timecho.com/timecho-cli/v1alpha1",
  "command": "timecho-cli version",
  "data": {
    "version": "1.0.0",
    "commit": "0123456789ab",
    "date": "2026-07-29T00:00:00Z",
    "channel": "stable",
    "go": "go1.25.0",
    "os": "linux",
    "arch": "amd64"
  },
  "meta": {
    "trace_id": "build-check-001",
    "duration_ms": 1
  },
  "notices": []
}

The specific field of data is determined by the command; the script should first determine ok and then parse the command data.

7.16.2 JSON Error Envelope

Error constructing a local parameter:

timecho-cli --json sql

Error writing to stderr, structure similar to:

{
  "ok": false,
  "api_version": "timecho.com/timecho-cli/v1alpha1",
  "command": "timecho-cli sql",
  "error": {
    "type": "validation",
    "code": "sql_source",
    "message": "exactly one SQL source is required",
    "hint": "pass one positional SQL, --file, or --stdin",
    "retryable": false,
    "param": "sql"
  },
  "meta": {},
  "notices": []
}

Automation logic should prioritize error.type and error.code instead of relying on the complete English message.

7.16.3 stdout and stderr

JSON success: stdout;
JSON failure: stderr;
CSV query result: pure stdout;
human final data: stdout;
human errors, tips and verbose diagnostics: stderr.

Bash Separation Output:

timecho-cli --json version \
  >result.json \
  2>error.json

PowerShell:

timecho-cli --json version `
  1> .\result.json `
  2> .\error.json

7.16.4 Exit Codes

Exit Code	Meaning
`0`	Success
`1`	Database operation error or general error not mapped to a dedicated exit code
`2`	Parameter or input check error
`3`	Configuration, Credentials or General Conflict
`4`	Network or protocol error
`5`	Internal Error
`6`	Not supported or policy rejected
`7`	Partial, partial results available but partial collection/processing failed
`10`	Missing write confirmation
`130`	Operation interrupted

Bash:

timecho-cli --json version
code=$?
echo "$code"

PowerShell:

timecho-cli --json version
$code = $LASTEXITCODE
Write-Output $code

7.16.5 Non-interactive configuration writing

Execute Dry Run first:

timecho-cli --json \
  --non-interactive \
  config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --dry-run

After the review is passed, it is explicitly confirmed that:

timecho-cli --json \
  --non-interactive \
  --yes \
  config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1

Without --yes, the write command returns confirmation_required without prompting or modifying the file.

7.16.6 Installing Built-in Skills in CI

Use temporary targets to avoid writing to the actuator's real Agent directory:

target="$(mktemp -d)"

timecho-cli --json \
  --non-interactive \
  setup skills \
  --agent codex \
  --target-dir "$target" \
  --dry-run

timecho-cli --json \
  --non-interactive \
  setup skills \
  --agent codex \
  --target-dir "$target"

PowerShell:

$target = Join-Path $env:TEMP ("timechodb-ci-skills-" + [guid]::NewGuid())

timecho-cli --json `
  --non-interactive `
  setup skills `
  --agent codex `
  --target-dir $target `
  --dry-run

timecho-cli --json `
  --non-interactive `
  setup skills `
  --agent codex `
  --target-dir $target

7.17 Password Usage Examples

The order in which passwords are read from the CLI is:

--password-stdin
TIMECHODB_PASSWORD
Operating System Keychain

7.17.1 Using Environment Variables

Bash:

export TIMECHODB_PASSWORD='your-password'
timecho-cli --ctx prod status

PowerShell:

$env:TIMECHODB_PASSWORD = "your-password"
timecho-cli --ctx prod status

Purge after use:

unset TIMECHODB_PASSWORD

PowerShell:

Remove-Item Env:TIMECHODB_PASSWORD

7.17.2 Using stdin

Bash:

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod status --password-stdin

PowerShell:

$env:TIMECHODB_PASSWORD |
  timecho-cli --ctx prod status --password-stdin

7.17.3 Using Keychain

Write when Context is added:

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli ctx add prod \
    --host db.example.com \
    --password-stdin

Subsequent direct use:

timecho-cli --ctx prod status
timecho-cli --ctx prod sql "show version"

7.18 Complete Operation Process Example

7.18.1 Adding Connections

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli ctx add prod \
    --host db.example.com \
    --port 6667 \
    --user root \
    --dialect tree \
    --password-stdin

7.18.2 Switch Contexts

timecho-cli ctx use prod

7.18.3 Check version

timecho-cli sql "show version"

7.18.4 Checking status

timecho-cli status

7.18.5 Query data

timecho-cli --json sql \
  "select * from root.demo.device1 limit 100"

7.18.6 Import CSV

timecho-cli data import csv data.csv \
  --batch-size 1000 \
  --max-bad-rows 10 \
  --error-file rejected.csv

7.18.7 Export CSV

timecho-cli data export csv \
  --sql "select * from root.demo.device1" \
  --out device1.csv

7.18.8 Get Machine Code

timecho-cli activate machine-code

7.18.9 Apply an Activation Code

printf '%s' "$ACTIVATION_CODE" |
  timecho-cli activate apply --stdin

7.18.10 Verifying activation status

timecho-cli activate status

7.18.11 Check local configuration

timecho-cli config get \
  --all \
  --home /opt/timecho \
  --db-version 2.0.6.1

7.18.12 Modify configuration

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --dry-run

Write after confirmation:

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --yes

7.18.13 Generating a Diagnostic Package

timecho-cli diagnose \
  --local \
  --home /opt/timecho \
  --bundle ./timecho-diagnose.zip

7.18.14 Installing Codex Skills

timecho-cli setup skills \
  --version 1.0.0 \
  --agent codex \
  --scope user

8. 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.