TimechoCLI Command Examples

About 27 min

TimechoCLI Command Examples

1. Prerequisites

TimechoCLI has been installed. For installation and deployment, see TimechoCLI Deployment.

2. Context Connection Management

2.1 `ctx add`: Add a Context

Basic syntax

timecho-cli ctx add NAME [flags]

Add a remote tree-model database

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

If the current session is an interactive terminal, the command prompts for the password; pressing Enter skips saving it. You can also pass the password 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. Without --password-stdin, the Context is still created, but its credential status is missing; subsequent database commands must provide the password through an environment variable or the keychain.

Add a table-model Context

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

Add a 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 a cluster Context

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

The flag can also be repeated:

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 a 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 a 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

2.2 `ctx list`: List Contexts

timecho-cli ctx list

JSON output:

timecho-cli ctx list --json

2.3 `ctx show`: Show a Context

Show the current Context:

timecho-cli ctx show

Show a specific Context:

timecho-cli ctx show prod

JSON output:

timecho-cli ctx show prod --json

Plaintext passwords stored in the keychain are never returned in the output.

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

2.5 `ctx update`: Update a Context

Only explicitly passed parameters are modified.

Change the host and port

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

Change the username and password

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

Change the SQL dialect

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

Enable TLS

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

Change timeouts and fetch size

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

Change the cluster node list

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

2.6 `ctx remove`: Remove a Context

Removing only the Context configuration leaves the keychain password intact and requires no confirmation:

timecho-cli ctx remove old-prod

Deleting the password stored in the keychain as well is a confirmable operation:

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

In an interactive terminal, --yes can be omitted and confirmation given at the prompt; in JSON or --non-interactive mode, --yes must be passed explicitly.

2.7 `ctx discover`: Discover Local Installations

Automatically search common installation directories:

timecho-cli ctx discover

Specify a 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 discovers installation directories; it does not modify Context configuration.

3. SQL Execution

3.1 Execute SQL Directly

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"

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

3.3 CSV Output

Output to the terminal:

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

Redirect to a file:

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

3.4 Execute a SQL File

Create a SQL file:

select * from root.sg.d1 limit 100

Execute it:

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

Short form:

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

3.5 Execute from stdin

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

Pipe input from a file:

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

PowerShell:

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

3.6 Force Query Execution

When the SQL type cannot be determined automatically:

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

3.7 Force Non-Query Execution

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

3.8 Use the Table Dialect

Use the Table dialect configured in the Context:

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

Temporarily override the dialect:

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

3.9 Provide the Database Password via stdin

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

3.10 Set a Timeout

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

3.11 Safely Display BLOB Binary Columns

Queries such as READ_OBJECT(...) return BLOB. In human mode, only a safe size summary is displayed by default, and arbitrary binary bytes are never written 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 needed, choose Base64 or hexadecimal explicitly:

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'"

With an explicit encoding, binary values in human and CSV output carry a base64: or hex: prefix; in human mode without an explicit encoding, the size summary is still displayed. In JSON query output, binary values are encoded strings without a prefix, with the column type and encoding declared in data.types and data.binary_encoding; if unspecified, JSON/CSV defaults to Base64. --binary-encoding accepts only base64 or hex.

The sql command allows exactly one input source: a positional argument, --file, or --stdin; they cannot be combined.
Only one SQL statement per invocation; multi-statement input is rejected.
--query and --non-query are mutually exclusive.
--stdin and --password-stdin cannot share stdin.
The general sql command refuses activation SQL; database activation must use activate apply.

4. CSV Data Import

4.1 `data import csv`: Import the Official Tree CSV

Sample CSV:

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:

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

4.2 Allow a Limited Number of Bad Rows

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

4.3 Write Bad Rows to a File

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

4.4 Import Table Data with a Mapping

Source 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:

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

4.5 Import Tree Data with a Mapping

Source 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:

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

4.6 Provide the Database Password via stdin

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

4.7 JSON Output of Import Results

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

5. CSV Data Export

5.1 `data export csv`: Export to a File

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

5.2 Export to stdout

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

--out can also be omitted; the default is stdout:

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

Redirect to a file through the shell:

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

5.3 Export a Table Query

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

5.4 Export BLOB Columns

By default, binary values in CSV use Base64 with a base64: prefix; hexadecimal is also available:

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 then uses the hex: prefix. --binary-encoding accepts only base64 or hex. To restore the original file of an OBJECT, do not go through CSV; use data export object in the next section.

5.5 Provide 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 written to stdout cannot be combined with JSON output mode.

6. OBJECT File Import and Export

OBJECT is a Table-model capability of TimechoDB Enterprise Edition. Before importing, confirm the database version, license status, target table DDL, all TAG columns, and the OBJECT FIELD column; do not mix the BLOB of the open-source Apache IoTDB with the enterprise OBJECT.

6.1 `data import object`: Write a Local File

The following command writes a local regular file into a single Table row in chunks of 4 MiB (the default) and marks EOF on the last chunk:

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 the import connection.

--timestamp is a required millisecond timestamp; pass one --tag name=value per TAG column; --object-column points to the OBJECT FIELD.
--chunk-size defaults to 4194304 bytes, with an allowed range of 1 to 256 MiB.
--verify is enabled by default: after writing, the data is read back chunk by chunk and compared by byte count and SHA-256. Use --verify=false only when explicitly accepting no verification.
Local verification accepts regular files only. If a chunk write fails midway, chunks already written on the server cannot be rolled back automatically by the CLI; check or delete the target row first, then decide whether to retry. JSON automation example:

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

6.2 `data export object`: Restore the Original File

A single query must return exactly one row and one non-NULL BLOB column through 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

For large objects, a chunked query template containing exactly one {{offset}} and one {{length}} placeholder can be used:

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

Export must use --out FILE; writing raw binary to stdout is forbidden. If the target already exists, a conflict is returned by default; it is replaced only when --force is passed explicitly. The CLI first writes a temporary file in the same directory, atomically publishes it only after full success, and returns the byte count and SHA-256; a failed query never publishes a partial target file.

7. TsFile Import

7.1 `data import tsfile`

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

Windows 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"

Provide the 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 argument is a path accessible to the database server, not a local path on the client running the CLI.
The first CLI release does not support TsFile export.

8. Database Activation

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

Provide the database password via stdin:

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

8.2 `activate apply`: Apply an Activation Code

Passing the activation code via stdin is recommended:

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

PowerShell:

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

Pass it directly as an argument:

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

JSON output:

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

--stdin is recommended so the activation code never enters the shell history.
After applying, the CLI queries the activation status again; success is reported only when the resulting status is ACTIVATED.
The activation code and the database password cannot be read from the same stdin pipe; in that case, store the database password in the keychain beforehand or provide it through the TIMECHODB_PASSWORD environment variable.

8.3 `activate status`: Show the Activation Status

timecho-cli --ctx prod activate status

JSON output:

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

Provide the database password via stdin:

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

9. Local Configuration Management

Configuration commands operate only on the local installation directory, an explicit configuration file, or a kind: local Context; they never modify remote server files over SSH.

9.1 `config get`: Read a Configuration

Read through a local Context

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

If the Context configuration file already contains an accurate versionHint, --db-version can be omitted. ctx add/update currently provides no flag to set a versionHint, so the regular CLI flow is to pass the database version explicitly. Read through the installation directory

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

Read through a specific 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 entries

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

9.2 `config set`: Modify a Configuration

Validate and show the diff only

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

Write after confirmation

Interactive:

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

Change the timestamp precision

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

Change the data directories

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

The actual write displays a diff, creates a backup, checks for concurrent changes, and performs an atomic replacement in the same directory.

9.3 `config diff`: Compare Configurations

Compare against the 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

9.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 apply tuning recommendations automatically. Even with --apply, 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 workflow is to review the recommendations first, then apply each confirmed item with config set:

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 contains no guessed hardware tuning values; when no authoritative recommendation exists, recommendations is empty and an explanatory notice is returned.

10. Configuration Schema Management

10.1 `config schema list`: List Schema Fields

Use the default database version:

timecho-cli config schema list

Specify a 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

10.2 `config schema show`: Show the Schema

Show the full schema:

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

Show a specific entry:

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

Show the timestamp precision definition:

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

10.3 `config schema update`: Update the Schema

Update from the default release URL:

timecho-cli config schema update \
  --version 1.0.0

Specify a custom release URL:

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 downloads:

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

and performs HTTPS, SHA-256, archive path, and schema content validation. The SHA-256 proof shows the assets are unchanged relative to checksums.txt, but the current protocol does not claim to independently verify the publisher identity or signature authenticity.

11. Database Status Check

11.1 `status`

Check the current Context:

timecho-cli status

Check a specific Context:

timecho-cli --ctx prod status

JSON output:

timecho-cli --ctx prod --json status

Add a timeout:

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

Provide the database password via stdin:

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

Automation invocation:

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

The status result contains checks such as database version, activation, cluster, Region, runtime variables, and disk usage; each check returns:

pass
warn
fail
skip

The disk usage check selects the query based on the SQL dialect of the Context: the tree model uses SHOW DISK_USAGE FROM root.**, and the table model uses SELECT * FROM information_schema.table_disk_usage. The syntax of the two models cannot be mixed.

12. Diagnostic Commands

12.1 Remote Database Diagnostics

timecho-cli --ctx prod diagnose

JSON output:

timecho-cli --ctx prod --json diagnose

12.2 Generate a Redacted Diagnostic Bundle

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

12.3 Include Local Diagnostics with Remote Diagnostics

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

12.4 Specify 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"

12.5 Run Remote and Local Diagnostics Together

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

12.6 Provide the Database Password via stdin

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

Diagnostic results are redacted for sensitive information such as passwords, tokens, and activation codes. If a single collection item fails, the remaining items still run and a partial success is returned.
diagnose always resolves the Context, creates a database session, and runs remote read-only queries first; --local and --home only add local OS/JDK/configuration/log collection and do not provide an offline diagnosis mode. Even if you only care about a local directory, a connectable database Context is still required.

13. TimechoAI

TimechoAI is a command group under the unified timecho-cli; there is no separate timechoai-cli executable. Currently available to users are ping, forecast, and key. evaluate and dimensions are still registered in the migration contract, but hidden and returning service_not_open; until the server side opens them, they must not be invoked or advertised as available capabilities. Runtime help is the final command contract.

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

13.2 Check Connectivity and Authentication

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

Prefer avoiding API keys in the shell history:

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

13.3 Forecast a Single Target Series

Input supports CSV, TSV, and JSON. The v0.1.0 Forecast contract accepts a single --input: one table containing the time column, the target, and optional covariate columns. The history part requires at least 16 rows; without --time-col, a case-insensitive time column is auto-detected.

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

--target must be passed exactly once, and its value must be a single target column name; omitting it, repeating it, or passing a comma-separated list of multiple columns fails before credentials are read or the network is touched. --output-start-time is also required: rows with time < boundary are the target/history-covariate history, and rows with time >= boundary provide future covariates, whose target values are discarded. The boundary may fall between two samples and is not required to appear exactly in the time column. Explicit models use --model or the compatible alias --model-id:

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

History and future covariates are selected from the same --input with --history-cov and --future-cov respectively. Both flags can be repeated or comma-separated, and column order is preserved; future covariates must be a subset of the history covariates. The default auto-adaptation only handles length: future rows beyond the horizon are truncated, and when there are not enough, legal timestamps are generated at the fixed sampling interval and the covariates are zero-filled. Use --no-auto-adapt to strictly reject length mismatches; with or without auto-adaptation, illegal column roles are never silently repaired.

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

When --output-length is omitted: without future covariates, it stays null on the wire and the service chooses the default; with future covariates selected, the horizon is inferred from the number of existing rows after the boundary, and if there are none at all, the default of the selected or auto-routed model is used and future rows are generated. The legacy flags --history-cov-input and --future-cov-input are hidden; passing either returns the forecast_legacy_flag migration error. The columns of legacy files must be merged into --input before using the new selectors; there is no compatible execution path. The time column strictly follows the Python SDK: only YYYY-MM-DD, or an ISO datetime with seconds, optional 1-9 fractional digits, and an optional Z/+HH:MM offset. An entire column must use the same separator, precision, timezone representation/state, and a fixed sampling interval. Numeric timestamps, duplicate times, mixed date/datetime, mixed Z and offset, and irregular intervals all fail before the network is touched. The CLI sorts stably but does not convert to UTC; --output-start-time must keep the same aware/naive timezone state as the input. The legacy format 2020-11-07 04:20:00 +0800 CST is not part of the new Forecast contract. Results can be output directly as human, JSON envelope, or plain CSV, or atomically written to CSV/JSON files. Existing target files are fully replaced; a failure never leaves a partial file behind:

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

--model-param KEY=VALUE can be repeated; VALUE is parsed as JSON first, otherwise passed as a plain string. Target and covariate columns accept only limited numeric values; nulls, NaN, Inf, duplicate columns, and illegal time values are rejected before credentials are read or any network request is made. --plot, --plot-format, --plot-width, --plot-height, and --plot-scale are handled natively by the unified Go CLI and never switch to a Python CLI or MCP. An example PNG with all plotting parameters:

timecho-cli ai forecast \
  --input ./data.csv \
  --target OT \
  --output-start-time 2024-01-17T00:00:00 \
  --output-length 96 \
  --plot ./forecast.png \
  --plot-format png \
  --plot-width 1200 \
  --plot-height 700 \
  --plot-scale 2

Other plotting parameters require --plot PATH; it writes a PNG by default, while an .html/.htm suffix or --plot-format html writes a self-contained SVG HTML. --plot-format accepts only png|html. --plot-width/--plot-height are logical pixels, defaulting to 800×500, both ranging 1-8192; --plot-scale is the PNG resolution multiplier, default 2, range 0.25-8, and the scaled width and height must not exceed 8192 pixels. --out and --plot must use different paths. Plotting reuses the same prepared target history, so the solid history line contains only the rows before the boundary; the forecast line is dashed, and the boundary is a gray dotted line. Columns selected by --history-cov also reuse their prepared pre-boundary frames, drawn only as low-emphasis history-only auxiliary curves that never extend into the forecast interval. Plot files use a temporary file in the same directory plus atomic replacement; on a rendering failure the old file is kept and an error is returned before the success result is printed. The Forecast JSON envelope's data.results keeps the API's split-table shape (columns and data); human/CSV modes expand the result table returned by the service and add a deterministic task column only when multiple tables are returned. With --plot, JSON additionally returns data.plot, which contains the absolute path and the logical/final dimensions; human mode reports the path, and CSV stays pure CSV with the path written to stderr. --out result.json writes the same results payload but without the CLI's outer envelope.

13.4 Manage the TimechoAI API Key

Viewing the status never echoes the key; setting/rotating reads from stdin first, avoiding secrets in command arguments or the 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 system keychain with service timecho-cli and account ai/api-key. The resolution order for set is --api-key-stdin, TIMECHOAI_API_KEY, the compatible variable TIMER_CLIENT_API_KEY, and finally a secure prompt in an interactive terminal; JSON or non-interactive mode never prompts for input.

13.5 AI Services Not Yet Available

evaluate and dimensions are still recognized by installed binaries, but they are hidden from ai --help, and calling them directly returns the typed error service_not_open. Until the server side opens them, do not treat the following commands as a success path or promise availability:

timecho-cli ai evaluate
timecho-cli ai dimensions

AI-specific parameters are --api-key-stdin and --base-url. The API key order is stdin, TIMECHOAI_API_KEY, the compatible variable TIMER_CLIENT_API_KEY, and the system keychain. The root-level --timeout, --json, --output, --non-interactive, --verbose, and --trace-id continue to be reused. AI JSON uses the same timecho.com/timecho-cli/v1alpha1 as other commands, with Forecast using the TimechoAIForecast kind; MCP is still out of scope for this migration, so do not fabricate MCP calls from planning documents.

13.6 Use the Forecast Agent Skill

When an Agent needs to automatically "check data → select routing → forecast → plot → report", install the built-in timecho-forecast workflow:

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 common timecho-cli-guide to the plan if they exist in the source. The workflow first checks the unified CLI's root/AI help, executes only through timecho-cli ai, and runtime --help takes precedence over static examples.

14. Skills Installation and Upload Package Export

timecho-cli setup skills serves two kinds of delivery:

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

Upload package export never calls platform-private APIs and never completes a remote import automatically.

14.1 Default Behavior: Install the Built-in Binary Skills

When --source, --bundle, or --version is not passed, the offline Skills catalog built into the binary is used:

timecho-cli setup skills

The defaults are equivalent to:

--agent all --scope user

Here all expands only to the following filesystem agents:

claude
codex
codebuddy
openclaw
hermes
trae
trae-cn

all does not include trae-work or workbuddy, to avoid accidentally generating upload packages when no export directory is specified. Preview the installation plan of the built-in catalog first:

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

Key fields in the output:

Field	Meaning
`source_mode: embedded`	Uses the catalog built into the binary
`bundle_version: embedded-<digest>`	Build-time catalog digest label
`sha256_verified: false`	No external `checksums.txt` used
`delivery_mode: filesystem`	Writes directly into the agent Skills directory
`delivery_status: planned`	Dry run; plan only

The built-in catalog is a build-time snapshot and does not represent the latest version on the official site or a remote release. Use --version to specify a release version.

14.2 Install from the Official Release

With --version specified and no --source/--bundle, the download comes from the release:

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

Install to the Codex user directory:

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

With JSON output:

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

With a custom HTTPS release URL:

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

The actual download URLs are composed of:

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

Remote downloads are HTTPS-only and verify SHA-256 before safe unpacking. The checksum proves only that the assets match checksums.txt; it is not an independent publisher signature verification.

14.3 Install from the Repository Skills Directory

For local development, use the canonical source directory directly:

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

After confirming the plan, install for real:

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

Windows PowerShell:

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

Local directory mode requires no external checksum; the output is:

source_mode: directory
sha256_verified: false
bundle_version: local

If both --source and --version are passed, --version acts only as a local bundle label in the manifest and never triggers a remote download:

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

--source and --bundle are mutually exclusive.

14.4 Install from a Local Bundle

A local .tar.gz bundle must come with a checksums.txt containing that file's digest:

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

Install for real:

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: build a test bundle containing only the Skill directories

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: build a test bundle containing only the Skill directories

$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 pack the entire repository root into a Skills bundle. When packaging from this repository's skills/, select only the canonical directories timechodb-*, timechoai-*, timecho-cli-guide, and timecho-forecast to avoid mixing embed.go, test files, or other non-Skill assets into the release package.

14.5 Select a Subset of Skills

--skill can be repeated or comma-separated:

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

The Forecast workflow can be selected alone:

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

Equivalent form:

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

Selecting a nonexistent Skill or one with an illegal name format fails before the target directory is written. If a selected Skill invokes timecho-cli in its 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 selected explicitly, timechoai-cli-guide is also added automatically if present in the source. This way, the Agent can confirm current syntax through runtime --help and the layered command reference before executing dependent Skills. Unrelated Skills are never injected with a guide, and explicitly selecting a guide itself never duplicates it. Therefore, automation scripts should treat plan.install/plan.export in the dry-run or real result as the final selection set, rather than assuming it maps one-to-one to the command-line --skill arguments.

14.6 Filesystem Agents and Default Directories

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`

Examples:

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-scoped 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, project scope uses the current working directory. Automation scripts are still advised to pass the project root explicitly. OpenClaw project scope reuses .agents/skills by default. For OpenClaw's native project directory:

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

The target then becomes:

<project>/skills

--native-target applies to OpenClaw only. After a Hermes project-scoped installation, if Hermes does not auto-discover the directory, the CLI prompts you to add the target directory to Hermes' external_dirs.

14.7 Install to Multiple Filesystem Agents at Once

--agent can be repeated or comma-separated:

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

Equivalent form:

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

The CLI first generates the plan for all targets and then applies them one by one; however, multi-target execution is currently not a global cross-directory transaction. If a later target write fails, earlier successful targets are not rolled back as a whole.

14.8 Override One Filesystem Agent's Target Directory

--target-dir is allowed with exactly one filesystem agent:

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

The following combination fails:

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

The CLI never silently reuses one custom directory for multiple agents.

14.9 Dry Run, Conflicts, and `--force`

A dry run only generates a plan; it creates no Skills, manifests, backups, or export packages:

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

Filesystem installation uses the following file in the target directory:

.timechodb-skills-manifest.json

to record the bundle version and file SHA-256 digests. If an installed Skill's content differs from what the manifest recorded, a conflict is reported by default and user modifications are preserved:

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

When replacement is explicitly allowed:

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

--force may also replace a same-named Skill directory that is not managed by the manifest. Always run --dry-run first and confirm the target path.

Installation for a single filesystem target stages in the target filesystem and attempts a rollback if the Skill/manifest commit fails.

14.10 Export an Upload Package for TRAE Work

TRAE Work is an upload target that must be selected explicitly and requires --export-dir:

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

Export the ZIP for real:

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

Export a .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.

14.11 Export an Upload Package for WorkBuddy

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

WorkBuddy currently accepts ZIP only:

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

The following fails:

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

14.12 Workspace-Level Upload Packages

The workspace scope is for TRAE Work / WorkBuddy upload exports only 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

Filesystem agents do not accept the workspace scope; upload agents do not accept the project scope.

14.13 Export for TRAE Work and WorkBuddy at the Same Time

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

When both upload agents are selected, the outputs are written to:

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

Because WorkBuddy does not accept .skill, use the default auto or an explicit zip when exporting both:

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

14.14 Run Filesystem Installation and Upload Export Together

Mixed targets must provide --export-dir. Since the only scope accepted by both filesystem and upload targets is user, mixed runs should use the default user scope:

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

For real:

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

14.15 Upload Package Contents and Status

Each Skill generates an independent package whose root directly contains:

SKILL.md
scripts/       # only if the original Skill has it
references/    # only if the original Skill has it
assets/        # only if the original Skill has it

The export directory also contains:

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

The status after a successful export is:

delivery_mode: import-package
delivery_status: awaiting-import

This means the package has been generated and still needs to be imported manually in TRAE Work or WorkBuddy. The current implementation performs no browser auto-upload, private API calls, remote status queries, start/stop, or rollback. For an export directory that already exists and is managed by export-manifest.json: if the content is exactly the same, it is skipped; if the content differs, it conflicts by default and can be replaced with --force. A non-empty directory without a manifest is treated as unmanaged and is never overwritten, even with --force.

14.16 Agent Names and Aliases

Canonical names:

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

The following compatibility aliases are currently retained:

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

Names are case-insensitive, but documentation and automation scripts should always use the canonical lowercase names.

14.17 Security and Behavior Boundaries

Skill names may contain only lowercase letters, digits, and hyphens, with a length of 1-64, and must not start or end with a hyphen.
The directory name must match the name in the SKILL.md frontmatter.
SKILL.md must contain name and description.
Symlinks in Skill sources or packages are rejected.
The installer only copies/packages files; it never executes the scripts inside a Skill.
Archives are checked for traversal, absolute paths, links, size limits, and abnormal entries.
--dry-run has no installation or export side effects.
Upload packages use deterministic file order, fixed timestamps, and permissions for stable verification.

15. Version Information

15.1 `version`

timecho-cli version

JSON output:

timecho-cli version --json

Can also be written as:

timecho-cli --json version

The output includes:

The CLI version.
The Git commit.
The build date.
The release channel.
The Go version.
The operating system and CPU architecture.

16. Shell Completion

16.1 Bash

Enable for the current terminal temporarily:

source <(timecho-cli completion bash)

Install permanently:

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

16.2 Zsh

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

Then restart Zsh:

exec zsh

16.3 Fish

mkdir -p ~/.config/fish/completions

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

16.4 PowerShell

Enable for the current session temporarily:

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

Write into the PowerShell profile:

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

If the profile does not exist:

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

17. Structured Output, Exit Codes, and Automation

17.1 JSON Success 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 concrete fields of data depend on the command; scripts should check ok first, then parse the command data.

17.2 JSON Error Envelope

Construct a local parameter error:

timecho-cli --json sql

The error is written to stderr with a structure like:

{
  "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 check error.type and error.code first, not rely on the full English message.

17.3 stdout and stderr

JSON success: stdout;
JSON failure: stderr;
CSV query results: pure stdout;
Final human data: stdout;
Human errors, prompts, and verbose diagnostics: stderr.

Bash separated output:

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

PowerShell:

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

17.4 Exit Codes

Exit Code	Meaning
`0`	Success
`1`	Database operation error, or a general error not mapped to a dedicated exit code
`2`	Parameter or input validation error
`3`	Configuration, credentials, or general conflict
`4`	Network or protocol error
`5`	Internal error
`6`	Not supported or rejected by policy
`7`	Partial; some results exist but some collection/processing failed
`10`	Missing confirmation for a write operation
`130`	Interrupted

Bash:

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

PowerShell:

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

17.5 Non-Interactive Configuration Write

Run a 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 passes, confirm explicitly:

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

Without --yes, the actual write returns confirmation_required; it never prompts or modifies files.

17.6 Install Built-in Skills in CI

Use a temporary target to avoid writing into the runner's real agent directories:

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

18. Password Usage Examples

The CLI resolves passwords in this order:

--password-stdin
TIMECHODB_PASSWORD
The OS keychain

18.1 Use an Environment Variable

Bash:

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

PowerShell:

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

Clean up after use:

unset TIMECHODB_PASSWORD

PowerShell:

Remove-Item Env:TIMECHODB_PASSWORD

18.2 Use 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

18.3 Use the Keychain

Store it when adding the Context:

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

Then use it directly:

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

19. Complete Operation Process Example

19.1 Add a Connection

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

19.2 Switch Context

timecho-cli ctx use prod

19.3 Check the Version

timecho-cli sql "show version"

19.4 Check the Status

timecho-cli status

19.5 Query Data

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

19.6 Import CSV

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

19.7 Export CSV

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

19.8 Get the Machine Code

timecho-cli activate machine-code

19.9 Apply the Activation Code

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

19.10 Verify the Activation Status

timecho-cli activate status

19.11 Check the Local Configuration

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

19.12 Modify the 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

19.13 Generate a Diagnostic Bundle

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

19.14 Install Codex Skills

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