You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tsfile.apache.org by ji...@apache.org on 2026/06/09 10:43:17 UTC

(tsfile) branch develop updated: Add tsfile-cli: inspect and import .tsfile from the command line (#829)

This is an automated email from the ASF dual-hosted git repository.

jt2594838 pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/tsfile.git


The following commit(s) were added to refs/heads/develop by this push:
     new d78fd5154 Add tsfile-cli: inspect and import .tsfile from the command line (#829)
d78fd5154 is described below

commit d78fd5154718b8931c1f022d6f4731df4ab248c6
Author: ZhangHongYin <46...@users.noreply.github.com>
AuthorDate: Tue Jun 9 18:43:11 2026 +0800

    Add tsfile-cli: inspect and import .tsfile from the command line (#829)
    
    * docs: add design spec for TsFile Unix-philosophy C++ CLI
    
    Read-only inspect/export verbs (ls/schema/stats/head/cat/select) as a
    single multi-call `tsfile` binary, backed by the existing C++ reader API.
    
    * docs: add implementation plan for TsFile Unix CLI; refine spec
    
    9 TDD tasks (CMake scaffold -> arg parser -> formatters -> ResultSet pump
    -> ls/schema/stats/head/cat/select -> install/verify). Spec tweaked to
    match confirmed C++ APIs (table-model schema blanks encoding/compression;
    stats = count + time range).
    
    * Update TsFile CLI redesign spec
    
    * Add TsFile CLI redesign implementation plan
    
    * Update tsfile CLI command surface
    
    * Route ReadFile::open errors to stderr
    
    * Add tsfile CLI commands, formatters, build, and tests
    
    * Consolidate TsFile CLI spec and plan
    
    * Extend tsfile stats with value summaries and shared stat helpers
    
    * Add tsfile meta command
    
    * Add tsfile count command
    
    * Add deterministic tsfile sample command
    
    * Format tsfile CLI sources with clang-format
    
    * Document CMake 4.x/ANTLR4 build constraint in CLI plan
    
    * Simplify sampled writer: trust caller-normalized limit
    
    * Add tsfile-cli usage skill for inspecting .tsfile from the CLI
    
    * Rename CLI binary from tsfile to tsfile-cli
    
    * Add tsfile CLI write (CSV/TSV import) design spec
    
    * Refine write spec: silent-by-default (-v summary) and opt-in --header-match
    
    * Add tsfile CLI write implementation plan
    
    * Add tsfile CLI input_format parsing layer
    
    * Add tsfile CLI write argument parsing
    
    * Add tsfile CLI write command (CSV/TSV import)
    
    * Treat '-' as stdin positional, not an unknown flag
    
    * Format tsfile CLI write sources with clang-format
    
    * Update tsfile-cli skill to document the write command
    
    * Condense tsfile-cli skill with formal notation
    
    * Ignore .codegraph and cpp/root test-run artifacts
    
    * Add QA learning log for tsfile CLI work
    
    * Move tsfile-cli skill to cpp/tools/skills; stop tracking .claude
    
    * Stop tracking docs/superpowers and QA_Log.md (keep local, out of PR)
    
    * Add Apache license header to tsfile-cli skill doc (fix RAT check)
    
    * Fix CLI test race: unique per-process temp filenames for parallel ctest
    
    * Simplify CLI test fixture: drop unused path param and atomic counter
    
    * Add tsfile-cli tool README
    
    * Expand tsfile-cli README: build-from-source and skill install
    
    * Address PR #829 review feedback for tsfile-cli
    
    - row_query/sample: translate storage error codes to readable phrases
      instead of emitting a bare numeric code
    - read_file: drop the always -1 fd_ value from open() diagnostic; keep
      strerror(errno)
    - run_cli: honor --help even with a positional file; correct the stats
      usage text (min/max/first/last/sum)
    - meta: remove the always-empty version/bloom_filter columns (the public
      reader API exposes neither); update README and SKILL accordingly
    - write: stream rows into fixed 1024-row Tablet batches so memory stays
      bounded regardless of input size
    - write: reject numeric overflow (ERANGE for int/float/double, plus an
      INT32 range check)
    - tools CMake: remove the noisy unconditional configure message
    - test CMake: drop the no-op SYSTEM target property and force the vendored
      GTest headers ahead on TsFile_Test where header resolution matters
    
    * Harden tsfile-cli writes, errors, and input validation
    
    Strict-review follow-up to PR #829:
    - write: reject non-strictly-increasing timestamps per device (tag tuple)
      with a located message; refuse --output equal to the input file; remove
      the partial output on any failure so no corrupt .tsfile is left behind
    - write/query/sample failures now print a human-readable cause via
      error_code_message() instead of a bare numeric code; the helper lives in
      the output_format layer so read and write share it
    - schema: report real encoding/compression for table-model columns instead
      of always-empty cells
    - columns spec: reject duplicate column names
    - reject flags that do not apply to a command (write-only flags on read
      commands, row/range flags on metadata commands, --header-match with
      --no-header), and give a clear error when an option precedes the command
    - rename the read-output helpers to emit_result_set* and the JSON predicate
      to emits_json_bare so the names match what they do
    - docs: document the per-device timestamp ordering rule and drop the
      unimplemented "help <command>" form
    
    * Rename tsfile-cli stat_table.{h,cc} to statistics.{h,cc}
    
    The file holds generic statistics helpers (collect_series_stats,
    collect_file_summary, statistic_value_cells) used by stats/count/meta for
    both the tree and table models. "table" wrongly implied the table model;
    "statistics" describes what it actually provides.
    
    * Add tests for tsfile-cli review hardening
    
    Covers per-device timestamp-order rejection (including across batch
    flushes), --output anti-alias and unlink-on-failure, large streaming
    round-trip, numeric overflow detection, duplicate-column rejection,
    flag-applicability errors, the leading-option error, error_code_message
    mapping, --help with a positional file, and table-model schema
    encoding/compression.
    
    * Simplify scoped-command check in tsfile-cli flag validation
    
    Derive the scoped flag from is_row instead of re-listing the
    head/cat/sample command names, so the row-command set lives in one place.
    
    * Address PR #829 round 2 review feedback for tsfile-cli
    
    - write: support quoted CSV fields that span multiple physical lines by
      joining continuation lines until the opening double-quote closes, via a
      new read_record() helper shared by the header and data read paths
    - read: print FLOAT/DOUBLE with max_digits10 precision so values
      round-trip losslessly through a pipe instead of the default 6 sig digits
    - tools CMake: include library headers from the staged LIBRARY_INCLUDE_DIR
      and THIRD_PARTY_INCLUDE instead of reaching into ${PROJECT_SOURCE_DIR}/src,
      matching the convention the test target already uses
    - tests: cover read_record (multi-line quoted, CR strip, TSV, unterminated
      quote) and add e2e float/double lossless and embedded-newline import cases
    
    * Address PR #829 round 3 review feedback for tsfile-cli
    
    Implements jt2594838's review on develop's tsfile-cli:
    
    - write: accept TIMESTAMP/DATE/BLOB columns and store each column with the
      engine's default encoding/compression for its type (via get_value_encoder /
      get_default_compressor) instead of hard-coded PLAIN/UNCOMPRESSED.
    - sample/row_query: when no device is given, build query paths from one
      whole-file get_timeseries_metadata() call via a shared collect_tree_query_paths
      helper instead of a per-device schema loop.
    - Sink CSV split/escape into common/csv_utils.{h,cc} and the datatype-name parser
      into common::parse_data_type_name; the CLI now delegates to them.
    - write: case-insensitive column category, verbose echo of the resolved config,
      header-match errors that name the offending column/position, error codes
      appended to writer failures, and result_code naming.
    - Documented the table-model "first table only" caveat and the extended write
      types in README/SKILL; added struct comments and clearer usage text.
    - Tests: extended-type/category parsing, TIMESTAMP/DATE/BLOB round-trip, verbose
      echo, header-match position, and common csv/type-name helpers.
    
    * Show short-flag aliases in tsfile-cli write/validation error messages
    
    Error strings for flags that have a short form now mention it, matching the
    usage text: -t/--table, -d/--device, -n/--limit. Flags without a short alias
    (--columns, --offset, --seed, --start/--end, --header-match) stay long-only.
    
    * Clarify intent of RowWriter::emits_json_bare predicate
    
    Add a comment explaining that BOOLEAN is grouped with the numeric types because
    true/false are bare JSON literals (not because BOOLEAN is numeric); strings,
    blobs, and dates are quoted. The misleadingly-named is_numeric was already
    renamed to emits_json_bare in a prior round.
    
    * Avoid per-cell copies in tsfile-cli write import hot loop
    
    - Move (not copy) each fully-built DataRow into the batch vector; the row owns a
      vector<string> of cells, so the lvalue push_back copied every cell per row.
    - Add values to the Tablet by column index instead of by name. The by-name
      add_value lowercases the measurement name and does a map lookup per cell;
      the column->index order is fixed at schema-build time, so the index is known.
      String/text/blob use the c-string by-index overload to keep the same path.
    
    * Strengthen tsfile-cli write tests; reject impossible DATE cells
    
    New e2e tests:
    - per-column value mapping via JSON output (guards the by-index add_value path:
      any cross-column write would surface as a wrong key/value pair)
    - multi-type import across >2 batches, spot-checking a last-batch row
    - RFC 4180 round-trip of a quoted STRING with comma + embedded quotes
    - TIMESTAMP overflow / non-numeric, empty-cell-as-null
    - DATE boundary (leap day) and impossible-date rejection
    
    The impossible-date test exposed a bug: parse_date_cell only checked the
    YYYY-MM-DD shape, and the writer silently drops an invalid std::tm rather than
    erroring, so e.g. 2024-13-40 imported as success. parse_date_cell now validates
    via DateConverter::date_to_int and reports "bad DATE".
    
    * Filter single-device tree query paths through the device schema
    
    Resolve the device's real series and build query paths directly from
    them, keeping only measurements that match the projection. A provided
    measurement that doesn't exist on the device is now dropped instead of
    queried blindly, matching the no-device path.
    
    * Use set::find for the known-command membership check
    
    Expresses the existence test directly instead of counting; equivalent
    for a std::set and C++11-compatible (no contains()).
---
 .gitignore                            |  21 +-
 cpp/CMakeLists.txt                    |   7 +-
 cpp/src/common/csv_utils.cc           |  86 ++++
 cpp/src/common/csv_utils.h            |  44 ++
 cpp/src/common/db_common.h            |  38 ++
 cpp/src/common/tablet.cc              |   3 +
 cpp/src/file/read_file.cc             |   8 +-
 cpp/test/CMakeLists.txt               |  49 +-
 cpp/test/common/csv_utils_test.cc     |  66 +++
 cpp/test/tools/cli_args_test.cc       | 182 +++++++
 cpp/test/tools/cli_test_util.h        | 104 ++++
 cpp/test/tools/command_e2e_test.cc    | 910 ++++++++++++++++++++++++++++++++++
 cpp/test/tools/input_format_test.cc   | 176 +++++++
 cpp/test/tools/output_format_test.cc  | 146 ++++++
 cpp/test/tools/statistics_test.cc     |  50 ++
 cpp/tools/CMakeLists.txt              |  48 ++
 cpp/tools/README.md                   | 217 ++++++++
 cpp/tools/cli/cli_args.cc             | 213 ++++++++
 cpp/tools/cli/cli_args.h              |  62 +++
 cpp/tools/cli/exit_codes.h            |  32 ++
 cpp/tools/cli/run_cli.cc              | 289 +++++++++++
 cpp/tools/cli/run_cli.h               |  34 ++
 cpp/tools/commands/cmd_cat.cc         |  29 ++
 cpp/tools/commands/cmd_count.cc       |  47 ++
 cpp/tools/commands/cmd_head.cc        |  30 ++
 cpp/tools/commands/cmd_ls.cc          |  64 +++
 cpp/tools/commands/cmd_meta.cc        |  50 ++
 cpp/tools/commands/cmd_sample.cc      |  90 ++++
 cpp/tools/commands/cmd_schema.cc      | 129 +++++
 cpp/tools/commands/cmd_stats.cc       |  57 +++
 cpp/tools/commands/cmd_write.cc       | 417 ++++++++++++++++
 cpp/tools/commands/commands.h         |  70 +++
 cpp/tools/commands/row_query.cc       | 140 ++++++
 cpp/tools/commands/statistics.cc      | 218 ++++++++
 cpp/tools/commands/statistics.h       |  69 +++
 cpp/tools/format/input_format.cc      | 148 ++++++
 cpp/tools/format/input_format.h       |  56 +++
 cpp/tools/format/output_format.cc     | 359 ++++++++++++++
 cpp/tools/format/output_format.h      |  73 +++
 cpp/tools/format/result_set_format.cc | 183 +++++++
 cpp/tools/format/result_set_format.h  |  45 ++
 cpp/tools/skills/tsfile-cli/SKILL.md  | 112 +++++
 cpp/tools/tools_main.cc               |  29 ++
 43 files changed, 5189 insertions(+), 11 deletions(-)

diff --git a/.gitignore b/.gitignore
index d27277565..fcd5f2b6b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -47,8 +47,19 @@ build/*
 cpp/third_party/zlib-1.3.1/treebuild.xml
 cpp/third_party/zlib-1.3.1/zlib-1.3.1/treebuild.xml
 
-# Claude Code
-.claude/settings.local.json
-.claude/todos/
-.claude/worktrees/
-.claude/scheduled_tasks.json
+# Claude Code (local AI tooling — not uploaded; skill lives in cpp/tools/skills)
+.claude/
+
+# CodeGraph local index
+.codegraph/
+
+# Test-run artifacts (temp .tsfile/.dat written to the working dir or repo root)
+cpp/cwrapper_*.tsfile
+cpp/tsfile_writer_*.tsfile
+cpp/*.dat
+/*.tsfile
+/*.dat
+
+# AI workflow artifacts (kept local, not uploaded)
+docs/superpowers/
+/QA_Log.md
diff --git a/cpp/CMakeLists.txt b/cpp/CMakeLists.txt
index 98d93fcfe..ea7e165d1 100755
--- a/cpp/CMakeLists.txt
+++ b/cpp/CMakeLists.txt
@@ -190,6 +190,9 @@ endif ()
 option(BUILD_TEST "Build tests" ON)
 message("cmake using: BUILD_TEST=${BUILD_TEST}")
 
+option(BUILD_TOOLS "Build the tsfile command-line tools" ON)
+message("cmake using: BUILD_TOOLS=${BUILD_TOOLS}")
+
 option(ENABLE_ANTLR4 "Enable ANTLR4 runtime" ON)
 message("cmake using: ENABLE_ANTLR4=${ENABLE_ANTLR4}")
 
@@ -262,6 +265,9 @@ endif ()
 add_subdirectory(third_party)
 
 add_subdirectory(src)
+if (BUILD_TOOLS)
+    add_subdirectory(tools)
+endif ()
 if (BUILD_TEST)
     add_subdirectory(test)
     if (TESTS_ENABLED)
@@ -272,4 +278,3 @@ else()
 endif ()
 
 add_subdirectory(examples)
-
diff --git a/cpp/src/common/csv_utils.cc b/cpp/src/common/csv_utils.cc
new file mode 100644
index 000000000..eb4cf897a
--- /dev/null
+++ b/cpp/src/common/csv_utils.cc
@@ -0,0 +1,86 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "common/csv_utils.h"
+
+namespace common {
+
+std::vector<std::string> split_csv_line(const std::string& line, char delim,
+                                        bool csv_quotes) {
+    std::vector<std::string> out;
+    std::string field;
+    if (!csv_quotes) {
+        for (char c : line) {
+            if (c == delim) {
+                out.push_back(field);
+                field.clear();
+            } else {
+                field += c;
+            }
+        }
+        out.push_back(field);
+        return out;
+    }
+    bool in_quotes = false;
+    for (size_t i = 0; i < line.size(); ++i) {
+        char c = line[i];
+        if (in_quotes) {
+            if (c == '"') {
+                if (i + 1 < line.size() && line[i + 1] == '"') {
+                    field += '"';
+                    ++i;
+                } else {
+                    in_quotes = false;
+                }
+            } else {
+                field += c;
+            }
+        } else if (c == '"') {
+            in_quotes = true;
+        } else if (c == delim) {
+            out.push_back(field);
+            field.clear();
+        } else {
+            field += c;
+        }
+    }
+    out.push_back(field);
+    return out;
+}
+
+std::string csv_escape(const std::string& field, char delim) {
+    const char triggers[] = {delim, '"', '\n', '\r'};
+    bool needs_quote =
+        field.find_first_of(triggers, 0, sizeof(triggers)) != std::string::npos;
+    if (!needs_quote) {
+        return field;
+    }
+    std::string out = "\"";
+    for (char c : field) {
+        if (c == '"') {
+            out += "\"\"";
+        } else {
+            out += c;
+        }
+    }
+    out += "\"";
+    return out;
+}
+
+}  // namespace common
diff --git a/cpp/src/common/csv_utils.h b/cpp/src/common/csv_utils.h
new file mode 100644
index 000000000..18e4c2bf6
--- /dev/null
+++ b/cpp/src/common/csv_utils.h
@@ -0,0 +1,44 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#ifndef COMMON_CSV_UTILS_H
+#define COMMON_CSV_UTILS_H
+
+#include <string>
+#include <vector>
+
+namespace common {
+
+// Split a single logical line on `delim`. When `csv_quotes` is true the
+// splitter is RFC 4180 aware: a field may be wrapped in double quotes, the
+// delimiter is literal inside quotes, and a doubled quote ("") inside a quoted
+// field is an escaped quote. When `csv_quotes` is false a quote is treated as
+// ordinary data (suitable for TSV).
+std::vector<std::string> split_csv_line(const std::string& line, char delim,
+                                        bool csv_quotes);
+
+// Quote/escape a field for RFC 4180 CSV output: wrap in double quotes and
+// double any embedded quote, but only when the field contains a delimiter,
+// quote, or newline. The delimiter that triggers quoting is `delim` (default
+// comma).
+std::string csv_escape(const std::string& field, char delim = ',');
+
+}  // namespace common
+
+#endif  // COMMON_CSV_UTILS_H
diff --git a/cpp/src/common/db_common.h b/cpp/src/common/db_common.h
index a2700c61c..d7130cd03 100644
--- a/cpp/src/common/db_common.h
+++ b/cpp/src/common/db_common.h
@@ -20,8 +20,10 @@
 #ifndef COMMON_DB_COMMON_H
 #define COMMON_DB_COMMON_H
 
+#include <cctype>
 #include <functional>
 #include <iostream>
+#include <string>
 #include <type_traits>
 #include <unordered_set>
 
@@ -115,6 +117,42 @@ FORCE_INLINE const char* get_data_type_name(TSDataType type) {
     return s_data_type_names[type];
 }
 
+// Parse a case-insensitive type name (e.g. "int32", "TIMESTAMP") into its
+// TSDataType. Covers every named scalar type, not just the subset in
+// s_data_type_names, so callers such as the CLI importer can accept the full
+// set. Returns false for unrecognized names.
+FORCE_INLINE bool parse_data_type_name(const std::string& s, TSDataType& out) {
+    std::string u;
+    u.reserve(s.size());
+    for (char c : s) {
+        u += static_cast<char>(std::toupper(static_cast<unsigned char>(c)));
+    }
+    if (u == "BOOLEAN") {
+        out = BOOLEAN;
+    } else if (u == "INT32") {
+        out = INT32;
+    } else if (u == "INT64") {
+        out = INT64;
+    } else if (u == "FLOAT") {
+        out = FLOAT;
+    } else if (u == "DOUBLE") {
+        out = DOUBLE;
+    } else if (u == "TEXT") {
+        out = TEXT;
+    } else if (u == "STRING") {
+        out = STRING;
+    } else if (u == "TIMESTAMP") {
+        out = TIMESTAMP;
+    } else if (u == "DATE") {
+        out = DATE;
+    } else if (u == "BLOB") {
+        out = BLOB;
+    } else {
+        return false;
+    }
+    return true;
+}
+
 FORCE_INLINE const char* get_encoding_name(TSEncoding encoding) {
     ASSERT(encoding >= PLAIN && encoding <= FREQ);
     return s_encoding_names[encoding];
diff --git a/cpp/src/common/tablet.cc b/cpp/src/common/tablet.cc
index d71e48384..b9ae5301a 100644
--- a/cpp/src/common/tablet.cc
+++ b/cpp/src/common/tablet.cc
@@ -478,6 +478,9 @@ template int Tablet::add_value(uint32_t row_index,
                                const std::string& measurement_name, double val);
 template int Tablet::add_value(uint32_t row_index,
                                const std::string& measurement_name, String val);
+template int Tablet::add_value(uint32_t row_index,
+                               const std::string& measurement_name,
+                               std::tm val);
 
 void Tablet::set_column_categories(
     const std::vector<ColumnCategory>& column_categories) {
diff --git a/cpp/src/file/read_file.cc b/cpp/src/file/read_file.cc
index dd1c42dad..8aab78ca6 100644
--- a/cpp/src/file/read_file.cc
+++ b/cpp/src/file/read_file.cc
@@ -21,6 +21,8 @@
 
 #include <fcntl.h>
 #include <sys/stat.h>
+
+#include <iostream>
 #ifdef _WIN32
 #include <io.h>
 #include <windows.h>
@@ -49,10 +51,8 @@ int ReadFile::open(const std::string& file_path) {
     file_path_ = file_path;
     fd_ = ::open(file_path_.c_str(), O_RDONLY);
     if (fd_ < 0) {
-        std::cout << "open file " << file_path << "  error :" << fd_
-                  << std::endl;
-        std::cout << "open error" << errno << "  " << strerror(errno)
-                  << std::endl;
+        std::cerr << "open file " << file_path << " error: " << strerror(errno)
+                  << " (errno " << errno << ")" << std::endl;
         return E_FILE_OPEN_ERR;
     }
 
diff --git a/cpp/test/CMakeLists.txt b/cpp/test/CMakeLists.txt
index 02c288167..4d325635f 100644
--- a/cpp/test/CMakeLists.txt
+++ b/cpp/test/CMakeLists.txt
@@ -110,6 +110,33 @@ if (${DOWNLOADED})
     endif ()
     add_subdirectory("${GTEST_SRC_ROOT}" "${CMAKE_BINARY_DIR}/googletest-build"
             EXCLUDE_FROM_ALL)
+    # AppleClang searches /usr/local/include before CMake's generated -isystem
+    # paths, so a system-installed GTest can shadow the vendored headers. Force
+    # the vendored include dirs ahead for GTest's own sources here; the same is
+    # done for the consuming TsFile_Test target below (where header resolution
+    # actually matters for the test code).
+    foreach (GTEST_TARGET gtest gtest_main gmock gmock_main)
+        if (TARGET ${GTEST_TARGET})
+            target_include_directories(${GTEST_TARGET} BEFORE PRIVATE
+                    ${GTEST_SRC_ROOT}/googletest/include
+                    ${GTEST_SRC_ROOT}/googletest
+                    ${GTEST_SRC_ROOT}/googlemock/include
+                    ${GTEST_SRC_ROOT}/googlemock)
+            if (APPLE AND NOT MSVC)
+                target_compile_options(${GTEST_TARGET} BEFORE PRIVATE
+                        -iquote${GTEST_SRC_ROOT}/googletest/include
+                        -iquote${GTEST_SRC_ROOT}/googletest
+                        -I${GTEST_SRC_ROOT}/googletest/include
+                        -I${GTEST_SRC_ROOT}/googletest
+                        -std=c++14)
+            endif ()
+        endif ()
+    endforeach ()
+    # Remember the vendored GTest header roots so they can be forced ahead of any
+    # system installation when compiling TsFile_Test itself.
+    set(VENDORED_GTEST_INCLUDE_DIRS
+            ${GTEST_SRC_ROOT}/googletest/include
+            ${GTEST_SRC_ROOT}/googlemock/include)
     set(TESTS_ENABLED ON PARENT_SCOPE)
 else ()
     message(WARNING "Failed to download googletest from all provided URLs, setting TESTS_ENABLED to OFF")
@@ -186,6 +213,11 @@ if (ENABLE_ZLIB)
     list(APPEND TEST_SRCS ${ZLIB_TEST_SRCS})
 endif()
 
+if (BUILD_TOOLS)
+    file(GLOB_RECURSE TOOLS_TEST_SRCS "tools/*_test.cc")
+    list(APPEND TEST_SRCS ${TOOLS_TEST_SRCS})
+endif ()
+
 if (${COV_ENABLED})
     message("Enable code cov...")
     add_compile_options(-fprofile-arcs -ftest-coverage)
@@ -197,12 +229,27 @@ if (ENABLE_ANTLR4)
 endif()
 
 add_executable(TsFile_Test ${TEST_SRCS})
+# Force the vendored GTest headers ahead of any system installation so the test
+# code reliably compiles against the vendored 1.12.1 headers.
+if (VENDORED_GTEST_INCLUDE_DIRS)
+    target_include_directories(TsFile_Test BEFORE PRIVATE
+            ${VENDORED_GTEST_INCLUDE_DIRS})
+endif ()
+if (BUILD_TOOLS)
+    target_include_directories(TsFile_Test PRIVATE ${CMAKE_SOURCE_DIR}/tools)
+endif ()
+if (APPLE AND NOT MSVC)
+    target_compile_options(TsFile_Test PRIVATE -std=c++14)
+endif ()
 target_link_libraries(
         TsFile_Test
         GTest::gtest_main
         GTest::gmock
         tsfile
 )
+if (BUILD_TOOLS)
+    target_link_libraries(TsFile_Test tsfile_cli_obj)
+endif ()
 
 set_target_properties(TsFile_Test PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${LIB_TSFILE_SDK_DIR})
 
@@ -232,4 +279,4 @@ if(WIN32)
   gtest_discover_tests(TsFile_Test DISCOVERY_MODE PRE_TEST DISCOVERY_TIMEOUT 120)
 else()
   gtest_discover_tests(TsFile_Test)
-endif()
\ No newline at end of file
+endif()
diff --git a/cpp/test/common/csv_utils_test.cc b/cpp/test/common/csv_utils_test.cc
new file mode 100644
index 000000000..fabcc86f9
--- /dev/null
+++ b/cpp/test/common/csv_utils_test.cc
@@ -0,0 +1,66 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "common/csv_utils.h"
+
+#include <gtest/gtest.h>
+
+#include "common/db_common.h"
+
+TEST(CsvUtilsTest, SplitTsvKeepsQuotesAsData) {
+    std::vector<std::string> f = common::split_csv_line("a\t\"b\"\tc", '\t',
+                                                        /*csv_quotes=*/false);
+    ASSERT_EQ(f.size(), 3u);
+    EXPECT_EQ(f[1], "\"b\"");
+}
+
+TEST(CsvUtilsTest, SplitCsvHonorsQuotedDelimiterAndEscapedQuote) {
+    std::vector<std::string> f =
+        common::split_csv_line("1,\"a,b\",\"she \"\"hi\"\"\"", ',', true);
+    ASSERT_EQ(f.size(), 3u);
+    EXPECT_EQ(f[1], "a,b");
+    EXPECT_EQ(f[2], "she \"hi\"");
+}
+
+TEST(CsvUtilsTest, EscapeOnlyQuotesWhenNeeded) {
+    EXPECT_EQ(common::csv_escape("plain"), "plain");
+    EXPECT_EQ(common::csv_escape("a,b"), "\"a,b\"");
+    EXPECT_EQ(common::csv_escape("she \"hi\""), "\"she \"\"hi\"\"\"");
+    EXPECT_EQ(common::csv_escape("line\nbreak"), "\"line\nbreak\"");
+    // A field containing a tab needs no quoting for comma-delimited CSV.
+    EXPECT_EQ(common::csv_escape("a\tb"), "a\tb");
+    // ...but does when the delimiter is the tab.
+    EXPECT_EQ(common::csv_escape("a\tb", '\t'), "\"a\tb\"");
+}
+
+TEST(DbCommonTest, ParseDataTypeNameCaseInsensitiveAllTypes) {
+    common::TSDataType t;
+    EXPECT_TRUE(common::parse_data_type_name("boolean", t));
+    EXPECT_EQ(t, common::BOOLEAN);
+    EXPECT_TRUE(common::parse_data_type_name("Int32", t));
+    EXPECT_EQ(t, common::INT32);
+    EXPECT_TRUE(common::parse_data_type_name("TIMESTAMP", t));
+    EXPECT_EQ(t, common::TIMESTAMP);
+    EXPECT_TRUE(common::parse_data_type_name("date", t));
+    EXPECT_EQ(t, common::DATE);
+    EXPECT_TRUE(common::parse_data_type_name("BLOB", t));
+    EXPECT_EQ(t, common::BLOB);
+    EXPECT_FALSE(common::parse_data_type_name("nope", t));
+    EXPECT_FALSE(common::parse_data_type_name("", t));
+}
diff --git a/cpp/test/tools/cli_args_test.cc b/cpp/test/tools/cli_args_test.cc
new file mode 100644
index 000000000..614329463
--- /dev/null
+++ b/cpp/test/tools/cli_args_test.cc
@@ -0,0 +1,182 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "cli/cli_args.h"
+
+#include <gtest/gtest.h>
+
+#include <sstream>
+
+#include "cli/run_cli.h"
+
+TEST(RunCliTest, VersionFlagPrintsVersionAndReturnsOk) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"--version"}, out, err);
+    EXPECT_EQ(code, 0);
+    EXPECT_NE(out.str().find("tsfile"), std::string::npos);
+    EXPECT_TRUE(err.str().empty());
+}
+
+TEST(RunCliTest, NoArgsPrintsUsageToErrAndReturnsUsageError) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("Usage"), std::string::npos);
+}
+
+TEST(RunCliTest, UnknownCommandIsUsageError) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"frobnicate", "x.tsfile"}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("Unknown command"), std::string::npos);
+}
+
+TEST(RunCliTest, LeadingOptionBeforeCommandIsClearError) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code =
+        tsfile_cli::run_cli({"-f", "json", "meta", "data.tsfile"}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("command must come before options"),
+              std::string::npos)
+        << err.str();
+}
+
+TEST(ParseArgsTest, CommandAndFilePositional) {
+    auto p = tsfile_cli::parse_args({"ls", "data.tsfile"});
+    EXPECT_TRUE(p.error.empty());
+    EXPECT_EQ(p.command, "ls");
+    EXPECT_EQ(p.file, "data.tsfile");
+}
+
+TEST(ParseArgsTest, FormatFlagParsed) {
+    auto p = tsfile_cli::parse_args({"cat", "-f", "json", "data.tsfile"});
+    EXPECT_TRUE(p.error.empty());
+    EXPECT_EQ(p.format, tsfile_cli::ParsedArgs::Format::kJson);
+}
+
+TEST(ParseArgsTest, MeasurementsSplitOnComma) {
+    auto p = tsfile_cli::parse_args({"cat", "-m", "s1,s2,s3", "data.tsfile"});
+    ASSERT_EQ(p.measurements.size(), 3u);
+    EXPECT_EQ(p.measurements[1], "s2");
+}
+
+TEST(ParseArgsTest, LimitOffsetAndTimeRange) {
+    auto p =
+        tsfile_cli::parse_args({"head", "-n", "5", "--offset", "2", "--start",
+                                "100", "--end", "200", "data.tsfile"});
+    EXPECT_EQ(p.limit, 5);
+    EXPECT_EQ(p.offset, 2);
+    EXPECT_TRUE(p.has_start);
+    EXPECT_EQ(p.start, 100);
+    EXPECT_TRUE(p.has_end);
+    EXPECT_EQ(p.end, 200);
+}
+
+TEST(ParseArgsTest, UnknownFlagIsError) {
+    auto p = tsfile_cli::parse_args({"ls", "--bogus", "data.tsfile"});
+    EXPECT_FALSE(p.error.empty());
+}
+
+TEST(ParseArgsTest, BadFormatValueIsError) {
+    auto p = tsfile_cli::parse_args({"cat", "-f", "yaml", "data.tsfile"});
+    EXPECT_FALSE(p.error.empty());
+}
+
+TEST(ParseArgsTest, MissingFileIsAllowedAtParseTime) {
+    auto p = tsfile_cli::parse_args({"ls"});
+    EXPECT_TRUE(p.error.empty());
+    EXPECT_EQ(p.command, "ls");
+    EXPECT_TRUE(p.file.empty());
+}
+
+TEST(ParseArgsTest, WriteFlagsParsed) {
+    auto p = tsfile_cli::parse_args({"write", "--table", "t1", "--columns",
+                                     "s1:INT64:field", "-o", "out.tsfile", "-v",
+                                     "--header-match", "in.csv"});
+    EXPECT_TRUE(p.error.empty());
+    EXPECT_EQ(p.command, "write");
+    EXPECT_EQ(p.table, "t1");
+    EXPECT_EQ(p.columns, "s1:INT64:field");
+    EXPECT_EQ(p.output, "out.tsfile");
+    EXPECT_TRUE(p.verbose);
+    EXPECT_TRUE(p.header_match);
+    EXPECT_EQ(p.file, "in.csv");
+}
+
+TEST(ParseArgsTest, OutputFlagNeedsValue) {
+    auto p = tsfile_cli::parse_args({"write", "-o"});
+    EXPECT_FALSE(p.error.empty());
+}
+
+TEST(ParseArgsTest, DashIsStdinPositional) {
+    auto p =
+        tsfile_cli::parse_args({"write", "--table", "t1", "--columns",
+                                "s1:INT64:field", "-o", "out.tsfile", "-"});
+    EXPECT_TRUE(p.error.empty());
+    EXPECT_EQ(p.file, "-");
+}
+
+TEST(ParseArgsTest, SeedFlagParsed) {
+    auto p = tsfile_cli::parse_args(
+        {"sample", "-m", "s1", "-n", "3", "--seed", "42", "data.tsfile"});
+    EXPECT_TRUE(p.error.empty());
+    EXPECT_EQ(p.command, "sample");
+    EXPECT_EQ(p.limit, 3);
+    EXPECT_TRUE(p.has_seed);
+    EXPECT_EQ(p.seed, 42);
+}
+
+TEST(ParseArgsTest, BadSeedValueIsError) {
+    auto p = tsfile_cli::parse_args(
+        {"sample", "--seed", "not_a_number", "data.tsfile"});
+    EXPECT_FALSE(p.error.empty());
+    EXPECT_NE(p.error.find("Invalid --seed"), std::string::npos);
+}
+
+TEST(RunCliTest, SelectIsNoLongerKnownCommand) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"select", "x.tsfile"}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("Unknown command"), std::string::npos);
+}
+
+TEST(RunCliTest, SeedOnCatIsUsageError) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code =
+        tsfile_cli::run_cli({"cat", "--seed", "7", "x.tsfile"}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("--seed is only valid for sample"),
+              std::string::npos);
+}
+
+TEST(RunCliTest, OffsetOnSampleIsUsageError) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code =
+        tsfile_cli::run_cli({"sample", "--offset", "2", "x.tsfile"}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("--offset is not valid for sample"),
+              std::string::npos);
+}
diff --git a/cpp/test/tools/cli_test_util.h b/cpp/test/tools/cli_test_util.h
new file mode 100644
index 000000000..0d1dccb56
--- /dev/null
+++ b/cpp/test/tools/cli_test_util.h
@@ -0,0 +1,104 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#ifndef TSFILE_CLI_TEST_UTIL_H
+#define TSFILE_CLI_TEST_UTIL_H
+
+#include <fcntl.h>
+#ifdef _WIN32
+#include <process.h>
+#else
+#include <unistd.h>
+#endif
+
+#include <sstream>
+#include <string>
+
+#include "common/schema.h"
+#include "common/tablet.h"
+#include "file/write_file.h"
+#include "writer/tsfile_table_writer.h"
+
+namespace tsfile_cli_test {
+
+// Unique per-process path so tests stay isolated when ctest runs the
+// gtest-discovered cases in parallel processes.
+inline std::string unique_temp_path(const std::string& stem,
+                                    const std::string& ext) {
+    static unsigned counter = 0;
+#ifdef _WIN32
+    long pid = static_cast<long>(_getpid());
+#else
+    long pid = static_cast<long>(getpid());
+#endif
+    std::ostringstream ss;
+    ss << stem << "_" << pid << "_" << counter++ << ext;
+    return ss.str();
+}
+
+inline std::string write_table_fixture() {
+    storage::libtsfile_init();
+    std::string out_path = unique_temp_path("tsfile_cli_fixture", ".tsfile");
+    std::string table_name = "table1";
+
+    storage::WriteFile file;
+    int flags = O_WRONLY | O_CREAT | O_TRUNC;
+#ifdef _WIN32
+    flags |= O_BINARY;
+#endif
+    file.create(out_path, flags, 0666);
+
+    auto* schema = new storage::TableSchema(
+        table_name,
+        {
+            common::ColumnSchema("id1", common::STRING, common::UNCOMPRESSED,
+                                 common::PLAIN, common::ColumnCategory::TAG),
+            common::ColumnSchema("id2", common::STRING, common::UNCOMPRESSED,
+                                 common::PLAIN, common::ColumnCategory::TAG),
+            common::ColumnSchema("s1", common::INT64, common::UNCOMPRESSED,
+                                 common::PLAIN, common::ColumnCategory::FIELD),
+        });
+
+    auto* writer = new storage::TsFileTableWriter(&file, schema);
+    storage::Tablet tablet(
+        table_name, {"id1", "id2", "s1"},
+        {common::STRING, common::STRING, common::INT64},
+        {common::ColumnCategory::TAG, common::ColumnCategory::TAG,
+         common::ColumnCategory::FIELD},
+        10);
+
+    for (int row = 0; row < 5; ++row) {
+        tablet.add_timestamp(row, static_cast<int64_t>(row));
+        tablet.add_value(row, "id1", "id1_field_1");
+        tablet.add_value(row, "id2", "id2_field_2");
+        tablet.add_value(row, "s1", static_cast<int64_t>(row * 10));
+    }
+
+    writer->write_table(tablet);
+    writer->flush();
+    writer->close();
+
+    delete writer;
+    delete schema;
+    return out_path;
+}
+
+}  // namespace tsfile_cli_test
+
+#endif  // TSFILE_CLI_TEST_UTIL_H
diff --git a/cpp/test/tools/command_e2e_test.cc b/cpp/test/tools/command_e2e_test.cc
new file mode 100644
index 000000000..ccd3eba9b
--- /dev/null
+++ b/cpp/test/tools/command_e2e_test.cc
@@ -0,0 +1,910 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include <gtest/gtest.h>
+
+#include <cstdio>
+#include <fstream>
+#include <sstream>
+#include <string>
+
+#include "cli/run_cli.h"
+#include "cli_test_util.h"
+
+namespace {
+
+struct Fixture {
+    std::string path = tsfile_cli_test::write_table_fixture();
+    ~Fixture() { std::remove(path.c_str()); }
+};
+
+size_t count_lines(const std::string& s) {
+    size_t n = 0;
+    for (char c : s) {
+        if (c == '\n') {
+            ++n;
+        }
+    }
+    return n;
+}
+
+}  // namespace
+
+TEST(CliE2E, LsListsTableNameTsv) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"ls", "-f", "tsv", f.path}, out, err);
+    EXPECT_EQ(code, 0);
+    EXPECT_EQ(out.str(), "name\ntable1\n");
+    EXPECT_TRUE(err.str().empty());
+}
+
+TEST(CliE2E, LsNoHeaderJustName) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"ls", "-f", "tsv", "--no-header", f.path},
+                                   out, err);
+    EXPECT_EQ(code, 0);
+    EXPECT_EQ(out.str(), "table1\n");
+}
+
+TEST(CliE2E, OpenMissingFileReturnsFileError) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code =
+        tsfile_cli::run_cli({"ls", "definitely_missing.tsfile"}, out, err);
+    EXPECT_EQ(code, 2);
+    EXPECT_FALSE(err.str().empty());
+}
+
+TEST(CliE2E, SchemaShowsFieldColumnAndType) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"schema", "-f", "tsv", f.path}, out, err);
+    EXPECT_EQ(code, 0);
+    EXPECT_NE(
+        out.str().find("target\tmeasurement\tdatatype\tencoding\tcompression"),
+        std::string::npos);
+    EXPECT_NE(out.str().find("s1"), std::string::npos);
+    EXPECT_NE(out.str().find("INT64"), std::string::npos);
+}
+
+TEST(CliE2E, SchemaTableMeasurementFilterOnlyShowsRequestedColumn) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"schema", "-m", "s1", "-f", "tsv", f.path},
+                                   out, err);
+    EXPECT_EQ(code, 0);
+    EXPECT_NE(out.str().find("table1\ts1\tINT64"), std::string::npos);
+    EXPECT_EQ(out.str().find("table1\tid1"), std::string::npos);
+    EXPECT_EQ(out.str().find("table1\tid2"), std::string::npos);
+}
+
+TEST(CliE2E, StatsReportsCountAndTimeRange) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"stats", "-f", "tsv", f.path}, out, err);
+    EXPECT_EQ(code, 0);
+    EXPECT_NE(out.str().find("target\tmeasurement\tcount\tstart_time\tend_"
+                             "time\tmin\tmax\tfirst\tlast\tsum"),
+              std::string::npos);
+    EXPECT_NE(out.str().find("s1\t5\t0\t4\t0\t40\t0\t40\t100"),
+              std::string::npos);
+}
+
+TEST(CliE2E, HeadProjectsAndLimits) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli(
+        {"head", "-m", "s1", "-n", "2", "-f", "tsv", f.path}, out, err);
+    EXPECT_EQ(code, 0);
+    EXPECT_EQ(out.str(), "time\ts1\n0\t0\n1\t10\n");
+}
+
+TEST(CliE2E, CatReturnsAllRows) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code =
+        tsfile_cli::run_cli({"cat", "-m", "s1", "-f", "tsv", f.path}, out, err);
+    EXPECT_EQ(code, 0);
+    EXPECT_EQ(count_lines(out.str()), 6u);
+    EXPECT_NE(out.str().find("time\ts1\n"), std::string::npos);
+}
+
+TEST(CliE2E, CatWithTimeRange) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli(
+        {"cat", "-m", "s1", "--start", "2", "--end", "3", "-f", "tsv", f.path},
+        out, err);
+    EXPECT_EQ(code, 0);
+    EXPECT_EQ(out.str(), "time\ts1\n2\t20\n3\t30\n");
+}
+
+TEST(CliE2E, CatJsonIsNdjson) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli(
+        {"cat", "-m", "s1", "--start", "0", "--end", "0", "-f", "json", f.path},
+        out, err);
+    EXPECT_EQ(code, 0);
+    EXPECT_EQ(out.str(), "{\"time\":0,\"s1\":0}\n");
+}
+
+TEST(CliE2E, MetaReportsFileSummary) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"meta", "-f", "tsv", f.path}, out, err);
+    EXPECT_EQ(code, 0);
+    EXPECT_TRUE(err.str().empty());
+    EXPECT_NE(out.str().find("file\tmodel\tdevice_count\ttable_count\tseries_"
+                             "count\tstart_time\tend_time\tfile_size_bytes"),
+              std::string::npos);
+    EXPECT_NE(out.str().find("\ttable\t"), std::string::npos);
+}
+
+TEST(CliE2E, CountReportsSeriesCountsAndTotal) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"count", "-f", "tsv", f.path}, out, err);
+    EXPECT_EQ(code, 0);
+    EXPECT_TRUE(err.str().empty());
+    EXPECT_NE(out.str().find("target\tmeasurement\tcount"), std::string::npos);
+    EXPECT_NE(out.str().find("\ts1\t5"), std::string::npos);
+    EXPECT_NE(out.str().find("total\t\t"), std::string::npos);
+}
+
+TEST(CliE2E, SampleIsReproducibleWithSeed) {
+    Fixture f;
+    std::ostringstream out1;
+    std::ostringstream err1;
+    std::ostringstream out2;
+    std::ostringstream err2;
+
+    int code1 = tsfile_cli::run_cli(
+        {"sample", "-m", "s1", "-n", "3", "--seed", "7", "-f", "tsv", f.path},
+        out1, err1);
+    int code2 = tsfile_cli::run_cli(
+        {"sample", "-m", "s1", "-n", "3", "--seed", "7", "-f", "tsv", f.path},
+        out2, err2);
+
+    EXPECT_EQ(code1, 0);
+    EXPECT_EQ(code2, 0);
+    EXPECT_TRUE(err1.str().empty());
+    EXPECT_TRUE(err2.str().empty());
+    EXPECT_EQ(out1.str(), out2.str());
+    EXPECT_EQ(count_lines(out1.str()), 4u);
+    EXPECT_NE(out1.str().find("time\ts1\n"), std::string::npos);
+}
+
+TEST(CliE2E, WriteThenReadRoundTrip) {
+    std::string csv_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_write_in", ".csv");
+    {
+        std::ofstream o(csv_path.c_str());
+        o << "time,id1,s1\n0,dev,0\n1,dev,10\n2,dev,20\n";
+    }
+    std::string out_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_write_out", ".tsfile");
+
+    std::ostringstream wout;
+    std::ostringstream werr;
+    int wc = tsfile_cli::run_cli(
+        {"write", "--table", "t1", "--columns", "id1:STRING:tag,s1:INT64:field",
+         "-o", out_path, csv_path},
+        wout, werr);
+    EXPECT_EQ(wc, 0) << werr.str();
+
+    std::ostringstream cout_;
+    std::ostringstream cerr_;
+    int cc =
+        tsfile_cli::run_cli({"count", "-f", "tsv", out_path}, cout_, cerr_);
+    EXPECT_EQ(cc, 0);
+    EXPECT_NE(cout_.str().find("\ts1\t3"), std::string::npos) << cout_.str();
+
+    std::ostringstream rout;
+    std::ostringstream rerr;
+    int rc = tsfile_cli::run_cli({"cat", "-m", "s1", "-f", "tsv", out_path},
+                                 rout, rerr);
+    EXPECT_EQ(rc, 0);
+    EXPECT_EQ(rout.str(), "time\ts1\n0\t0\n1\t10\n2\t20\n");
+
+    std::remove(csv_path.c_str());
+    std::remove(out_path.c_str());
+}
+
+TEST(CliE2E, WriteThenReadFloatDoubleRoundTripLossless) {
+    std::string csv_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_fp_in", ".csv");
+    {
+        std::ofstream o(csv_path.c_str());
+        o << "time,id1,f1,d1\n0,dev,0.1,0.1\n1,dev,3.4028235,"
+             "3.141592653589793\n";
+    }
+    std::string out_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_fp_out", ".tsfile");
+
+    std::ostringstream wout;
+    std::ostringstream werr;
+    int wc =
+        tsfile_cli::run_cli({"write", "--table", "t1", "--columns",
+                             "id1:STRING:tag,f1:FLOAT:field,d1:DOUBLE:field",
+                             "-o", out_path, csv_path},
+                            wout, werr);
+    ASSERT_EQ(wc, 0) << werr.str();
+
+    std::ostringstream rout;
+    std::ostringstream rerr;
+    int rc = tsfile_cli::run_cli({"cat", "-f", "json", out_path}, rout, rerr);
+    ASSERT_EQ(rc, 0) << rerr.str();
+    // Default ostream precision (6 sig digits) would print 0.1 / 3.40282 and
+    // lose bits; max_digits10 keeps every digit needed to round-trip.
+    EXPECT_NE(rout.str().find("0.100000001"), std::string::npos) << rout.str();
+    EXPECT_NE(rout.str().find("3.40282345"), std::string::npos) << rout.str();
+    EXPECT_NE(rout.str().find("3.1415926535897931"), std::string::npos)
+        << rout.str();
+
+    std::remove(csv_path.c_str());
+    std::remove(out_path.c_str());
+}
+
+TEST(CliE2E, WriteImportsQuotedFieldWithEmbeddedNewline) {
+    std::string csv_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_nl_in", ".csv");
+    {
+        std::ofstream o(csv_path.c_str());
+        // The note field on the first row spans two physical lines inside
+        // quotes; it must import as a single row, not be split into two.
+        o << "time,id1,note\n0,dev,\"line one\nline two\"\n1,dev,plain\n";
+    }
+    std::string out_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_nl_out", ".tsfile");
+
+    std::ostringstream wout;
+    std::ostringstream werr;
+    int wc = tsfile_cli::run_cli(
+        {"write", "--table", "t1", "--columns",
+         "id1:STRING:tag,note:TEXT:field", "-o", out_path, csv_path},
+        wout, werr);
+    ASSERT_EQ(wc, 0) << werr.str();
+
+    std::ostringstream cout_;
+    std::ostringstream cerr_;
+    ASSERT_EQ(
+        tsfile_cli::run_cli({"count", "-f", "tsv", out_path}, cout_, cerr_), 0);
+    EXPECT_NE(cout_.str().find("\tnote\t2"), std::string::npos) << cout_.str();
+
+    std::ostringstream rout;
+    std::ostringstream rerr;
+    ASSERT_EQ(tsfile_cli::run_cli({"cat", "-f", "json", out_path}, rout, rerr),
+              0);
+    EXPECT_NE(rout.str().find("line one\\nline two"), std::string::npos)
+        << rout.str();
+
+    std::remove(csv_path.c_str());
+    std::remove(out_path.c_str());
+}
+
+TEST(CliE2E, WriteMissingColumnsIsUsageError) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli(
+        {"write", "--table", "t1", "-o", "x.tsfile", "in.csv"}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("--columns"), std::string::npos);
+}
+
+namespace {
+bool path_exists(const std::string& p) {
+    std::ifstream in(p.c_str());
+    return in.good();
+}
+}  // namespace
+
+TEST(CliE2E, WriteRejectsOutOfOrderTimestampsAndLeavesNoOutput) {
+    std::string csv =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_ooo", ".csv");
+    {
+        std::ofstream o(csv.c_str());
+        o << "time,s1\n5,50\n1,10\n";
+    }
+    std::string out_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_ooo_out", ".tsfile");
+
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"write", "--table", "t", "--columns",
+                                    "s1:INT64:field", "-o", out_path, csv},
+                                   out, err);
+    EXPECT_EQ(code, 3);
+    EXPECT_NE(err.str().find("strictly increasing"), std::string::npos)
+        << err.str();
+    EXPECT_NE(err.str().find("line 3"), std::string::npos) << err.str();
+    EXPECT_FALSE(path_exists(out_path)) << "failed import must leave no output";
+
+    std::remove(csv.c_str());
+    std::remove(out_path.c_str());
+}
+
+TEST(CliE2E, WriteAllowsSameTimestampAcrossDevices) {
+    std::string csv =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_md", ".csv");
+    {
+        std::ofstream o(csv.c_str());
+        o << "time,id,s1\n1,A,10\n1,B,20\n2,A,30\n";
+    }
+    std::string out_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_md_out", ".tsfile");
+
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli(
+        {"write", "--table", "t", "--columns", "id:STRING:tag,s1:INT64:field",
+         "-o", out_path, csv},
+        out, err);
+    EXPECT_EQ(code, 0) << err.str();
+
+    std::ostringstream cout_;
+    std::ostringstream cerr_;
+    tsfile_cli::run_cli({"count", "-f", "tsv", out_path}, cout_, cerr_);
+    EXPECT_NE(cout_.str().find("total\t\t3"), std::string::npos) << cout_.str();
+
+    std::remove(csv.c_str());
+    std::remove(out_path.c_str());
+}
+
+TEST(CliE2E, WriteRejectsOutputEqualsInput) {
+    std::string csv =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_alias", ".csv");
+    {
+        std::ofstream o(csv.c_str());
+        o << "time,s1\n0,1\n";
+    }
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"write", "--table", "t", "--columns",
+                                    "s1:INT64:field", "-o", csv, csv},
+                                   out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("same as the input"), std::string::npos)
+        << err.str();
+    // The input file must be untouched.
+    std::ifstream in(csv.c_str());
+    std::stringstream buf;
+    buf << in.rdbuf();
+    EXPECT_EQ(buf.str(), "time,s1\n0,1\n");
+
+    std::remove(csv.c_str());
+}
+
+TEST(CliE2E, WriteFailureOnBadValueLeavesNoOutput) {
+    std::string csv =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_badval", ".csv");
+    {
+        std::ofstream o(csv.c_str());
+        o << "time,s1\n0,notanumber\n";
+    }
+    std::string out_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_badval_out", ".tsfile");
+
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"write", "--table", "t", "--columns",
+                                    "s1:INT64:field", "-o", out_path, csv},
+                                   out, err);
+    EXPECT_EQ(code, 3);
+    EXPECT_FALSE(path_exists(out_path));
+
+    std::remove(csv.c_str());
+    std::remove(out_path.c_str());
+}
+
+TEST(CliE2E, WriteRejectsDuplicateColumnNames) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli(
+        {"write", "--table", "t", "--columns", "s1:INT64:field,s1:INT64:field",
+         "-o", "x.tsfile", "-"},
+        out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("duplicate column"), std::string::npos)
+        << err.str();
+}
+
+TEST(CliE2E, WriteRejectsHeaderMatchWithNoHeader) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli(
+        {"write", "--table", "t", "--columns", "s1:INT64:field", "-o",
+         "x.tsfile", "--no-header", "--header-match", "-"},
+        out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("--header-match"), std::string::npos) << err.str();
+}
+
+TEST(CliE2E, ReadRejectsWriteOnlyFlag) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"ls", "-o", "x.tsfile", f.path}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("only valid for write"), std::string::npos)
+        << err.str();
+}
+
+TEST(CliE2E, MetaRejectsDeviceScopeFlag) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"meta", "-d", "dev", f.path}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("not valid for meta"), std::string::npos)
+        << err.str();
+}
+
+TEST(CliE2E, SchemaTableShowsEncodingAndCompression) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"schema", "-f", "tsv", f.path}, out, err);
+    EXPECT_EQ(code, 0);
+    // Table-model schema must report real (non-empty) encoding and compression
+    // rather than blanks. The INT64 field encodes as TS_2DIFF; the compression
+    // is the engine default (build-dependent) but must not be empty.
+    EXPECT_NE(out.str().find("\ts1\tINT64\tTS_2DIFF\t"), std::string::npos)
+        << out.str();
+    EXPECT_EQ(out.str().find("\ts1\tINT64\tTS_2DIFF\t\n"), std::string::npos)
+        << out.str();
+}
+
+namespace {
+// Run a one-row `write` whose single value cell is `value`, declaring the
+// column as `type`. Returns the exit code; captures stderr into `err`.
+int write_one_value(const std::string& type, const std::string& value,
+                    std::string& err_out) {
+    std::string csv =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_ovf", ".csv");
+    {
+        std::ofstream o(csv.c_str());
+        o << "time,s1\n0," << value << "\n";
+    }
+    std::string out_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_ovf_out", ".tsfile");
+    std::ostringstream out;
+    std::ostringstream err;
+    int code =
+        tsfile_cli::run_cli({"write", "--table", "t", "--columns",
+                             "s1:" + type + ":field", "-o", out_path, csv},
+                            out, err);
+    err_out = err.str();
+    std::remove(csv.c_str());
+    std::remove(out_path.c_str());
+    return code;
+}
+}  // namespace
+
+TEST(CliE2E, WriteRejectsInt32Overflow) {
+    std::string err;
+    EXPECT_EQ(write_one_value("INT32", "3000000000", err), 3);
+    EXPECT_NE(err.find("INT32 out of range"), std::string::npos) << err;
+}
+
+TEST(CliE2E, WriteAcceptsInt32Boundary) {
+    std::string err;
+    EXPECT_EQ(write_one_value("INT32", "2147483647", err), 0) << err;
+}
+
+TEST(CliE2E, WriteRejectsInt64Overflow) {
+    std::string err;
+    EXPECT_EQ(write_one_value("INT64", "99999999999999999999999999", err), 3);
+    EXPECT_NE(err.find("INT64 out of range"), std::string::npos) << err;
+}
+
+TEST(CliE2E, WriteRejectsDoubleOverflow) {
+    std::string err;
+    EXPECT_EQ(write_one_value("DOUBLE", "1e400", err), 3);
+    EXPECT_NE(err.find("DOUBLE out of range"), std::string::npos) << err;
+}
+
+TEST(CliE2E, WriteRejectsNonNumericInt64) {
+    std::string err;
+    EXPECT_EQ(write_one_value("INT64", "12abc", err), 3);
+    EXPECT_NE(err.find("bad INT64"), std::string::npos) << err;
+}
+
+TEST(CliE2E, WriteRejectsOutOfOrderAcrossBatches) {
+    // More than one 1024-row batch of ascending rows, then a violating
+    // timestamp. The first batch is already flushed by the time the bad row is
+    // read, so this proves both that per-device tracking survives a batch flush
+    // and that the already-written output is removed on failure.
+    std::string csv =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_xbatch", ".csv");
+    {
+        std::ofstream o(csv.c_str());
+        o << "time,s1\n";
+        for (int i = 1; i <= 1100; ++i) {
+            o << i << "," << i << "\n";
+        }
+        o << "500,999\n";  // <= the last timestamp for the tag-less device
+    }
+    std::string out_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_xbatch_out", ".tsfile");
+
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"write", "--table", "t", "--columns",
+                                    "s1:INT64:field", "-o", out_path, csv},
+                                   out, err);
+    EXPECT_EQ(code, 3);
+    EXPECT_NE(err.str().find("strictly increasing"), std::string::npos)
+        << err.str();
+    EXPECT_FALSE(path_exists(out_path));
+
+    std::remove(csv.c_str());
+    std::remove(out_path.c_str());
+}
+
+TEST(CliE2E, WriteStreamsLargeInputRoundTrips) {
+    std::string csv =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_large", ".csv");
+    {
+        std::ofstream o(csv.c_str());
+        o << "time,s1\n";
+        for (int i = 1; i <= 3000; ++i) {
+            o << i << "," << (i * 2) << "\n";
+        }
+    }
+    std::string out_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_large_out", ".tsfile");
+
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"write", "--table", "big", "--columns",
+                                    "s1:INT64:field", "-o", out_path, csv},
+                                   out, err);
+    EXPECT_EQ(code, 0) << err.str();
+
+    std::ostringstream cout_;
+    std::ostringstream cerr_;
+    tsfile_cli::run_cli({"count", "-f", "tsv", out_path}, cout_, cerr_);
+    EXPECT_NE(cout_.str().find("\ts1\t3000"), std::string::npos) << cout_.str();
+
+    std::remove(csv.c_str());
+    std::remove(out_path.c_str());
+}
+
+TEST(CliE2E, HelpWithPositionalFilePrintsUsage) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"cat", "--help", f.path}, out, err);
+    EXPECT_EQ(code, 0);
+    EXPECT_NE(out.str().find("Usage:"), std::string::npos) << out.str();
+}
+
+TEST(CliE2E, StatsRejectsRowOnlyFlag) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"stats", "--start", "1", f.path}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("only valid for head/cat/sample"),
+              std::string::npos)
+        << err.str();
+}
+
+TEST(CliE2E, LsRejectsMeasurementsFlag) {
+    Fixture f;
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"ls", "-m", "s1", f.path}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("not valid for ls"), std::string::npos)
+        << err.str();
+}
+
+TEST(CliE2E, WriteRoundTripsTimestampDateBlob) {
+    std::string csv =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_tdb", ".csv");
+    {
+        std::ofstream o(csv.c_str());
+        o << "time,id1,ts1,d1,b1\n"
+             "0,dev,1700000000000,2024-01-15,hello\n"
+             "1,dev,1700000000001,2024-12-31,world\n";
+    }
+    std::string out_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_tdb_out", ".tsfile");
+
+    std::ostringstream wout;
+    std::ostringstream werr;
+    int wc = tsfile_cli::run_cli(
+        {"write", "--table", "t1", "--columns",
+         "id1:STRING:tag,ts1:TIMESTAMP:field,d1:DATE:field,b1:BLOB:field", "-o",
+         out_path, csv},
+        wout, werr);
+    ASSERT_EQ(wc, 0) << werr.str();
+
+    std::ostringstream rout;
+    std::ostringstream rerr;
+    ASSERT_EQ(tsfile_cli::run_cli({"cat", "-f", "tsv", out_path}, rout, rerr),
+              0)
+        << rerr.str();
+    // TIMESTAMP prints as raw epoch ms, DATE as YYYY-MM-DD, BLOB as its bytes.
+    EXPECT_NE(rout.str().find("1700000000000"), std::string::npos)
+        << rout.str();
+    EXPECT_NE(rout.str().find("2024-01-15"), std::string::npos) << rout.str();
+    EXPECT_NE(rout.str().find("2024-12-31"), std::string::npos) << rout.str();
+    EXPECT_NE(rout.str().find("hello"), std::string::npos) << rout.str();
+    EXPECT_NE(rout.str().find("world"), std::string::npos) << rout.str();
+
+    std::remove(csv.c_str());
+    std::remove(out_path.c_str());
+}
+
+TEST(CliE2E, WriteRejectsBadDate) {
+    std::string err;
+    EXPECT_EQ(write_one_value("DATE", "not-a-date", err), 3);
+    EXPECT_NE(err.find("bad DATE"), std::string::npos) << err;
+}
+
+TEST(CliE2E, WriteVerboseEchoesConfig) {
+    std::string csv =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_vb", ".csv");
+    {
+        std::ofstream o(csv.c_str());
+        o << "time,s1\n0,1\n";
+    }
+    std::string out_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_vb_out", ".tsfile");
+
+    std::ostringstream out;
+    std::ostringstream err;
+    int code =
+        tsfile_cli::run_cli({"write", "--table", "vt", "--columns",
+                             "s1:INT64:field", "-v", "-o", out_path, csv},
+                            out, err);
+    EXPECT_EQ(code, 0) << err.str();
+    EXPECT_NE(err.str().find("table=vt"), std::string::npos) << err.str();
+    EXPECT_NE(err.str().find("column s1:INT64:field"), std::string::npos)
+        << err.str();
+    EXPECT_NE(err.str().find("wrote 1 rows"), std::string::npos) << err.str();
+
+    std::remove(csv.c_str());
+    std::remove(out_path.c_str());
+}
+
+TEST(CliE2E, WriteHeaderMatchReportsMismatchPosition) {
+    std::string csv =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_hm", ".csv");
+    {
+        std::ofstream o(csv.c_str());
+        o << "time,wrong\n0,1\n";
+    }
+    std::string out_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_hm_out", ".tsfile");
+
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli(
+        {"write", "--table", "t", "--columns", "s1:INT64:field",
+         "--header-match", "-o", out_path, csv},
+        out, err);
+    EXPECT_EQ(code, 3);
+    EXPECT_NE(err.str().find("header column 2 is 'wrong'"), std::string::npos)
+        << err.str();
+    EXPECT_NE(err.str().find("expected 's1'"), std::string::npos) << err.str();
+
+    std::remove(csv.c_str());
+    std::remove(out_path.c_str());
+}
+
+// Every column carries a distinct, type-specific value, so the JSON output pins
+// each column name to exactly one value. This is what guards the by-index
+// add_value mapping in cmd_write: if any two columns were written to the wrong
+// slot, a key/value pair below would mismatch.
+TEST(CliE2E, WriteMapsEachColumnToItsOwnValue) {
+    std::string csv =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_colmap", ".csv");
+    {
+        std::ofstream o(csv.c_str());
+        o << "time,a_bool,b_int,c_long,d_float,e_double,f_str,g_ts,h_date\n"
+             "10,true,42,9000000000,1.5,3.25,hello,1700000000000,2024-06-15\n";
+    }
+    std::string out_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_colmap_out", ".tsfile");
+
+    std::ostringstream wout;
+    std::ostringstream werr;
+    int wc = tsfile_cli::run_cli(
+        {"write", "--table", "t1", "--columns",
+         "a_bool:BOOLEAN:field,b_int:INT32:field,c_long:INT64:field,"
+         "d_float:FLOAT:field,e_double:DOUBLE:field,f_str:STRING:field,"
+         "g_ts:TIMESTAMP:field,h_date:DATE:field",
+         "-o", out_path, csv},
+        wout, werr);
+    ASSERT_EQ(wc, 0) << werr.str();
+
+    std::ostringstream rout;
+    std::ostringstream rerr;
+    ASSERT_EQ(tsfile_cli::run_cli({"cat", "-f", "json", out_path}, rout, rerr),
+              0)
+        << rerr.str();
+    const std::string& j = rout.str();
+    EXPECT_NE(j.find("\"a_bool\":true"), std::string::npos) << j;
+    EXPECT_NE(j.find("\"b_int\":42"), std::string::npos) << j;
+    EXPECT_NE(j.find("\"c_long\":9000000000"), std::string::npos) << j;
+    EXPECT_NE(j.find("\"d_float\":1.5"), std::string::npos) << j;
+    EXPECT_NE(j.find("\"e_double\":3.25"), std::string::npos) << j;
+    EXPECT_NE(j.find("\"f_str\":\"hello\""), std::string::npos) << j;
+    EXPECT_NE(j.find("\"g_ts\":1700000000000"), std::string::npos) << j;
+    EXPECT_NE(j.find("\"h_date\":\"2024-06-15\""), std::string::npos) << j;
+
+    std::remove(csv.c_str());
+    std::remove(out_path.c_str());
+}
+
+// A multi-type import spanning several batches must keep every value in its own
+// column after each flush. Tags vary so timestamps may repeat across devices.
+TEST(CliE2E, WriteMultiTypeAcrossBatchesRoundTrips) {
+    std::string csv =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_mtb", ".csv");
+    const int kRows = 2500;  // > 2 batches of 1024
+    {
+        std::ofstream o(csv.c_str());
+        o << "time,id,n,note\n";
+        for (int i = 0; i < kRows; ++i) {
+            o << i << ",dev," << (i * 3) << ",row" << i << "\n";
+        }
+    }
+    std::string out_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_mtb_out", ".tsfile");
+
+    std::ostringstream wout;
+    std::ostringstream werr;
+    int wc = tsfile_cli::run_cli(
+        {"write", "--table", "t", "--columns",
+         "id:STRING:tag,n:INT64:field,note:TEXT:field", "-o", out_path, csv},
+        wout, werr);
+    ASSERT_EQ(wc, 0) << werr.str();
+
+    std::ostringstream cout_;
+    std::ostringstream cerr_;
+    ASSERT_EQ(
+        tsfile_cli::run_cli({"count", "-f", "tsv", out_path}, cout_, cerr_), 0);
+    EXPECT_NE(cout_.str().find("\tn\t2500"), std::string::npos) << cout_.str();
+
+    // Spot-check a row from the last batch keeps n and note paired correctly.
+    std::ostringstream rout;
+    std::ostringstream rerr;
+    ASSERT_EQ(tsfile_cli::run_cli({"cat", "--start", "2400", "--end", "2400",
+                                   "-f", "json", out_path},
+                                  rout, rerr),
+              0)
+        << rerr.str();
+    EXPECT_NE(rout.str().find("\"n\":7200"), std::string::npos) << rout.str();
+    EXPECT_NE(rout.str().find("\"note\":\"row2400\""), std::string::npos)
+        << rout.str();
+
+    std::remove(csv.c_str());
+    std::remove(out_path.c_str());
+}
+
+// A quoted STRING field containing the delimiter and escaped quotes must
+// survive import and re-export unchanged (RFC 4180 round-trip through the
+// writer).
+TEST(CliE2E, WriteRoundTripsQuotedSpecialChars) {
+    std::string csv =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_special", ".csv");
+    {
+        std::ofstream o(csv.c_str());
+        // note = a,b "q" c  (comma + embedded quotes)
+        o << "time,id,note\n0,dev,\"a,b \"\"q\"\" c\"\n";
+    }
+    std::string out_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_special_out", ".tsfile");
+
+    std::ostringstream wout;
+    std::ostringstream werr;
+    int wc = tsfile_cli::run_cli(
+        {"write", "--table", "t", "--columns",
+         "id:STRING:tag,note:STRING:field", "-o", out_path, csv},
+        wout, werr);
+    ASSERT_EQ(wc, 0) << werr.str();
+
+    // JSON escapes the embedded quotes; the comma is preserved verbatim.
+    std::ostringstream rout;
+    std::ostringstream rerr;
+    ASSERT_EQ(tsfile_cli::run_cli({"cat", "-f", "json", out_path}, rout, rerr),
+              0)
+        << rerr.str();
+    EXPECT_NE(rout.str().find("\"note\":\"a,b \\\"q\\\" c\""),
+              std::string::npos)
+        << rout.str();
+
+    std::remove(csv.c_str());
+    std::remove(out_path.c_str());
+}
+
+TEST(CliE2E, WriteRejectsTimestampOverflow) {
+    std::string err;
+    EXPECT_EQ(write_one_value("TIMESTAMP", "99999999999999999999999999", err),
+              3);
+    EXPECT_NE(err.find("TIMESTAMP out of range"), std::string::npos) << err;
+}
+
+TEST(CliE2E, WriteRejectsNonNumericTimestampColumn) {
+    std::string err;
+    EXPECT_EQ(write_one_value("TIMESTAMP", "not-a-number", err), 3);
+    EXPECT_NE(err.find("bad TIMESTAMP"), std::string::npos) << err;
+}
+
+TEST(CliE2E, WriteRejectsImpossibleDate) {
+    // Syntactically YYYY-MM-DD but not a real calendar date.
+    std::string err;
+    EXPECT_EQ(write_one_value("DATE", "2024-13-40", err), 3);
+    EXPECT_NE(err.find("bad DATE"), std::string::npos) << err;
+}
+
+TEST(CliE2E, WriteAcceptsDateBoundary) {
+    std::string err;
+    EXPECT_EQ(write_one_value("DATE", "2024-02-29", err), 0)
+        << err;  // leap day
+}
+
+// An empty cell writes a null, which JSON renders as null (not the type's
+// zero).
+TEST(CliE2E, WriteEmptyCellBecomesNull) {
+    std::string csv =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_null", ".csv");
+    {
+        std::ofstream o(csv.c_str());
+        o << "time,id,n\n0,dev,\n";  // n is empty -> null
+    }
+    std::string out_path =
+        tsfile_cli_test::unique_temp_path("tsfile_cli_null_out", ".tsfile");
+
+    std::ostringstream wout;
+    std::ostringstream werr;
+    int wc = tsfile_cli::run_cli(
+        {"write", "--table", "t", "--columns", "id:STRING:tag,n:INT64:field",
+         "-o", out_path, csv},
+        wout, werr);
+    ASSERT_EQ(wc, 0) << werr.str();
+
+    std::ostringstream rout;
+    std::ostringstream rerr;
+    ASSERT_EQ(tsfile_cli::run_cli({"cat", "-f", "json", out_path}, rout, rerr),
+              0)
+        << rerr.str();
+    EXPECT_NE(rout.str().find("\"n\":null"), std::string::npos) << rout.str();
+
+    std::remove(csv.c_str());
+    std::remove(out_path.c_str());
+}
diff --git a/cpp/test/tools/input_format_test.cc b/cpp/test/tools/input_format_test.cc
new file mode 100644
index 000000000..a3c0bda7f
--- /dev/null
+++ b/cpp/test/tools/input_format_test.cc
@@ -0,0 +1,176 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "format/input_format.h"
+
+#include <gtest/gtest.h>
+
+#include <sstream>
+
+#include "common/db_common.h"
+#include "utils/db_utils.h"
+
+TEST(InputFormatTest, ParseColumnsSpecValid) {
+    std::vector<tsfile_cli::ColumnDef> cols;
+    std::string err;
+    EXPECT_TRUE(tsfile_cli::parse_columns_spec("id1:STRING:tag,s1:INT64:field",
+                                               cols, err));
+    ASSERT_EQ(cols.size(), 2u);
+    EXPECT_EQ(cols[0].name, "id1");
+    EXPECT_EQ(cols[0].type, common::STRING);
+    EXPECT_EQ(cols[0].category, common::ColumnCategory::TAG);
+    EXPECT_EQ(cols[1].type, common::INT64);
+    EXPECT_EQ(cols[1].category, common::ColumnCategory::FIELD);
+}
+
+TEST(InputFormatTest, ParseColumnsSpecCaseInsensitiveType) {
+    std::vector<tsfile_cli::ColumnDef> cols;
+    std::string err;
+    EXPECT_TRUE(tsfile_cli::parse_columns_spec("s1:int64:field", cols, err));
+    EXPECT_EQ(cols[0].type, common::INT64);
+}
+
+TEST(InputFormatTest, ParseColumnsSpecCaseInsensitiveCategory) {
+    std::vector<tsfile_cli::ColumnDef> cols;
+    std::string err;
+    EXPECT_TRUE(tsfile_cli::parse_columns_spec("id1:STRING:TAG,s1:INT64:Field",
+                                               cols, err))
+        << err;
+    ASSERT_EQ(cols.size(), 2u);
+    EXPECT_EQ(cols[0].category, common::ColumnCategory::TAG);
+    EXPECT_EQ(cols[1].category, common::ColumnCategory::FIELD);
+}
+
+TEST(InputFormatTest, ParseColumnsSpecExtendedTypes) {
+    std::vector<tsfile_cli::ColumnDef> cols;
+    std::string err;
+    EXPECT_TRUE(tsfile_cli::parse_columns_spec(
+        "ts:TIMESTAMP:field,d:DATE:field,b:BLOB:field", cols, err))
+        << err;
+    ASSERT_EQ(cols.size(), 3u);
+    EXPECT_EQ(cols[0].type, common::TIMESTAMP);
+    EXPECT_EQ(cols[1].type, common::DATE);
+    EXPECT_EQ(cols[2].type, common::BLOB);
+}
+
+TEST(InputFormatTest, ParseColumnsSpecErrors) {
+    std::vector<tsfile_cli::ColumnDef> cols;
+    std::string err;
+    EXPECT_FALSE(tsfile_cli::parse_columns_spec("s1:NOPE:field", cols, err));
+    EXPECT_FALSE(tsfile_cli::parse_columns_spec("s1:INT64:bogus", cols, err));
+    EXPECT_FALSE(tsfile_cli::parse_columns_spec("s1:INT64", cols, err));
+    EXPECT_FALSE(tsfile_cli::parse_columns_spec("", cols, err));
+    EXPECT_FALSE(tsfile_cli::parse_columns_spec(":INT64:field", cols, err));
+}
+
+TEST(InputFormatTest, ParseColumnsSpecRejectsDuplicateNames) {
+    std::vector<tsfile_cli::ColumnDef> cols;
+    std::string err;
+    EXPECT_FALSE(tsfile_cli::parse_columns_spec("s1:INT64:field,s1:INT32:field",
+                                                cols, err));
+    EXPECT_NE(err.find("duplicate column"), std::string::npos) << err;
+}
+
+TEST(InputFormatTest, SplitLineTsv) {
+    std::vector<std::string> f =
+        tsfile_cli::split_line("0\t10\t20", '\t', false);
+    ASSERT_EQ(f.size(), 3u);
+    EXPECT_EQ(f[0], "0");
+    EXPECT_EQ(f[2], "20");
+}
+
+TEST(InputFormatTest, SplitLineCsvQuotes) {
+    std::vector<std::string> f =
+        tsfile_cli::split_line("1,\"a,b\",\"she \"\"hi\"\"\"", ',', true);
+    ASSERT_EQ(f.size(), 3u);
+    EXPECT_EQ(f[1], "a,b");
+    EXPECT_EQ(f[2], "she \"hi\"");
+}
+
+TEST(InputFormatTest, SplitLineEmptyFields) {
+    std::vector<std::string> f = tsfile_cli::split_line("0,,5", ',', true);
+    ASSERT_EQ(f.size(), 3u);
+    EXPECT_EQ(f[1], "");
+}
+
+TEST(InputFormatTest, ParseBoolCell) {
+    bool b = false;
+    EXPECT_TRUE(tsfile_cli::parse_bool_cell("true", b));
+    EXPECT_TRUE(b);
+    EXPECT_TRUE(tsfile_cli::parse_bool_cell("0", b));
+    EXPECT_FALSE(b);
+    EXPECT_FALSE(tsfile_cli::parse_bool_cell("maybe", b));
+}
+
+TEST(InputFormatTest, ReadRecordSingleLinePlain) {
+    std::istringstream in("a,b,c\nd,e,f\n");
+    std::string rec;
+    long long n = 0;
+    ASSERT_TRUE(tsfile_cli::read_record(in, true, rec, n));
+    EXPECT_EQ(rec, "a,b,c");
+    EXPECT_EQ(n, 1);
+    ASSERT_TRUE(tsfile_cli::read_record(in, true, rec, n));
+    EXPECT_EQ(rec, "d,e,f");
+    EXPECT_EQ(n, 1);
+    EXPECT_FALSE(tsfile_cli::read_record(in, true, rec, n));
+}
+
+TEST(InputFormatTest, ReadRecordJoinsQuotedNewline) {
+    std::istringstream in("1,\"line one\nline two\",x\n2,plain,y\n");
+    std::string rec;
+    long long n = 0;
+    ASSERT_TRUE(tsfile_cli::read_record(in, true, rec, n));
+    EXPECT_EQ(rec, "1,\"line one\nline two\",x");
+    EXPECT_EQ(n, 2);  // two physical lines made one record
+    // The embedded newline survives field splitting inside the quotes.
+    std::vector<std::string> f = tsfile_cli::split_line(rec, ',', true);
+    ASSERT_EQ(f.size(), 3u);
+    EXPECT_EQ(f[1], "line one\nline two");
+    ASSERT_TRUE(tsfile_cli::read_record(in, true, rec, n));
+    EXPECT_EQ(rec, "2,plain,y");
+    EXPECT_EQ(n, 1);
+}
+
+TEST(InputFormatTest, ReadRecordStripsCarriageReturn) {
+    std::istringstream in("a,b\r\nc,d\r\n");
+    std::string rec;
+    long long n = 0;
+    ASSERT_TRUE(tsfile_cli::read_record(in, true, rec, n));
+    EXPECT_EQ(rec, "a,b");
+}
+
+TEST(InputFormatTest, ReadRecordTsvIgnoresQuotes) {
+    // With csv_quotes false a quote is just data; no line joining happens.
+    std::istringstream in("1\t\"open\n2\tclosed\n");
+    std::string rec;
+    long long n = 0;
+    ASSERT_TRUE(tsfile_cli::read_record(in, false, rec, n));
+    EXPECT_EQ(rec, "1\t\"open");
+    EXPECT_EQ(n, 1);
+}
+
+TEST(InputFormatTest, ReadRecordUnterminatedQuoteAtEof) {
+    std::istringstream in("1,\"never closed\n");
+    std::string rec;
+    long long n = 0;
+    ASSERT_TRUE(tsfile_cli::read_record(in, true, rec, n));
+    EXPECT_EQ(rec, "1,\"never closed");
+    EXPECT_EQ(n, 1);
+    EXPECT_FALSE(tsfile_cli::read_record(in, true, rec, n));
+}
diff --git a/cpp/test/tools/output_format_test.cc b/cpp/test/tools/output_format_test.cc
new file mode 100644
index 000000000..abaa47dc9
--- /dev/null
+++ b/cpp/test/tools/output_format_test.cc
@@ -0,0 +1,146 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "format/output_format.h"
+
+#include <gtest/gtest.h>
+
+#include <sstream>
+#include <vector>
+
+#include "common/db_common.h"
+#include "utils/errno_define.h"
+
+using tsfile_cli::OutputFormat;
+using tsfile_cli::ParsedArgs;
+using tsfile_cli::RowWriter;
+
+TEST(ErrorCodeMessageTest, KnownCodesMapToReadablePhrases) {
+    EXPECT_STREQ(tsfile_cli::error_code_message(common::E_TABLE_NOT_EXIST),
+                 "table does not exist");
+    EXPECT_STREQ(tsfile_cli::error_code_message(common::E_DEVICE_NOT_EXIST),
+                 "device does not exist");
+    EXPECT_STREQ(
+        tsfile_cli::error_code_message(common::E_MEASUREMENT_NOT_EXIST),
+        "measurement does not exist");
+    EXPECT_STREQ(tsfile_cli::error_code_message(common::E_TSFILE_CORRUPTED),
+                 "file is corrupted");
+    EXPECT_STREQ(tsfile_cli::error_code_message(common::E_OUT_OF_ORDER),
+                 "data is out of order");
+    EXPECT_STREQ(tsfile_cli::error_code_message(common::E_DECODE_ERR),
+                 "failed to decode data");
+}
+
+TEST(ErrorCodeMessageTest, UnknownCodeFallsBackToInternalError) {
+    EXPECT_STREQ(tsfile_cli::error_code_message(987654), "internal error");
+    // The phrase is always a non-empty, printable string (never a bare code).
+    EXPECT_GT(std::string(tsfile_cli::error_code_message(-1)).size(), 0u);
+}
+
+TEST(ResolveFormatTest, AutoUsesTableOnTtyTsvOtherwise) {
+    EXPECT_EQ(tsfile_cli::resolve_format(ParsedArgs::Format::kAuto, true),
+              OutputFormat::kTable);
+    EXPECT_EQ(tsfile_cli::resolve_format(ParsedArgs::Format::kAuto, false),
+              OutputFormat::kTsv);
+    EXPECT_EQ(tsfile_cli::resolve_format(ParsedArgs::Format::kJson, true),
+              OutputFormat::kJson);
+}
+
+TEST(CsvEscapeTest, QuotesWhenSpecialCharsPresent) {
+    EXPECT_EQ(tsfile_cli::csv_escape("plain"), "plain");
+    EXPECT_EQ(tsfile_cli::csv_escape("a,b"), "\"a,b\"");
+    EXPECT_EQ(tsfile_cli::csv_escape("she said \"hi\""),
+              "\"she said \"\"hi\"\"\"");
+    EXPECT_EQ(tsfile_cli::csv_escape("line\nbreak"), "\"line\nbreak\"");
+}
+
+TEST(JsonEscapeTest, EscapesQuotesBackslashAndControls) {
+    EXPECT_EQ(tsfile_cli::json_escape("a\"b\\c"), "a\\\"b\\\\c");
+    EXPECT_EQ(tsfile_cli::json_escape("tab\there"), "tab\\there");
+}
+
+TEST(TypeNameTest, KnownTypesMapToNames) {
+    EXPECT_STREQ(tsfile_cli::tsdatatype_name(common::INT64), "INT64");
+    EXPECT_STREQ(tsfile_cli::tsdatatype_name(common::STRING), "STRING");
+    EXPECT_STREQ(tsfile_cli::tsdatatype_name(common::BOOLEAN), "BOOLEAN");
+}
+
+TEST(EncodingNameTest, KnownEncodings) {
+    EXPECT_STREQ(tsfile_cli::tsencoding_name(common::PLAIN), "PLAIN");
+    EXPECT_STREQ(tsfile_cli::tsencoding_name(common::TS_2DIFF), "TS_2DIFF");
+    EXPECT_STREQ(tsfile_cli::tsencoding_name(common::SPRINTZ), "SPRINTZ");
+}
+
+TEST(CompressionNameTest, KnownCompressors) {
+    EXPECT_STREQ(tsfile_cli::compression_name(common::UNCOMPRESSED),
+                 "UNCOMPRESSED");
+    EXPECT_STREQ(tsfile_cli::compression_name(common::SNAPPY), "SNAPPY");
+    EXPECT_STREQ(tsfile_cli::compression_name(common::LZ4), "LZ4");
+}
+
+TEST(RowWriterTest, TsvWritesHeaderThenRows) {
+    std::ostringstream out;
+    RowWriter w(out, OutputFormat::kTsv, {"time", "s1"},
+                {common::INT64, common::INT64}, false);
+    w.write({"1", "10"}, {false, false});
+    w.write({"2", ""}, {false, true});
+    w.finish();
+    EXPECT_EQ(out.str(), "time\ts1\n1\t10\n2\t\n");
+}
+
+TEST(RowWriterTest, NoHeaderSuppressesHeader) {
+    std::ostringstream out;
+    RowWriter w(out, OutputFormat::kTsv, {"name"}, {common::STRING}, true);
+    w.write({"table1"}, {false});
+    w.finish();
+    EXPECT_EQ(out.str(), "table1\n");
+}
+
+TEST(RowWriterTest, CsvEscapesCells) {
+    std::ostringstream out;
+    RowWriter w(out, OutputFormat::kCsv, {"name"}, {common::STRING}, false);
+    w.write({"a,b"}, {false});
+    w.finish();
+    EXPECT_EQ(out.str(), "name\n\"a,b\"\n");
+}
+
+TEST(RowWriterTest, JsonNumbersUnquotedStringsQuotedNullEmitted) {
+    std::ostringstream out;
+    RowWriter w(out, OutputFormat::kJson, {"time", "name"},
+                {common::INT64, common::STRING}, false);
+    w.write({"5", "dev1"}, {false, false});
+    w.write({"6", ""}, {false, true});
+    w.finish();
+    EXPECT_EQ(out.str(),
+              "{\"time\":5,\"name\":\"dev1\"}\n"
+              "{\"time\":6,\"name\":null}\n");
+}
+
+TEST(RowWriterTest, TableAlignsColumns) {
+    std::ostringstream out;
+    RowWriter w(out, OutputFormat::kTable, {"name", "type"},
+                {common::STRING, common::STRING}, false);
+    w.write({"s1", "INT64"}, {false, false});
+    w.write({"longname", "BOOLEAN"}, {false, false});
+    w.finish();
+    EXPECT_EQ(out.str(),
+              "name      type\n"
+              "s1        INT64\n"
+              "longname  BOOLEAN\n");
+}
diff --git a/cpp/test/tools/statistics_test.cc b/cpp/test/tools/statistics_test.cc
new file mode 100644
index 000000000..a151fdc3c
--- /dev/null
+++ b/cpp/test/tools/statistics_test.cc
@@ -0,0 +1,50 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "commands/statistics.h"
+
+#include <gtest/gtest.h>
+
+#include "common/statistic.h"
+
+TEST(StatisticsTest, Int64StatisticCellsContainValueSummaries) {
+    storage::Int64Statistic st;
+    st.update(1, static_cast<int64_t>(10));
+    st.update(3, static_cast<int64_t>(30));
+    tsfile_cli::StatisticCells cells = tsfile_cli::statistic_value_cells(&st);
+    EXPECT_EQ(cells.values[0], "10");
+    EXPECT_EQ(cells.values[1], "30");
+    EXPECT_EQ(cells.values[2], "10");
+    EXPECT_EQ(cells.values[3], "30");
+    EXPECT_EQ(cells.values[4], "40");
+    EXPECT_EQ(cells.is_null,
+              std::vector<bool>({false, false, false, false, false}));
+}
+
+TEST(StatisticsTest, BooleanStatisticLeavesMinMaxNull) {
+    storage::BooleanStatistic st;
+    st.update(1, true);
+    st.update(2, false);
+    tsfile_cli::StatisticCells cells = tsfile_cli::statistic_value_cells(&st);
+    EXPECT_TRUE(cells.is_null[0]);
+    EXPECT_TRUE(cells.is_null[1]);
+    EXPECT_EQ(cells.values[2], "true");
+    EXPECT_EQ(cells.values[3], "false");
+    EXPECT_EQ(cells.values[4], "1");
+}
diff --git a/cpp/tools/CMakeLists.txt b/cpp/tools/CMakeLists.txt
new file mode 100644
index 000000000..a26e4b712
--- /dev/null
+++ b/cpp/tools/CMakeLists.txt
@@ -0,0 +1,48 @@
+#[[
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+]]
+
+file(GLOB_RECURSE TSFILE_CLI_SRCS
+        "cli/*.cc"
+        "format/*.cc"
+        "commands/*.cc")
+
+add_library(tsfile_cli_obj OBJECT ${TSFILE_CLI_SRCS})
+# Tool-own headers (cli/, commands/, format/) resolve from this directory;
+# library headers come from the staged include tree like the rest of the build.
+target_include_directories(tsfile_cli_obj PUBLIC
+        ${CMAKE_CURRENT_SOURCE_DIR}
+        ${LIBRARY_INCLUDE_DIR}
+        ${THIRD_PARTY_INCLUDE})
+
+if (ENABLE_ANTLR4)
+    target_include_directories(tsfile_cli_obj PUBLIC
+            ${PROJECT_SOURCE_DIR}/third_party/antlr4-cpp-runtime-4/runtime/src)
+endif ()
+
+target_compile_definitions(tsfile_cli_obj PRIVATE
+        TSFILE_CLI_VERSION="${TsFile_CPP_VERSION}")
+
+add_executable(tsfile_cli tools_main.cc $<TARGET_OBJECTS:tsfile_cli_obj>)
+target_include_directories(tsfile_cli PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
+target_link_libraries(tsfile_cli tsfile)
+set_target_properties(tsfile_cli PROPERTIES
+        OUTPUT_NAME tsfile-cli
+        RUNTIME_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/bin)
+
+install(TARGETS tsfile_cli RUNTIME DESTINATION bin)
diff --git a/cpp/tools/README.md b/cpp/tools/README.md
new file mode 100644
index 000000000..c2621fb98
--- /dev/null
+++ b/cpp/tools/README.md
@@ -0,0 +1,217 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+
+# tsfile-cli — TsFile Command-Line Tool
+
+`tsfile-cli` is a single, pipe-friendly C++ command-line tool for inspecting **and**
+importing Apache TsFile (`.tsfile`) files from the shell — the TsFile analogue of
+`parquet-cli` / `pqrs`. Read commands print data to **stdout** and diagnostics to
+**stderr**, so they compose with `awk`, `jq`, `sort`, and friends; the `write` command
+imports CSV/TSV into a new `.tsfile`. It is built on the public `storage::TsFileReader`
+and `storage::TsFileTableWriter` APIs and does not modify the storage engine.
+
+## Building from source
+
+The CLI is part of the C++ module and is built by default (CMake option `BUILD_TOOLS=ON`).
+The CMake target is `tsfile_cli`; the produced executable is named `tsfile-cli`.
+
+**Prerequisites:** a C++11 compiler (GCC / Clang / MSVC) and CMake ≥ 3.11. The third-party
+dependencies (ANTLR4, Snappy, LZ4, LZOKAY, Zlib, GoogleTest) are bundled under
+`cpp/third_party/` and built automatically — no separate install step needed.
+
+Choose any one of the following.
+
+**1. Build script (recommended).** From `cpp/`:
+
+```bash
+bash build.sh -t=Debug      # -> cpp/build/Debug/bin/tsfile-cli
+bash build.sh               # Release (default) -> cpp/build/Release/bin/tsfile-cli
+```
+
+**2. Maven (builds the whole C++ module).** From the repository root:
+
+```bash
+./mvnw clean package -P with-cpp   # -> cpp/target/build/bin/tsfile-cli
+```
+
+**3. Plain CMake.** From `cpp/`:
+
+```bash
+mkdir -p build/Debug && cd build/Debug
+cmake ../.. -DCMAKE_BUILD_TYPE=Debug
+make -j tsfile_cli                 # -> build/Debug/bin/tsfile-cli
+```
+
+> **CMake 4.x note.** The bundled ANTLR4 runtime sets old CMake policies that CMake 4
+> rejects (`Policy CMP00xx may not be set to OLD behavior`). The reader and CLI do not use
+> ANTLR4, so disable it — `--disable-antlr4` for the build script, or `-DENABLE_ANTLR4=OFF`
+> for plain CMake:
+>
+> ```bash
+> bash build.sh -t=Debug --disable-antlr4
+> ```
+
+Verify the binary:
+
+```bash
+./build/Debug/bin/tsfile-cli --version    # -> tsfile-cli (Apache TsFile C++) <version>
+./build/Debug/bin/tsfile-cli --help
+```
+
+The executable links the `tsfile` shared library built alongside it. To run it from
+anywhere, either run it in place by its full path, or use CMake's install step
+(`cmake --install .` / `make install`), which installs the binary to `<prefix>/bin` and
+`libtsfile` to `<prefix>/lib`.
+
+## Usage
+
+```
+tsfile-cli <command> [options] <file.tsfile>
+tsfile-cli --help | --version | help
+```
+
+Exit codes: `0` success, `1` usage/argument error, `2` file open/corrupt,
+`3` query/runtime error.
+
+### Reading
+
+| Command | Description |
+|---|---|
+| `ls` | List devices (tree model) or tables (table model), one name per line |
+| `schema` | Per-series `target, measurement, datatype, encoding, compression` |
+| `meta` | File summary: model, device/table/series counts, time range, file size |
+| `stats` | Per-series `count, start_time, end_time, min, max, first, last, sum` |
+| `count` | Per-series row counts plus a `total` row (from statistics, no page scan) |
+| `head` | First N rows (default 10; use `-n`) |
+| `cat` | All matching rows, streamed |
+| `sample` | Reproducible reservoir sample (default 10; `-n`, `--seed`) |
+
+The metadata commands (`ls` / `schema` / `meta` / `stats` / `count`) answer most questions
+without decoding data pages.
+
+Shared options:
+
+| Option | Meaning |
+|---|---|
+| `-f, --format csv\|tsv\|json\|table` | Output format; defaults to `table` on a TTY, `tsv` when piped |
+| `-d, --device <id>` / `-t, --table <name>` | Scope to one device / table (mutually exclusive) |
+| `-m, --measurements a,b,c` | Column projection (`schema`, `head`, `cat`, `sample`) |
+| `-n, --limit N` / `--offset N` | Max rows / rows to skip (`head`, `cat`; `--offset` not valid for `sample`) |
+| `--start <ms>` / `--end <ms>` | Inclusive epoch-millisecond time range (`head`, `cat`, `sample`) |
+| `--seed N` | Reproducible sampling seed (`sample` only) |
+| `--no-header` | Omit the header row |
+| `--model tree\|table` | Force the model (otherwise auto-detected) |
+
+`json` output is NDJSON (one object per line; numbers/booleans bare, other values quoted,
+nulls as `null`). CSV output follows RFC 4180. Timestamps are raw epoch milliseconds.
+
+```bash
+BIN=cpp/build/Debug/bin/tsfile-cli
+$BIN ls -f tsv data.tsfile                          # list tables / devices
+$BIN meta data.tsfile                               # quick file overview
+$BIN count -t table1 -f tsv data.tsfile             # row counts, no page scan
+$BIN cat -m temp,humidity --start 1700000000000 -f csv data.tsfile | head
+$BIN sample -m temp -n 20 --seed 42 -f json data.tsfile | jq .
+```
+
+### Writing (import)
+
+`tsfile-cli write` imports CSV/TSV rows into a **new table-model** `.tsfile` (the output is
+overwritten). The first input column is the timestamp (epoch milliseconds); the remaining
+columns are declared explicitly with `--columns` — there is no type inference.
+
+Timestamps must be **strictly increasing per device**, where a device is identified by its
+`tag` column values (rows that share the same tags form one device's timeline). Rows for
+different tag combinations may freely interleave and reuse timestamps. Out-of-order input is
+rejected with the offending line number, and a failed import leaves no output file behind.
+`--output` must differ from the input file.
+
+```
+tsfile-cli write --table <name> --columns <spec> -o <out.tsfile> \
+                 [-f csv|tsv] [--no-header] [--header-match] [-v] [<input> | -]
+```
+
+`--columns` is a comma-separated list of `name:TYPE:category`, where `category` (case-insensitive)
+is `tag` or `field` and `TYPE` (case-insensitive) is one of `BOOLEAN, INT32, INT64, FLOAT, DOUBLE,
+STRING, TEXT, TIMESTAMP, DATE, BLOB` — for example `--columns "id1:STRING:tag,s1:INT64:field"`.
+`DATE` cells are written as `YYYY-MM-DD`; `TIMESTAMP` cells as epoch milliseconds. Each column is
+stored with the engine's default encoding and compression for its type.
+
+| Option | Meaning |
+|---|---|
+| `--table <name>` | Output table name (lower-cased) |
+| `--columns <spec>` | Ordered data columns (excludes the leading timestamp column) |
+| `-o, --output <path>` | Output `.tsfile` (required; overwritten) |
+| `<input>` / `-` | Input file, or `-` / omitted for stdin |
+| `-f csv\|tsv` | Input delimiter (default csv; `json` / `table` are rejected) |
+| `--no-header` | Input has no header row (default: first line is a header and is skipped) |
+| `--header-match` | Validate header names against `--columns` |
+| `-v, --verbose` | Print `wrote N rows to <out>` to stderr (otherwise silent on success) |
+
+An empty cell is written as null. The command is silent on success (Unix-style); pass `-v`
+for a one-line summary.
+
+```bash
+# round-trip through a pipe
+printf 'time,id1,s1\n0,dev,0\n1,dev,10\n' \
+  | tsfile-cli write --table t1 --columns "id1:STRING:tag,s1:INT64:field" -o out.tsfile -
+tsfile-cli count -f tsv out.tsfile          # -> t1.dev  s1  2
+```
+
+For tree-model writes, JSON input, or programmatic use, use the C++ SDK directly — see
+`cpp/examples/cpp_examples/demo_write.cpp` (`TsFileTableWriter` / `TsFileWriter` + `Tablet`).
+
+## Using the skill with an AI assistant
+
+`cpp/tools/skills/tsfile-cli/SKILL.md` is a machine-readable reference that teaches AI
+coding assistants (e.g. Claude Code) how to drive `tsfile-cli` correctly. Such assistants
+auto-discover skills from a `.claude/skills/` directory at session start, so "installing"
+the skill just means placing it there — either project-level or user-level:
+
+```bash
+# project-level (this repository only)
+mkdir -p .claude/skills/tsfile-cli
+cp cpp/tools/skills/tsfile-cli/SKILL.md .claude/skills/tsfile-cli/SKILL.md
+
+# or user-level (available in all your projects)
+mkdir -p ~/.claude/skills/tsfile-cli
+cp cpp/tools/skills/tsfile-cli/SKILL.md ~/.claude/skills/tsfile-cli/SKILL.md
+```
+
+> The installed `SKILL.md` must begin with its YAML front-matter (`--- … ---`) for the
+> assistant to detect it. The in-repo copy carries an Apache license header comment above
+> the front-matter; if discovery fails, delete that leading `<!-- … -->` block from the
+> installed copy so `---` is the first line.
+
+Start a new assistant session afterward. The skill then activates automatically when you
+ask to inspect or import a `.tsfile`; you can also invoke it explicitly (e.g. "use the
+tsfile-cli skill").
+
+## Source layout
+
+```text
+cpp/tools/
+├── tools_main.cc          # main(): forwards argv to run_cli
+├── cli/                   # argument parsing, top-level dispatch, exit codes
+├── format/                # csv/tsv/json/table output + CSV/TSV input parsing
+├── commands/              # one file per command + shared row-query / statistics helpers
+└── skills/tsfile-cli/     # model-facing skill reference (for AI assistants)
+```
diff --git a/cpp/tools/cli/cli_args.cc b/cpp/tools/cli/cli_args.cc
new file mode 100644
index 000000000..846419f34
--- /dev/null
+++ b/cpp/tools/cli/cli_args.cc
@@ -0,0 +1,213 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "cli/cli_args.h"
+
+#include <cstdlib>
+#include <sstream>
+
+namespace tsfile_cli {
+namespace {
+
+std::vector<std::string> split_csv(const std::string& s) {
+    std::vector<std::string> out;
+    std::string item;
+    std::istringstream iss(s);
+    while (std::getline(iss, item, ',')) {
+        if (!item.empty()) {
+            out.push_back(item);
+        }
+    }
+    return out;
+}
+
+bool parse_ll(const std::string& s, long long& out) {
+    if (s.empty()) {
+        return false;
+    }
+    char* endp = nullptr;
+    long long v = std::strtoll(s.c_str(), &endp, 10);
+    if (endp == nullptr || *endp != '\0') {
+        return false;
+    }
+    out = v;
+    return true;
+}
+
+bool parse_format(const std::string& s, ParsedArgs::Format& out) {
+    if (s == "csv") {
+        out = ParsedArgs::Format::kCsv;
+    } else if (s == "tsv") {
+        out = ParsedArgs::Format::kTsv;
+    } else if (s == "json") {
+        out = ParsedArgs::Format::kJson;
+    } else if (s == "table") {
+        out = ParsedArgs::Format::kTable;
+    } else {
+        return false;
+    }
+    return true;
+}
+
+}  // namespace
+
+ParsedArgs parse_args(const std::vector<std::string>& args) {
+    ParsedArgs p;
+    if (args.empty()) {
+        return p;
+    }
+    p.command = args[0];
+    if (p.command == "--version") {
+        p.version = true;
+    }
+    if (p.command == "--help" || p.command == "-h") {
+        p.help = true;
+    }
+    // The subcommand must come first. A leading option means it was omitted;
+    // say so explicitly instead of failing later with a confusing message about
+    // the first real positional argument.
+    if (p.command.size() > 1 && p.command[0] == '-' && !p.version && !p.help) {
+        p.error = "the command must come before options (got option '" +
+                  p.command + "'); run with --help for usage";
+        return p;
+    }
+
+    size_t i = 1;
+    auto need_value = [&](const std::string& flag, std::string& dst) -> bool {
+        if (i + 1 >= args.size()) {
+            p.error = "Missing value for " + flag;
+            return false;
+        }
+        dst = args[++i];
+        return true;
+    };
+
+    for (; i < args.size(); ++i) {
+        const std::string& a = args[i];
+        std::string val;
+        if (a == "-f" || a == "--format") {
+            if (!need_value(a, val)) {
+                return p;
+            }
+            if (!parse_format(val, p.format)) {
+                p.error =
+                    "Invalid format: " + val + " (use csv|tsv|json|table)";
+                return p;
+            }
+        } else if (a == "-d" || a == "--device") {
+            if (!need_value(a, p.device)) {
+                return p;
+            }
+        } else if (a == "-t" || a == "--table") {
+            if (!need_value(a, p.table)) {
+                return p;
+            }
+        } else if (a == "-m" || a == "--measurements") {
+            if (!need_value(a, val)) {
+                return p;
+            }
+            p.measurements = split_csv(val);
+        } else if (a == "-n" || a == "--limit") {
+            if (!need_value(a, val)) {
+                return p;
+            }
+            if (!parse_ll(val, p.limit)) {
+                p.error = "Invalid -n/--limit: " + val;
+                return p;
+            }
+        } else if (a == "--offset") {
+            if (!need_value(a, val)) {
+                return p;
+            }
+            if (!parse_ll(val, p.offset)) {
+                p.error = "Invalid --offset: " + val;
+                return p;
+            }
+        } else if (a == "--start") {
+            if (!need_value(a, val)) {
+                return p;
+            }
+            if (!parse_ll(val, p.start)) {
+                p.error = "Invalid --start: " + val;
+                return p;
+            }
+            p.has_start = true;
+        } else if (a == "--end") {
+            if (!need_value(a, val)) {
+                return p;
+            }
+            if (!parse_ll(val, p.end)) {
+                p.error = "Invalid --end: " + val;
+                return p;
+            }
+            p.has_end = true;
+        } else if (a == "--seed") {
+            if (!need_value(a, val)) {
+                return p;
+            }
+            if (!parse_ll(val, p.seed)) {
+                p.error = "Invalid --seed: " + val;
+                return p;
+            }
+            p.has_seed = true;
+        } else if (a == "-o" || a == "--output") {
+            if (!need_value(a, p.output)) {
+                return p;
+            }
+        } else if (a == "--columns") {
+            if (!need_value(a, p.columns)) {
+                return p;
+            }
+        } else if (a == "-v" || a == "--verbose") {
+            p.verbose = true;
+        } else if (a == "--header-match") {
+            p.header_match = true;
+        } else if (a == "--model") {
+            if (!need_value(a, val)) {
+                return p;
+            }
+            if (val != "tree" && val != "table") {
+                p.error = "Invalid --model: " + val + " (use tree|table)";
+                return p;
+            }
+            p.model = val;
+        } else if (a == "--no-header") {
+            p.no_header = true;
+        } else if (a == "-h" || a == "--help") {
+            p.help = true;
+            return p;  // help wins; stop parsing the rest
+        } else if (a == "--version") {
+            p.version = true;
+            return p;  // version wins; stop parsing the rest
+        } else if (a.size() > 1 && a[0] == '-') {
+            p.error = "Unknown flag: " + a;
+            return p;
+        } else {
+            if (p.file.empty()) {
+                p.file = a;
+            } else {
+                p.error = "Unexpected argument: " + a;
+                return p;
+            }
+        }
+    }
+    return p;
+}
+
+}  // namespace tsfile_cli
diff --git a/cpp/tools/cli/cli_args.h b/cpp/tools/cli/cli_args.h
new file mode 100644
index 000000000..90fa95e79
--- /dev/null
+++ b/cpp/tools/cli/cli_args.h
@@ -0,0 +1,62 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#ifndef TSFILE_CLI_CLI_ARGS_H
+#define TSFILE_CLI_CLI_ARGS_H
+
+#include <climits>
+#include <string>
+#include <vector>
+
+namespace tsfile_cli {
+
+struct ParsedArgs {
+    enum class Format { kAuto, kCsv, kTsv, kJson, kTable };
+
+    std::string command;  // subcommand, e.g. "ls"/"write" (args[0])
+    std::string file;     // positional <file.tsfile>; for write, the CSV/TSV
+                          // input ("" or "-" means read stdin)
+    std::string device;   // -d/--device filter (tree model)
+    std::string table;    // -t/--table filter (table model); write target table
+    std::vector<std::string> measurements;  // -m/--measurements projection
+    long long limit = -1;          // -n/--limit; -1 means unlimited
+    long long offset = 0;          // --offset; rows to skip before emitting
+    long long start = LLONG_MIN;   // --start; inclusive lower time bound
+    long long end = LLONG_MAX;     // --end; inclusive upper time bound
+    bool has_start = false;        // whether --start was supplied
+    bool has_end = false;          // whether --end was supplied
+    long long seed = 0;            // --seed for the reservoir sampler
+    bool has_seed = false;         // whether --seed was supplied
+    Format format = Format::kAuto;  // -f/--format; kAuto resolves by TTY
+    bool no_header = false;        // --no-header; suppress header row
+    std::string model;             // --model tree|table override ("" = auto)
+    std::string output;            // -o/--output; write destination .tsfile
+    std::string columns;           // --columns spec for write (name:TYPE:cat,..)
+    bool verbose = false;          // -v/--verbose; write progress to stderr
+    bool header_match = false;     // --header-match; validate write header row
+    bool help = false;             // -h/--help requested
+    bool version = false;          // --version requested
+    std::string error;             // non-empty if parsing failed (the message)
+};
+
+ParsedArgs parse_args(const std::vector<std::string>& args);
+
+}  // namespace tsfile_cli
+
+#endif  // TSFILE_CLI_CLI_ARGS_H
diff --git a/cpp/tools/cli/exit_codes.h b/cpp/tools/cli/exit_codes.h
new file mode 100644
index 000000000..0ab6dfdf5
--- /dev/null
+++ b/cpp/tools/cli/exit_codes.h
@@ -0,0 +1,32 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#ifndef TSFILE_CLI_EXIT_CODES_H
+#define TSFILE_CLI_EXIT_CODES_H
+
+namespace tsfile_cli {
+
+constexpr int kExitOk = 0;
+constexpr int kExitUsage = 1;
+constexpr int kExitFile = 2;
+constexpr int kExitRuntime = 3;
+
+}  // namespace tsfile_cli
+
+#endif  // TSFILE_CLI_EXIT_CODES_H
diff --git a/cpp/tools/cli/run_cli.cc b/cpp/tools/cli/run_cli.cc
new file mode 100644
index 000000000..d6103c82d
--- /dev/null
+++ b/cpp/tools/cli/run_cli.cc
@@ -0,0 +1,289 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "cli/run_cli.h"
+
+#include <cstdio>
+#include <set>
+
+#include "cli/cli_args.h"
+#include "cli/exit_codes.h"
+#include "commands/commands.h"
+#include "format/output_format.h"
+#include "reader/tsfile_reader.h"
+
+#ifdef _WIN32
+#include <io.h>
+#define TSFILE_ISATTY _isatty
+#define TSFILE_FILENO _fileno
+#else
+#include <unistd.h>
+#define TSFILE_ISATTY isatty
+#define TSFILE_FILENO fileno
+#endif
+
+#ifndef TSFILE_CLI_VERSION
+#define TSFILE_CLI_VERSION "unknown"
+#endif
+
+namespace tsfile_cli {
+namespace {
+
+void print_usage(std::ostream& os) {
+    os << "Usage: tsfile-cli <command> [options] <file.tsfile>\n"
+          "Commands:\n"
+          "  ls       list devices (tree) or tables (table)\n"
+          "  schema   per-measurement data type/encoding/compression\n"
+          "  meta     file metadata summary\n"
+          "  stats    per-series count, time range, "
+          "min/max/first/last/sum\n"
+          "  head     first N rows (use -n)\n"
+          "  cat      all rows of a device/table\n"
+          "  count    number of rows (per series, plus a total)\n"
+          "  sample   deterministic sample rows (use -n and --seed)\n"
+          "  write    import CSV/TSV rows into a new table tsfile "
+          "(--table, --columns, -o)\n"
+          "Options:\n"
+          "  -f, --format csv|tsv|json|table  output format "
+          "(default: table on a TTY, tsv when piped)\n"
+          "  -d, --device <name>      restrict to one device (tree model)\n"
+          "  -t, --table <name>       restrict to one table (table model)\n"
+          "  -m, --measurements a,b   project only these measurements\n"
+          "  -n, --limit N            max rows (head/cat/sample)\n"
+          "      --offset N           skip N rows before emitting\n"
+          "      --start <ms>         inclusive lower time bound\n"
+          "      --end <ms>           inclusive upper time bound\n"
+          "      --seed N             RNG seed for sample\n"
+          "      --no-header          omit the header row\n"
+          "      --model tree|table   force the data model (else auto)\n"
+          "  -h, --help               print this help\n"
+          "      --version            print version\n"
+          "Write options:\n"
+          "      --table <name>       target table name (required)\n"
+          "      --columns SPEC       column spec name:TYPE:tag|field,... "
+          "(required)\n"
+          "  -o, --output <file>      destination .tsfile (required)\n"
+          "      --header-match       require the input header to match "
+          "--columns\n"
+          "  -v, --verbose            report rows written to stderr\n";
+}
+
+bool is_known_command(const std::string& c) {
+    static const std::set<std::string> kCmds = {"ls",    "schema", "meta",
+                                                "stats", "head",   "cat",
+                                                "count", "sample", "write"};
+    return kCmds.find(c) != kCmds.end();
+}
+
+bool validate_command_flags(const ParsedArgs& p, std::ostream& err) {
+    if (p.has_seed && p.command != "sample") {
+        err << "Error: --seed is only valid for sample\n";
+        return false;
+    }
+    if (p.command == "sample" && p.offset != 0) {
+        err << "Error: --offset is not valid for sample\n";
+        return false;
+    }
+    if (!p.device.empty() && !p.table.empty()) {
+        err << "Error: -d/--device and -t/--table cannot be used together\n";
+        return false;
+    }
+    if (p.limit < -1) {
+        err << "Error: -n/--limit must be >= -1\n";
+        return false;
+    }
+    if (p.offset < 0) {
+        err << "Error: --offset must be >= 0\n";
+        return false;
+    }
+    if (p.has_start && p.has_end && p.start > p.end) {
+        err << "Error: --start must be <= --end\n";
+        return false;
+    }
+    return true;
+}
+
+bool validate_write_flags(const ParsedArgs& p, std::ostream& err) {
+    if (p.table.empty()) {
+        err << "Error: write requires -t/--table\n";
+        return false;
+    }
+    if (p.columns.empty()) {
+        err << "Error: write requires --columns\n";
+        return false;
+    }
+    if (p.output.empty()) {
+        err << "Error: write requires -o/--output\n";
+        return false;
+    }
+    if (p.format == ParsedArgs::Format::kJson ||
+        p.format == ParsedArgs::Format::kTable) {
+        err << "Error: write input format must be csv or tsv\n";
+        return false;
+    }
+    if (p.no_header && p.header_match) {
+        err << "Error: --header-match cannot be combined with --no-header\n";
+        return false;
+    }
+    if (!p.measurements.empty() || !p.device.empty() || p.has_start ||
+        p.has_end || p.has_seed || p.limit != -1 || p.offset != 0) {
+        err << "Error: read-only flags are not valid for write\n";
+        return false;
+    }
+    return true;
+}
+
+// Reject flags that have no effect for the given read command, instead of
+// silently ignoring them, so misuse is caught rather than producing surprising
+// output. Only called for non-write commands; write has its own validation.
+bool validate_read_flag_applicability(const ParsedArgs& p, std::ostream& err) {
+    const std::string& c = p.command;
+    const bool is_row = (c == "head" || c == "cat" || c == "sample");
+    const bool scoped =
+        is_row || c == "schema" || c == "stats" || c == "count";
+
+    if (!p.output.empty()) {
+        err << "Error: -o/--output is only valid for write\n";
+        return false;
+    }
+    if (!p.columns.empty()) {
+        err << "Error: --columns is only valid for write\n";
+        return false;
+    }
+    if (p.header_match) {
+        err << "Error: --header-match is only valid for write\n";
+        return false;
+    }
+    if (p.verbose) {
+        err << "Error: -v/--verbose is only valid for write\n";
+        return false;
+    }
+    if (!is_row && p.limit != -1) {
+        err << "Error: -n/--limit is only valid for head/cat/sample\n";
+        return false;
+    }
+    if (!is_row && (p.has_start || p.has_end)) {
+        err << "Error: --start/--end are only valid for head/cat/sample\n";
+        return false;
+    }
+    if (!scoped && !p.device.empty()) {
+        err << "Error: -d/--device is not valid for " << c << "\n";
+        return false;
+    }
+    if (!scoped && !p.table.empty()) {
+        err << "Error: -t/--table is not valid for " << c << "\n";
+        return false;
+    }
+    if (!scoped && !p.measurements.empty()) {
+        err << "Error: -m/--measurements is not valid for " << c << "\n";
+        return false;
+    }
+    return true;
+}
+
+}  // namespace
+
+int run_cli(const std::vector<std::string>& args, std::ostream& out,
+            std::ostream& err) {
+    ParsedArgs p = parse_args(args);
+
+    if (p.version) {
+        out << "tsfile-cli (Apache TsFile C++) " << TSFILE_CLI_VERSION << "\n";
+        return kExitOk;
+    }
+    if (args.empty()) {
+        print_usage(err);
+        return kExitUsage;
+    }
+    if (p.command == "help" || p.command == "--help" || p.command == "-h" ||
+        p.help) {
+        print_usage(out);
+        return kExitOk;
+    }
+    if (!p.error.empty()) {
+        err << "Error: " << p.error << "\n";
+        print_usage(err);
+        return kExitUsage;
+    }
+    if (!is_known_command(p.command)) {
+        err << "Unknown command: " << p.command << "\n";
+        print_usage(err);
+        return kExitUsage;
+    }
+    if (p.command != "write" && p.file.empty()) {
+        err << "Error: missing <file.tsfile> argument\n";
+        return kExitUsage;
+    }
+    if (!validate_command_flags(p, err)) {
+        print_usage(err);
+        return kExitUsage;
+    }
+
+    if (p.command == "write") {
+        if (!validate_write_flags(p, err)) {
+            print_usage(err);
+            return kExitUsage;
+        }
+        storage::libtsfile_init();
+        return cmd_write(p, out, err);
+    }
+
+    if (!validate_read_flag_applicability(p, err)) {
+        print_usage(err);
+        return kExitUsage;
+    }
+
+    storage::libtsfile_init();
+    storage::TsFileReader reader;
+    int open_ret = reader.open(p.file);
+    if (open_ret != 0) {
+        err << "Error: cannot open or corrupted file: " << p.file << "\n";
+        return kExitFile;
+    }
+
+    bool stdout_tty = TSFILE_ISATTY(TSFILE_FILENO(stdout)) != 0;
+    OutputFormat fmt = resolve_format(p.format, stdout_tty);
+
+    int code;
+    if (p.command == "ls") {
+        code = cmd_ls(p, reader, fmt, out, err);
+    } else if (p.command == "schema") {
+        code = cmd_schema(p, reader, fmt, out, err);
+    } else if (p.command == "meta") {
+        code = cmd_meta(p, reader, fmt, out, err);
+    } else if (p.command == "stats") {
+        code = cmd_stats(p, reader, fmt, out, err);
+    } else if (p.command == "head") {
+        code = cmd_head(p, reader, fmt, out, err);
+    } else if (p.command == "cat") {
+        code = cmd_cat(p, reader, fmt, out, err);
+    } else if (p.command == "count") {
+        code = cmd_count(p, reader, fmt, out, err);
+    } else if (p.command == "sample") {
+        code = cmd_sample(p, reader, fmt, out, err);
+    } else {
+        err << "Unknown command: " << p.command << "\n";
+        code = kExitUsage;
+    }
+
+    reader.close();
+    return code;
+}
+
+}  // namespace tsfile_cli
diff --git a/cpp/tools/cli/run_cli.h b/cpp/tools/cli/run_cli.h
new file mode 100644
index 000000000..79439d152
--- /dev/null
+++ b/cpp/tools/cli/run_cli.h
@@ -0,0 +1,34 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#ifndef TSFILE_CLI_RUN_CLI_H
+#define TSFILE_CLI_RUN_CLI_H
+
+#include <ostream>
+#include <string>
+#include <vector>
+
+namespace tsfile_cli {
+
+int run_cli(const std::vector<std::string>& args, std::ostream& out,
+            std::ostream& err);
+
+}  // namespace tsfile_cli
+
+#endif  // TSFILE_CLI_RUN_CLI_H
diff --git a/cpp/tools/commands/cmd_cat.cc b/cpp/tools/commands/cmd_cat.cc
new file mode 100644
index 000000000..b1af65d98
--- /dev/null
+++ b/cpp/tools/commands/cmd_cat.cc
@@ -0,0 +1,29 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "commands/commands.h"
+
+namespace tsfile_cli {
+
+int cmd_cat(const ParsedArgs& args, storage::TsFileReader& reader,
+            OutputFormat fmt, std::ostream& out, std::ostream& err) {
+    return run_row_query(args, reader, fmt, out, err, args.offset, args.limit);
+}
+
+}  // namespace tsfile_cli
diff --git a/cpp/tools/commands/cmd_count.cc b/cpp/tools/commands/cmd_count.cc
new file mode 100644
index 000000000..9480744c6
--- /dev/null
+++ b/cpp/tools/commands/cmd_count.cc
@@ -0,0 +1,47 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include <string>
+#include <vector>
+
+#include "cli/exit_codes.h"
+#include "commands/commands.h"
+#include "commands/statistics.h"
+
+namespace tsfile_cli {
+
+int cmd_count(const ParsedArgs& args, storage::TsFileReader& reader,
+              OutputFormat fmt, std::ostream& out, std::ostream& /*err*/) {
+    RowWriter w(out, fmt, {"target", "measurement", "count"},
+                {common::STRING, common::STRING, common::INT64},
+                args.no_header);
+
+    long long total = 0;
+    std::vector<SeriesStatRow> rows = collect_series_stats(args, reader);
+    for (const SeriesStatRow& row : rows) {
+        total += row.count;
+        w.write({row.target, row.measurement, std::to_string(row.count)},
+                {false, false, false});
+    }
+    w.write({"total", "", std::to_string(total)}, {false, true, false});
+    w.finish();
+    return kExitOk;
+}
+
+}  // namespace tsfile_cli
diff --git a/cpp/tools/commands/cmd_head.cc b/cpp/tools/commands/cmd_head.cc
new file mode 100644
index 000000000..06b01908f
--- /dev/null
+++ b/cpp/tools/commands/cmd_head.cc
@@ -0,0 +1,30 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "commands/commands.h"
+
+namespace tsfile_cli {
+
+int cmd_head(const ParsedArgs& args, storage::TsFileReader& reader,
+             OutputFormat fmt, std::ostream& out, std::ostream& err) {
+    long long limit = args.limit < 0 ? 10 : args.limit;
+    return run_row_query(args, reader, fmt, out, err, args.offset, limit);
+}
+
+}  // namespace tsfile_cli
diff --git a/cpp/tools/commands/cmd_ls.cc b/cpp/tools/commands/cmd_ls.cc
new file mode 100644
index 000000000..675151e8a
--- /dev/null
+++ b/cpp/tools/commands/cmd_ls.cc
@@ -0,0 +1,64 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include <string>
+#include <vector>
+
+#include "cli/exit_codes.h"
+#include "commands/commands.h"
+#include "reader/tsfile_reader.h"
+
+namespace tsfile_cli {
+
+bool is_table_model(const ParsedArgs& args, storage::TsFileReader& reader) {
+    if (args.model == "tree") {
+        return false;
+    }
+    if (args.model == "table") {
+        return true;
+    }
+    return !reader.get_all_table_schemas().empty();
+}
+
+int cmd_ls(const ParsedArgs& args, storage::TsFileReader& reader,
+           OutputFormat fmt, std::ostream& out, std::ostream& /*err*/) {
+    std::vector<std::string> names;
+    if (is_table_model(args, reader)) {
+        for (auto& ts : reader.get_all_table_schemas()) {
+            if (ts) {
+                names.push_back(ts->get_table_name());
+            }
+        }
+    } else {
+        for (auto& dev : reader.get_all_device_ids()) {
+            if (dev) {
+                names.push_back(dev->get_device_name());
+            }
+        }
+    }
+
+    RowWriter w(out, fmt, {"name"}, {common::STRING}, args.no_header);
+    for (const std::string& n : names) {
+        w.write({n}, {false});
+    }
+    w.finish();
+    return kExitOk;
+}
+
+}  // namespace tsfile_cli
diff --git a/cpp/tools/commands/cmd_meta.cc b/cpp/tools/commands/cmd_meta.cc
new file mode 100644
index 000000000..dd70029f3
--- /dev/null
+++ b/cpp/tools/commands/cmd_meta.cc
@@ -0,0 +1,50 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include <string>
+
+#include "cli/exit_codes.h"
+#include "commands/commands.h"
+#include "commands/statistics.h"
+#include "reader/tsfile_reader.h"
+
+namespace tsfile_cli {
+
+int cmd_meta(const ParsedArgs& args, storage::TsFileReader& reader,
+             OutputFormat fmt, std::ostream& out, std::ostream& /*err*/) {
+    RowWriter w(out, fmt,
+                {"file", "model", "device_count", "table_count", "series_count",
+                 "start_time", "end_time", "file_size_bytes"},
+                {common::STRING, common::STRING, common::INT64, common::INT64,
+                 common::INT64, common::INT64, common::INT64, common::INT64},
+                args.no_header);
+
+    FileSummary s = collect_file_summary(args, reader);
+    w.write({s.file, s.model, std::to_string(s.device_count),
+             std::to_string(s.table_count), std::to_string(s.series_count),
+             s.has_time_range ? std::to_string(s.start_time) : "",
+             s.has_time_range ? std::to_string(s.end_time) : "",
+             std::to_string(s.file_size_bytes)},
+            {false, false, false, false, false, !s.has_time_range,
+             !s.has_time_range, false});
+    w.finish();
+    return kExitOk;
+}
+
+}  // namespace tsfile_cli
diff --git a/cpp/tools/commands/cmd_sample.cc b/cpp/tools/commands/cmd_sample.cc
new file mode 100644
index 000000000..1123df26a
--- /dev/null
+++ b/cpp/tools/commands/cmd_sample.cc
@@ -0,0 +1,90 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include <limits>
+#include <string>
+#include <vector>
+
+#include "cli/exit_codes.h"
+#include "commands/commands.h"
+#include "common/schema.h"
+#include "format/result_set_format.h"
+#include "reader/tsfile_reader.h"
+
+namespace tsfile_cli {
+
+int cmd_sample(const ParsedArgs& args, storage::TsFileReader& reader,
+               OutputFormat fmt, std::ostream& out, std::ostream& err) {
+    const int64_t start = args.has_start ? static_cast<int64_t>(args.start)
+                                         : std::numeric_limits<int64_t>::min();
+    const int64_t end = args.has_end ? static_cast<int64_t>(args.end)
+                                     : std::numeric_limits<int64_t>::max();
+    storage::ResultSet* rs = nullptr;
+    int qret = 0;
+
+    if (is_table_model(args, reader)) {
+        std::string table_name = args.table;
+        if (table_name.empty()) {
+            auto schemas = reader.get_all_table_schemas();
+            if (schemas.empty() || !schemas[0]) {
+                err << "Error: no table found in file\n";
+                return kExitRuntime;
+            }
+            table_name = schemas[0]->get_table_name();
+        }
+        std::vector<std::string> cols = args.measurements;
+        if (cols.empty()) {
+            auto ts = reader.get_table_schema(table_name);
+            if (ts) {
+                cols = ts->get_measurement_names();
+            }
+        }
+        qret = reader.query(table_name, cols, start, end, rs);
+    } else {
+        std::vector<std::string> paths = collect_tree_query_paths(args, reader);
+        if (paths.empty()) {
+            err << "Error: no time series found\n";
+            return kExitRuntime;
+        }
+        qret = reader.query(paths, start, end, rs);
+    }
+
+    if (qret != 0 || rs == nullptr) {
+        err << "Error: query failed: " << error_code_message(qret) << "\n";
+        if (rs != nullptr) {
+            reader.destroy_query_data_set(rs);
+        }
+        return kExitRuntime;
+    }
+
+    const long long limit = args.limit < 0 ? 10 : args.limit;
+    const unsigned long long seed =
+        args.has_seed ? static_cast<unsigned long long>(args.seed) : 0ULL;
+    int wret =
+        emit_result_set_sampled(rs, fmt, args.no_header, out, limit, seed);
+    reader.destroy_query_data_set(rs);
+    if (wret != 0) {
+        err << "Error: failed to read rows: " << error_code_message(wret)
+            << "\n";
+        return kExitRuntime;
+    }
+    return kExitOk;
+}
+
+}  // namespace tsfile_cli
diff --git a/cpp/tools/commands/cmd_schema.cc b/cpp/tools/commands/cmd_schema.cc
new file mode 100644
index 000000000..3e03f4f99
--- /dev/null
+++ b/cpp/tools/commands/cmd_schema.cc
@@ -0,0 +1,129 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include <algorithm>
+#include <map>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "cli/exit_codes.h"
+#include "commands/commands.h"
+#include "common/schema.h"
+#include "reader/tsfile_reader.h"
+
+namespace tsfile_cli {
+namespace {
+
+void write_table_schema_rows(const ParsedArgs& args,
+                             storage::TsFileReader& reader, RowWriter& w) {
+    auto schemas = reader.get_all_table_schemas();
+    for (auto& schema : schemas) {
+        if (!schema) {
+            continue;
+        }
+        if (!args.table.empty() && schema->get_table_name() != args.table) {
+            continue;
+        }
+        for (const auto& ms : schema->get_measurement_schemas()) {
+            if (!ms) {
+                continue;
+            }
+            const std::string& name = ms->measurement_name_;
+            if (!args.measurements.empty() &&
+                std::find(args.measurements.begin(), args.measurements.end(),
+                          name) == args.measurements.end()) {
+                continue;
+            }
+            w.write({schema->get_table_name(), name,
+                     tsdatatype_name(ms->data_type_),
+                     tsencoding_name(ms->encoding_),
+                     compression_name(ms->compression_type_)},
+                    {false, false, false, false, false});
+        }
+    }
+}
+
+}  // namespace
+
+int cmd_schema(const ParsedArgs& args, storage::TsFileReader& reader,
+               OutputFormat fmt, std::ostream& out, std::ostream& /*err*/) {
+    RowWriter w(
+        out, fmt,
+        {"target", "measurement", "datatype", "encoding", "compression"},
+        {common::STRING, common::STRING, common::STRING, common::STRING,
+         common::STRING},
+        args.no_header);
+
+    if (is_table_model(args, reader)) {
+        write_table_schema_rows(args, reader, w);
+        w.finish();
+        return kExitOk;
+    }
+
+    storage::DeviceTimeseriesMetadataMap meta =
+        reader.get_timeseries_metadata();
+    for (auto& kv : meta) {
+        std::string target = kv.first ? kv.first->get_device_name() : "";
+        if (!args.device.empty() && target != args.device) {
+            continue;
+        }
+
+        // The timeseries metadata (kv.second) carries the data type but not the
+        // encoding/compression, so fetch the measurement schema separately to
+        // fill those two columns, keyed by measurement name.
+        std::map<std::string, std::pair<std::string, std::string>> enc_comp;
+        if (kv.first) {
+            std::vector<storage::MeasurementSchema> ms;
+            if (reader.get_timeseries_schema(kv.first, ms) == 0) {
+                for (auto& m : ms) {
+                    enc_comp[m.measurement_name_] =
+                        std::make_pair(tsencoding_name(m.encoding_),
+                                       compression_name(m.compression_type_));
+                }
+            }
+        }
+
+        for (auto& ts : kv.second) {
+            if (!ts) {
+                continue;
+            }
+            std::string m = ts->get_measurement_name().to_std_string();
+            if (!args.measurements.empty() &&
+                std::find(args.measurements.begin(), args.measurements.end(),
+                          m) == args.measurements.end()) {
+                continue;
+            }
+            std::string enc;
+            std::string comp;
+            auto it = enc_comp.find(m);
+            if (it != enc_comp.end()) {
+                enc = it->second.first;
+                comp = it->second.second;
+            }
+            w.write(
+                {target, m, tsdatatype_name(ts->get_data_type()), enc, comp},
+                {false, false, false, enc.empty(), comp.empty()});
+        }
+    }
+    w.finish();
+    return kExitOk;
+}
+
+}  // namespace tsfile_cli
diff --git a/cpp/tools/commands/cmd_stats.cc b/cpp/tools/commands/cmd_stats.cc
new file mode 100644
index 000000000..898ca469b
--- /dev/null
+++ b/cpp/tools/commands/cmd_stats.cc
@@ -0,0 +1,57 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include <string>
+#include <vector>
+
+#include "cli/exit_codes.h"
+#include "commands/commands.h"
+#include "commands/statistics.h"
+
+namespace tsfile_cli {
+
+int cmd_stats(const ParsedArgs& args, storage::TsFileReader& reader,
+              OutputFormat fmt, std::ostream& out, std::ostream& /*err*/) {
+    RowWriter w(out, fmt,
+                {"target", "measurement", "count", "start_time", "end_time",
+                 "min", "max", "first", "last", "sum"},
+                {common::STRING, common::STRING, common::INT64, common::INT64,
+                 common::INT64, common::STRING, common::STRING, common::STRING,
+                 common::STRING, common::STRING},
+                args.no_header);
+
+    std::vector<SeriesStatRow> rows = collect_series_stats(args, reader);
+    for (const SeriesStatRow& row : rows) {
+        std::vector<std::string> cells = {
+            row.target, row.measurement, std::to_string(row.count),
+            std::to_string(row.start_time), std::to_string(row.end_time)};
+        cells.insert(cells.end(), row.value_cells.values.begin(),
+                     row.value_cells.values.end());
+
+        std::vector<bool> nulls = {false, false, false, row.count == 0,
+                                   row.count == 0};
+        nulls.insert(nulls.end(), row.value_cells.is_null.begin(),
+                     row.value_cells.is_null.end());
+        w.write(cells, nulls);
+    }
+    w.finish();
+    return kExitOk;
+}
+
+}  // namespace tsfile_cli
diff --git a/cpp/tools/commands/cmd_write.cc b/cpp/tools/commands/cmd_write.cc
new file mode 100644
index 000000000..ecd703cbe
--- /dev/null
+++ b/cpp/tools/commands/cmd_write.cc
@@ -0,0 +1,417 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include <fcntl.h>
+
+#include <algorithm>
+#include <cerrno>
+#include <cstdint>
+#include <cstdio>
+#include <cstdlib>
+#include <ctime>
+#include <fstream>
+#include <iostream>
+#include <string>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#include "cli/cli_args.h"
+#include "cli/exit_codes.h"
+#include "commands/commands.h"
+#include "common/datatype/date_converter.h"
+#include "common/schema.h"
+#include "common/tablet.h"
+#include "file/write_file.h"
+#include "format/input_format.h"
+#include "writer/tsfile_table_writer.h"
+
+namespace tsfile_cli {
+namespace {
+
+struct DataRow {
+    long long line_no;
+    int64_t timestamp;
+    std::vector<std::string> cells;
+};
+
+// Parse a calendar date in strict YYYY-MM-DD form into a std::tm (year offset
+// from 1900, month 0-based) the way storage::Tablet expects for DATE columns.
+// Validates that it is a real date (DateConverter rejects e.g. 2024-13-40),
+// since the writer silently drops an invalid std::tm rather than erroring.
+bool parse_date_cell(const std::string& cell, std::tm& out) {
+    int y = 0;
+    int m = 0;
+    int d = 0;
+    char extra = 0;
+    if (std::sscanf(cell.c_str(), "%4d-%2d-%2d%c", &y, &m, &d, &extra) != 3) {
+        return false;
+    }
+    out = std::tm();
+    out.tm_year = y - 1900;
+    out.tm_mon = m - 1;
+    out.tm_mday = d;
+    int32_t date_int = 0;
+    return common::DateConverter::date_to_int(out, date_int) == common::E_OK;
+}
+
+bool add_typed_value(storage::Tablet& tablet, uint32_t row,
+                     uint32_t schema_index, const ColumnDef& def,
+                     const std::string& cell, std::string& error) {
+    if (cell.empty()) {
+        return true;  // null
+    }
+    char* e = nullptr;
+    switch (def.type) {
+        case common::BOOLEAN: {
+            bool v = false;
+            if (!parse_bool_cell(cell, v)) {
+                error = "bad BOOLEAN '" + cell + "'";
+                return false;
+            }
+            tablet.add_value(row, schema_index, v);
+            return true;
+        }
+        case common::INT32: {
+            errno = 0;
+            long long v = std::strtoll(cell.c_str(), &e, 10);
+            if (e == nullptr || *e != '\0') {
+                error = "bad INT32 '" + cell + "'";
+                return false;
+            }
+            if (errno == ERANGE || v < INT32_MIN || v > INT32_MAX) {
+                error = "INT32 out of range '" + cell + "'";
+                return false;
+            }
+            tablet.add_value(row, schema_index, static_cast<int32_t>(v));
+            return true;
+        }
+        case common::INT64: {
+            errno = 0;
+            long long v = std::strtoll(cell.c_str(), &e, 10);
+            if (e == nullptr || *e != '\0') {
+                error = "bad INT64 '" + cell + "'";
+                return false;
+            }
+            if (errno == ERANGE) {
+                error = "INT64 out of range '" + cell + "'";
+                return false;
+            }
+            tablet.add_value(row, schema_index, static_cast<int64_t>(v));
+            return true;
+        }
+        case common::TIMESTAMP: {
+            errno = 0;
+            long long v = std::strtoll(cell.c_str(), &e, 10);
+            if (e == nullptr || *e != '\0') {
+                error = "bad TIMESTAMP '" + cell + "'";
+                return false;
+            }
+            if (errno == ERANGE) {
+                error = "TIMESTAMP out of range '" + cell + "'";
+                return false;
+            }
+            tablet.add_value(row, schema_index, static_cast<int64_t>(v));
+            return true;
+        }
+        case common::DATE: {
+            std::tm d;
+            if (!parse_date_cell(cell, d)) {
+                error = "bad DATE '" + cell + "' (want YYYY-MM-DD)";
+                return false;
+            }
+            tablet.add_value(row, schema_index, d);
+            return true;
+        }
+        case common::FLOAT: {
+            errno = 0;
+            float v = std::strtof(cell.c_str(), &e);
+            if (e == nullptr || *e != '\0') {
+                error = "bad FLOAT '" + cell + "'";
+                return false;
+            }
+            if (errno == ERANGE) {
+                error = "FLOAT out of range '" + cell + "'";
+                return false;
+            }
+            tablet.add_value(row, schema_index, v);
+            return true;
+        }
+        case common::DOUBLE: {
+            errno = 0;
+            double v = std::strtod(cell.c_str(), &e);
+            if (e == nullptr || *e != '\0') {
+                error = "bad DOUBLE '" + cell + "'";
+                return false;
+            }
+            if (errno == ERANGE) {
+                error = "DOUBLE out of range '" + cell + "'";
+                return false;
+            }
+            tablet.add_value(row, schema_index, v);
+            return true;
+        }
+        case common::STRING:
+        case common::TEXT:
+        case common::BLOB: {
+            // Add by index using the c-string overload to avoid the per-cell
+            // name lowercasing + map lookup the by-name overload would do.
+            tablet.add_value(row, schema_index, cell.c_str());
+            return true;
+        }
+        default:
+            error = "unsupported column type";
+            return false;
+    }
+}
+
+}  // namespace
+
+int cmd_write(const ParsedArgs& args, std::ostream& /*out*/,
+              std::ostream& err) {
+    std::vector<ColumnDef> columns;
+    std::string perr;
+    if (!parse_columns_spec(args.columns, columns, perr)) {
+        err << "Error: " << perr << "\n";
+        return kExitUsage;
+    }
+
+    std::istream* in = &std::cin;
+    std::ifstream fin;
+    if (!args.file.empty() && args.file != "-") {
+        fin.open(args.file.c_str());
+        if (!fin.is_open()) {
+            err << "Error: cannot open input: " << args.file << "\n";
+            return kExitFile;
+        }
+        in = &fin;
+    }
+
+    const char delim = (args.format == ParsedArgs::Format::kTsv) ? '\t' : ',';
+    const bool csv_quotes = (delim == ',');
+
+    if (args.verbose) {
+        // Echo the resolved write configuration so the user can self-check the
+        // parsed flags before any rows are imported.
+        err << "write: table=" << args.table << " output=" << args.output
+            << " input=" << (args.file.empty() ? "-" : args.file)
+            << " format=" << (delim == '\t' ? "tsv" : "csv")
+            << " header=" << (args.no_header ? "none" : "yes")
+            << (args.header_match ? " (match)" : "") << "\n";
+        for (const ColumnDef& d : columns) {
+            err << "  column " << d.name << ":" << tsdatatype_name(d.type) << ":"
+                << (d.category == common::ColumnCategory::TAG ? "tag" : "field")
+                << "\n";
+        }
+    }
+
+    std::string line;
+    long long line_no = 0;
+    long long record_lines = 0;
+    if (!args.no_header) {
+        if (read_record(*in, csv_quotes, line, record_lines)) {
+            line_no += record_lines;
+            if (args.header_match) {
+                std::vector<std::string> h =
+                    split_line(line, delim, csv_quotes);
+                const size_t expected = columns.size() + 1;
+                if (h.size() != expected) {
+                    err << "Error: header has " << h.size()
+                        << " columns, expected " << expected
+                        << " (time + --columns) (line 1)\n";
+                    return kExitRuntime;
+                }
+                for (size_t i = 0; i < columns.size(); ++i) {
+                    if (h[i + 1] != columns[i].name) {
+                        err << "Error: header column " << (i + 2) << " is '"
+                            << h[i + 1] << "', expected '" << columns[i].name
+                            << "' (line 1)\n";
+                        return kExitRuntime;
+                    }
+                }
+            }
+        }
+    }
+
+    std::vector<std::string> names;
+    std::vector<common::TSDataType> types;
+    std::vector<common::ColumnCategory> cats;
+    std::vector<common::ColumnSchema> col_schemas;
+    std::vector<size_t> tag_idx;
+    for (size_t j = 0; j < columns.size(); ++j) {
+        const ColumnDef& d = columns[j];
+        names.push_back(d.name);
+        types.push_back(d.type);
+        cats.push_back(d.category);
+        col_schemas.push_back(common::ColumnSchema(
+            d.name, d.type, common::get_default_compressor(),
+            common::get_value_encoder(d.type), d.category));
+        if (d.category == common::ColumnCategory::TAG) {
+            tag_idx.push_back(j);
+        }
+    }
+
+    // Creating the output truncates it; refuse to clobber the input we are
+    // still reading from, which would otherwise silently destroy the source
+    // data.
+    if (!args.file.empty() && args.file != "-" && args.output == args.file) {
+        err << "Error: --output is the same as the input file: " << args.output
+            << "\n";
+        return kExitUsage;
+    }
+
+    storage::WriteFile file;
+    int flags = O_WRONLY | O_CREAT | O_TRUNC;
+#ifdef _WIN32
+    flags |= O_BINARY;
+#endif
+    if (file.create(args.output, flags, 0666) != 0) {
+        err << "Error: cannot create output: " << args.output << "\n";
+        return kExitFile;
+    }
+    auto* schema = new storage::TableSchema(args.table, col_schemas);
+    auto* writer = new storage::TsFileTableWriter(&file, schema);
+
+    // Stream rows into fixed-size batches so memory stays bounded regardless of
+    // input size; a full file is never buffered in memory.
+    const size_t kBatch = 1024;
+    int result_code = kExitOk;
+    long long total_rows = 0;
+    std::vector<DataRow> batch;
+    batch.reserve(kBatch);
+    // The table writer requires strictly increasing timestamps per device, and
+    // a device is identified by its tag-column values. Track the last timestamp
+    // seen for each device so out-of-order input is rejected with a clear,
+    // located message instead of an opaque write failure.
+    std::unordered_map<std::string, int64_t> last_ts_by_device;
+
+    auto flush_batch = [&]() -> bool {
+        if (batch.empty()) {
+            return true;
+        }
+        storage::Tablet tablet(args.table, names, types, cats,
+                               static_cast<int>(batch.size()));
+        for (size_t i = 0; i < batch.size(); ++i) {
+            uint32_t r = static_cast<uint32_t>(i);
+            tablet.add_timestamp(r, batch[i].timestamp);
+            for (size_t j = 0; j < columns.size(); ++j) {
+                std::string cell_err;
+                if (!add_typed_value(tablet, r, static_cast<uint32_t>(j),
+                                     columns[j], batch[i].cells[j], cell_err)) {
+                    err << "Error: " << cell_err << " (line "
+                        << batch[i].line_no << ")\n";
+                    return false;
+                }
+            }
+        }
+        int wt = writer->write_table(tablet);
+        if (wt != 0) {
+            err << "Error: failed to write rows: " << error_code_message(wt)
+                << " (code " << wt << ")\n";
+            return false;
+        }
+        total_rows += static_cast<long long>(batch.size());
+        batch.clear();
+        return true;
+    };
+
+    while (read_record(*in, csv_quotes, line, record_lines)) {
+        line_no += record_lines;
+        if (line.empty()) {
+            continue;
+        }
+        std::vector<std::string> fields = split_line(line, delim, csv_quotes);
+        if (fields.size() != columns.size() + 1) {
+            err << "Error: expected " << (columns.size() + 1) << " fields, got "
+                << fields.size() << " (line " << line_no << ")\n";
+            result_code = kExitRuntime;
+            break;
+        }
+        char* e = nullptr;
+        errno = 0;
+        long long ts = std::strtoll(fields[0].c_str(), &e, 10);
+        if (e == nullptr || *e != '\0' || errno == ERANGE) {
+            err << "Error: bad timestamp '" << fields[0] << "' (line "
+                << line_no << ")\n";
+            result_code = kExitRuntime;
+            break;
+        }
+        DataRow r;
+        r.line_no = line_no;
+        r.timestamp = static_cast<int64_t>(ts);
+        r.cells.assign(fields.begin() + 1, fields.end());
+
+        std::string device_key;
+        for (size_t k : tag_idx) {
+            device_key += r.cells[k];
+            device_key.push_back('\0');
+        }
+        auto seen = last_ts_by_device.find(device_key);
+        if (seen != last_ts_by_device.end() && r.timestamp <= seen->second) {
+            err << "Error: timestamps must be strictly increasing per device "
+                   "(line "
+                << line_no << ": " << r.timestamp << " <= previous "
+                << seen->second << ")\n";
+            result_code = kExitRuntime;
+            break;
+        }
+        last_ts_by_device[device_key] = r.timestamp;
+
+        batch.push_back(std::move(r));
+        if (batch.size() >= kBatch && !flush_batch()) {
+            result_code = kExitRuntime;
+            break;
+        }
+    }
+
+    if (result_code == kExitOk && !flush_batch()) {
+        result_code = kExitRuntime;
+    }
+
+    if (result_code == kExitOk) {
+        int fr = writer->flush();
+        if (fr != 0) {
+            err << "Error: failed to flush output: " << error_code_message(fr)
+                << " (code " << fr << ")\n";
+            result_code = kExitRuntime;
+        } else {
+            int cr = writer->close();
+            if (cr != 0) {
+                err << "Error: failed to close output: "
+                    << error_code_message(cr) << " (code " << cr << ")\n";
+                result_code = kExitRuntime;
+            }
+        }
+    } else {
+        writer->close();
+    }
+    delete writer;
+    delete schema;
+
+    if (result_code != kExitOk) {
+        // The import failed; do not leave a partial/corrupt .tsfile behind.
+        file.close();
+        std::remove(args.output.c_str());
+    } else if (args.verbose) {
+        err << "wrote " << total_rows << " rows to " << args.output << "\n";
+    }
+    return result_code;
+}
+
+}  // namespace tsfile_cli
diff --git a/cpp/tools/commands/commands.h b/cpp/tools/commands/commands.h
new file mode 100644
index 000000000..5e26fd64b
--- /dev/null
+++ b/cpp/tools/commands/commands.h
@@ -0,0 +1,70 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#ifndef TSFILE_CLI_COMMANDS_H
+#define TSFILE_CLI_COMMANDS_H
+
+#include <ostream>
+#include <string>
+#include <vector>
+
+#include "cli/cli_args.h"
+#include "format/output_format.h"
+
+namespace storage {
+class TsFileReader;
+}  // namespace storage
+
+namespace tsfile_cli {
+
+bool is_table_model(const ParsedArgs& args, storage::TsFileReader& reader);
+
+// Build the list of "device.measurement" paths to query for the tree model.
+// When args.device is set only that device is resolved (one targeted metadata
+// lookup); otherwise every device/series is collected from a single whole-file
+// get_timeseries_metadata() call rather than a per-device schema loop. Honors
+// args.measurements as a projection filter.
+std::vector<std::string> collect_tree_query_paths(
+    const ParsedArgs& args, storage::TsFileReader& reader);
+
+int run_row_query(const ParsedArgs& args, storage::TsFileReader& reader,
+                  OutputFormat fmt, std::ostream& out, std::ostream& err,
+                  long long offset, long long limit);
+
+int cmd_ls(const ParsedArgs& args, storage::TsFileReader& reader,
+           OutputFormat fmt, std::ostream& out, std::ostream& err);
+int cmd_schema(const ParsedArgs& args, storage::TsFileReader& reader,
+               OutputFormat fmt, std::ostream& out, std::ostream& err);
+int cmd_meta(const ParsedArgs& args, storage::TsFileReader& reader,
+             OutputFormat fmt, std::ostream& out, std::ostream& err);
+int cmd_count(const ParsedArgs& args, storage::TsFileReader& reader,
+              OutputFormat fmt, std::ostream& out, std::ostream& err);
+int cmd_stats(const ParsedArgs& args, storage::TsFileReader& reader,
+              OutputFormat fmt, std::ostream& out, std::ostream& err);
+int cmd_head(const ParsedArgs& args, storage::TsFileReader& reader,
+             OutputFormat fmt, std::ostream& out, std::ostream& err);
+int cmd_cat(const ParsedArgs& args, storage::TsFileReader& reader,
+            OutputFormat fmt, std::ostream& out, std::ostream& err);
+int cmd_sample(const ParsedArgs& args, storage::TsFileReader& reader,
+               OutputFormat fmt, std::ostream& out, std::ostream& err);
+int cmd_write(const ParsedArgs& args, std::ostream& out, std::ostream& err);
+
+}  // namespace tsfile_cli
+
+#endif  // TSFILE_CLI_COMMANDS_H
diff --git a/cpp/tools/commands/row_query.cc b/cpp/tools/commands/row_query.cc
new file mode 100644
index 000000000..702deefd6
--- /dev/null
+++ b/cpp/tools/commands/row_query.cc
@@ -0,0 +1,140 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include <algorithm>
+#include <limits>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "cli/exit_codes.h"
+#include "commands/commands.h"
+#include "common/device_id.h"
+#include "common/schema.h"
+#include "format/result_set_format.h"
+#include "reader/tsfile_reader.h"
+
+namespace tsfile_cli {
+
+std::vector<std::string> collect_tree_query_paths(
+    const ParsedArgs& args, storage::TsFileReader& reader) {
+    std::vector<std::string> paths;
+    const bool has_projection = !args.measurements.empty();
+    auto include_measurement = [&](const std::string& m) {
+        return !has_projection ||
+               std::find(args.measurements.begin(), args.measurements.end(),
+                         m) != args.measurements.end();
+    };
+
+    if (!args.device.empty()) {
+        // A single device was requested: resolve its series and keep only the
+        // ones matching the projection. Filtering against the device's real
+        // schema means a provided measurement that doesn't exist on the device
+        // is dropped rather than queried blindly (matching the no-device path).
+        auto did = std::make_shared<storage::StringArrayDeviceID>(args.device);
+        std::vector<storage::MeasurementSchema> sch;
+        if (reader.get_timeseries_schema(did, sch) == 0) {
+            for (auto& m : sch) {
+                if (include_measurement(m.measurement_name_)) {
+                    paths.push_back(args.device + "." + m.measurement_name_);
+                }
+            }
+        }
+        return paths;
+    }
+
+    // No device filter: collect every device/series from a single whole-file
+    // metadata call instead of querying each device one by one.
+    storage::DeviceTimeseriesMetadataMap meta =
+        reader.get_timeseries_metadata();
+    for (auto& kv : meta) {
+        if (!kv.first) {
+            continue;
+        }
+        const std::string dev = kv.first->get_device_name();
+        for (auto& ts : kv.second) {
+            if (!ts) {
+                continue;
+            }
+            const std::string m = ts->get_measurement_name().to_std_string();
+            if (include_measurement(m)) {
+                paths.push_back(dev + "." + m);
+            }
+        }
+    }
+    return paths;
+}
+
+int run_row_query(const ParsedArgs& args, storage::TsFileReader& reader,
+                  OutputFormat fmt, std::ostream& out, std::ostream& err,
+                  long long offset, long long limit) {
+    const int64_t start = args.has_start ? static_cast<int64_t>(args.start)
+                                         : std::numeric_limits<int64_t>::min();
+    const int64_t end = args.has_end ? static_cast<int64_t>(args.end)
+                                     : std::numeric_limits<int64_t>::max();
+
+    storage::ResultSet* rs = nullptr;
+    int qret = 0;
+
+    if (is_table_model(args, reader)) {
+        std::string table_name = args.table;
+        if (table_name.empty()) {
+            auto schemas = reader.get_all_table_schemas();
+            if (schemas.empty() || !schemas[0]) {
+                err << "Error: no table found in file\n";
+                return kExitRuntime;
+            }
+            table_name = schemas[0]->get_table_name();
+        }
+        std::vector<std::string> cols = args.measurements;
+        if (cols.empty()) {
+            auto ts = reader.get_table_schema(table_name);
+            if (ts) {
+                cols = ts->get_measurement_names();
+            }
+        }
+        qret = reader.query(table_name, cols, start, end, rs);
+    } else {
+        std::vector<std::string> paths = collect_tree_query_paths(args, reader);
+        if (paths.empty()) {
+            err << "Error: no time series found\n";
+            return kExitRuntime;
+        }
+        qret = reader.query(paths, start, end, rs);
+    }
+
+    if (qret != 0 || rs == nullptr) {
+        err << "Error: query failed: " << error_code_message(qret) << "\n";
+        if (rs != nullptr) {
+            reader.destroy_query_data_set(rs);
+        }
+        return kExitRuntime;
+    }
+
+    int wret = emit_result_set(rs, fmt, args.no_header, out, offset, limit);
+    reader.destroy_query_data_set(rs);
+    if (wret != 0) {
+        err << "Error: failed to read rows: " << error_code_message(wret)
+            << "\n";
+        return kExitRuntime;
+    }
+    return kExitOk;
+}
+
+}  // namespace tsfile_cli
diff --git a/cpp/tools/commands/statistics.cc b/cpp/tools/commands/statistics.cc
new file mode 100644
index 000000000..f1c21b994
--- /dev/null
+++ b/cpp/tools/commands/statistics.cc
@@ -0,0 +1,218 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "commands/statistics.h"
+
+#include <algorithm>
+#include <fstream>
+#include <limits>
+#include <sstream>
+
+#include "commands/commands.h"
+#include "common/statistic.h"
+#include "reader/tsfile_reader.h"
+
+namespace tsfile_cli {
+namespace {
+
+template <typename T>
+std::string value_to_string(const T& value) {
+    std::ostringstream ss;
+    ss << value;
+    return ss.str();
+}
+
+std::string bool_to_string(bool value) { return value ? "true" : "false"; }
+
+std::string string_to_std(const common::String& value) {
+    return value.to_std_string();
+}
+
+long long file_size(const std::string& path) {
+    std::ifstream in(path.c_str(), std::ios::binary | std::ios::ate);
+    if (!in.good()) {
+        return 0;
+    }
+    return static_cast<long long>(in.tellg());
+}
+
+}  // namespace
+
+StatisticCells statistic_value_cells(storage::Statistic* st) {
+    StatisticCells cells;
+    cells.values.assign(5, "");
+    cells.is_null.assign(5, true);
+    if (st == nullptr || st->get_count() == 0) {
+        return cells;
+    }
+
+    switch (st->get_type()) {
+        case common::BOOLEAN: {
+            auto* s = static_cast<storage::BooleanStatistic*>(st);
+            cells.values = {"", "", bool_to_string(s->first_value_),
+                            bool_to_string(s->last_value_),
+                            value_to_string(s->sum_value_)};
+            cells.is_null = {true, true, false, false, false};
+            break;
+        }
+        case common::INT32:
+        case common::DATE: {
+            auto* s = static_cast<storage::Int32Statistic*>(st);
+            cells.values = {value_to_string(s->min_value_),
+                            value_to_string(s->max_value_),
+                            value_to_string(s->first_value_),
+                            value_to_string(s->last_value_),
+                            value_to_string(s->sum_value_)};
+            cells.is_null = {false, false, false, false, false};
+            break;
+        }
+        case common::INT64:
+        case common::TIMESTAMP: {
+            auto* s = static_cast<storage::Int64Statistic*>(st);
+            cells.values = {value_to_string(s->min_value_),
+                            value_to_string(s->max_value_),
+                            value_to_string(s->first_value_),
+                            value_to_string(s->last_value_),
+                            value_to_string(s->sum_value_)};
+            cells.is_null = {false, false, false, false, false};
+            break;
+        }
+        case common::FLOAT: {
+            auto* s = static_cast<storage::FloatStatistic*>(st);
+            cells.values = {value_to_string(s->min_value_),
+                            value_to_string(s->max_value_),
+                            value_to_string(s->first_value_),
+                            value_to_string(s->last_value_),
+                            value_to_string(s->sum_value_)};
+            cells.is_null = {false, false, false, false, false};
+            break;
+        }
+        case common::DOUBLE: {
+            auto* s = static_cast<storage::DoubleStatistic*>(st);
+            cells.values = {value_to_string(s->min_value_),
+                            value_to_string(s->max_value_),
+                            value_to_string(s->first_value_),
+                            value_to_string(s->last_value_),
+                            value_to_string(s->sum_value_)};
+            cells.is_null = {false, false, false, false, false};
+            break;
+        }
+        case common::STRING: {
+            auto* s = static_cast<storage::StringStatistic*>(st);
+            cells.values = {string_to_std(s->min_value_),
+                            string_to_std(s->max_value_),
+                            string_to_std(s->first_value_),
+                            string_to_std(s->last_value_), ""};
+            cells.is_null = {false, false, false, false, true};
+            break;
+        }
+        case common::TEXT: {
+            auto* s = static_cast<storage::TextStatistic*>(st);
+            cells.values = {"", "", string_to_std(s->first_value_),
+                            string_to_std(s->last_value_), ""};
+            cells.is_null = {true, true, false, false, true};
+            break;
+        }
+        default:
+            break;
+    }
+    return cells;
+}
+
+std::vector<SeriesStatRow> collect_series_stats(const ParsedArgs& args,
+                                                storage::TsFileReader& reader) {
+    std::vector<SeriesStatRow> rows;
+    storage::DeviceTimeseriesMetadataMap meta =
+        reader.get_timeseries_metadata();
+    for (auto& kv : meta) {
+        std::string target = kv.first ? kv.first->get_device_name() : "";
+        if (!args.device.empty() && target != args.device) {
+            continue;
+        }
+        if (!args.table.empty() && kv.first &&
+            kv.first->get_table_name() != args.table) {
+            continue;
+        }
+        for (auto& ts : kv.second) {
+            if (!ts) {
+                continue;
+            }
+            std::string measurement =
+                ts->get_measurement_name().to_std_string();
+            if (!args.measurements.empty() &&
+                std::find(args.measurements.begin(), args.measurements.end(),
+                          measurement) == args.measurements.end()) {
+                continue;
+            }
+            storage::Statistic* st = ts->get_statistic();
+            SeriesStatRow row;
+            row.target = target;
+            row.measurement = measurement;
+            if (st != nullptr) {
+                row.count = st->get_count();
+                row.start_time = st->start_time_;
+                row.end_time = st->end_time_;
+                row.value_cells = statistic_value_cells(st);
+            } else {
+                row.value_cells.values.assign(5, "");
+                row.value_cells.is_null.assign(5, true);
+            }
+            rows.push_back(row);
+        }
+    }
+    return rows;
+}
+
+FileSummary collect_file_summary(const ParsedArgs& args,
+                                 storage::TsFileReader& reader) {
+    FileSummary s;
+    s.file = args.file;
+    s.model = is_table_model(args, reader) ? "table" : "tree";
+    s.device_count = static_cast<long long>(reader.get_all_device_ids().size());
+    s.table_count =
+        static_cast<long long>(reader.get_all_table_schemas().size());
+    s.file_size_bytes = file_size(args.file);
+
+    // The file summary (series_count + overall time range) describes the whole
+    // file, so clear any -d/-t/-m filters from the args copy before collecting
+    // per-series stats; otherwise meta would only count the filtered subset.
+    ParsedArgs all = args;
+    all.device.clear();
+    all.table.clear();
+    all.measurements.clear();
+    std::vector<SeriesStatRow> rows = collect_series_stats(all, reader);
+    s.series_count = static_cast<long long>(rows.size());
+    long long min_start = std::numeric_limits<long long>::max();
+    long long max_end = std::numeric_limits<long long>::min();
+    for (const SeriesStatRow& row : rows) {
+        if (row.count <= 0) {
+            continue;
+        }
+        min_start = std::min(min_start, row.start_time);
+        max_end = std::max(max_end, row.end_time);
+        s.has_time_range = true;
+    }
+    if (s.has_time_range) {
+        s.start_time = min_start;
+        s.end_time = max_end;
+    }
+    return s;
+}
+
+}  // namespace tsfile_cli
diff --git a/cpp/tools/commands/statistics.h b/cpp/tools/commands/statistics.h
new file mode 100644
index 000000000..031b5b4aa
--- /dev/null
+++ b/cpp/tools/commands/statistics.h
@@ -0,0 +1,69 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#ifndef TSFILE_CLI_STATISTICS_H
+#define TSFILE_CLI_STATISTICS_H
+
+#include <string>
+#include <vector>
+
+#include "cli/cli_args.h"
+
+namespace storage {
+class Statistic;
+class TsFileReader;
+}  // namespace storage
+
+namespace tsfile_cli {
+
+struct StatisticCells {
+    std::vector<std::string> values;
+    std::vector<bool> is_null;
+};
+
+struct SeriesStatRow {
+    std::string target;
+    std::string measurement;
+    long long count = 0;
+    long long start_time = 0;
+    long long end_time = 0;
+    StatisticCells value_cells;
+};
+
+struct FileSummary {
+    std::string file;
+    std::string model;
+    long long device_count = 0;
+    long long table_count = 0;
+    long long series_count = 0;
+    long long start_time = 0;
+    long long end_time = 0;
+    bool has_time_range = false;
+    long long file_size_bytes = 0;
+};
+
+StatisticCells statistic_value_cells(storage::Statistic* st);
+std::vector<SeriesStatRow> collect_series_stats(const ParsedArgs& args,
+                                                storage::TsFileReader& reader);
+FileSummary collect_file_summary(const ParsedArgs& args,
+                                 storage::TsFileReader& reader);
+
+}  // namespace tsfile_cli
+
+#endif  // TSFILE_CLI_STATISTICS_H
diff --git a/cpp/tools/format/input_format.cc b/cpp/tools/format/input_format.cc
new file mode 100644
index 000000000..eb2c99a92
--- /dev/null
+++ b/cpp/tools/format/input_format.cc
@@ -0,0 +1,148 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "format/input_format.h"
+
+#include <cctype>
+#include <istream>
+
+#include "common/csv_utils.h"
+
+namespace tsfile_cli {
+
+namespace {
+
+void strip_cr(std::string& s) {
+    if (!s.empty() && s.back() == '\r') {
+        s.pop_back();
+    }
+}
+
+}  // namespace
+
+bool read_record(std::istream& in, bool csv_quotes, std::string& record,
+                 long long& lines_consumed) {
+    record.clear();
+    lines_consumed = 0;
+    std::string physical;
+    bool open_quote = false;
+    while (std::getline(in, physical)) {
+        strip_cr(physical);
+        ++lines_consumed;
+        if (!record.empty()) {
+            record.push_back('\n');  // restore the newline inside the field
+        }
+        record += physical;
+        if (csv_quotes) {
+            for (char c : physical) {
+                if (c == '"') {
+                    open_quote = !open_quote;
+                }
+            }
+            if (open_quote) {
+                continue;  // quote still open: the field spans the next line
+            }
+        }
+        return true;
+    }
+    return lines_consumed > 0;  // trailing record with an unterminated quote
+}
+
+bool parse_datatype_name(const std::string& s, common::TSDataType& out) {
+    return common::parse_data_type_name(s, out);
+}
+
+bool parse_category(const std::string& s, common::ColumnCategory& out) {
+    std::string l;
+    l.reserve(s.size());
+    for (char c : s) {
+        l += static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+    }
+    if (l == "tag") {
+        out = common::ColumnCategory::TAG;
+    } else if (l == "field") {
+        out = common::ColumnCategory::FIELD;
+    } else {
+        return false;
+    }
+    return true;
+}
+
+std::vector<std::string> split_line(const std::string& line, char delim,
+                                    bool csv_quotes) {
+    return common::split_csv_line(line, delim, csv_quotes);
+}
+
+bool parse_columns_spec(const std::string& spec, std::vector<ColumnDef>& out,
+                        std::string& error) {
+    out.clear();
+    if (spec.empty()) {
+        error = "empty --columns";
+        return false;
+    }
+    std::vector<std::string> items = split_line(spec, ',', false);
+    for (const std::string& item : items) {
+        std::vector<std::string> parts = split_line(item, ':', false);
+        if (parts.size() != 3) {
+            error = "bad column '" + item + "' (want name:TYPE:category)";
+            return false;
+        }
+        ColumnDef def;
+        def.name = parts[0];
+        if (def.name.empty()) {
+            error = "empty column name in '" + item + "'";
+            return false;
+        }
+        if (!parse_datatype_name(parts[1], def.type)) {
+            error = "unknown type '" + parts[1] + "'";
+            return false;
+        }
+        if (!parse_category(parts[2], def.category)) {
+            error = "bad category '" + parts[2] + "' (want tag|field)";
+            return false;
+        }
+        for (const ColumnDef& prev : out) {
+            if (prev.name == def.name) {
+                error = "duplicate column name '" + def.name + "'";
+                return false;
+            }
+        }
+        out.push_back(def);
+    }
+    return true;
+}
+
+bool parse_bool_cell(const std::string& s, bool& out) {
+    std::string l;
+    l.reserve(s.size());
+    for (char c : s) {
+        l += static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+    }
+    if (l == "true" || l == "1") {
+        out = true;
+        return true;
+    }
+    if (l == "false" || l == "0") {
+        out = false;
+        return true;
+    }
+    return false;
+}
+
+}  // namespace tsfile_cli
diff --git a/cpp/tools/format/input_format.h b/cpp/tools/format/input_format.h
new file mode 100644
index 000000000..3b46af769
--- /dev/null
+++ b/cpp/tools/format/input_format.h
@@ -0,0 +1,56 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#ifndef TSFILE_CLI_INPUT_FORMAT_H
+#define TSFILE_CLI_INPUT_FORMAT_H
+
+#include <istream>
+#include <string>
+#include <vector>
+
+#include "common/db_common.h"
+#include "utils/db_utils.h"
+
+namespace tsfile_cli {
+
+struct ColumnDef {
+    std::string name;
+    common::TSDataType type;
+    common::ColumnCategory category;
+};
+
+bool parse_datatype_name(const std::string& s, common::TSDataType& out);
+bool parse_category(const std::string& s, common::ColumnCategory& out);
+bool parse_columns_spec(const std::string& spec, std::vector<ColumnDef>& out,
+                        std::string& error);
+std::vector<std::string> split_line(const std::string& line, char delim,
+                                    bool csv_quotes);
+bool parse_bool_cell(const std::string& s, bool& out);
+
+// Read one logical record from `in`. When `csv_quotes` is true a field may span
+// multiple physical lines if it opens a double-quote that is not yet closed, so
+// continuation lines are appended (newline preserved) until the quote closes.
+// `lines_consumed` returns how many physical lines were read, so callers can
+// keep accurate line numbers. Returns false at end of input with no record.
+bool read_record(std::istream& in, bool csv_quotes, std::string& record,
+                 long long& lines_consumed);
+
+}  // namespace tsfile_cli
+
+#endif  // TSFILE_CLI_INPUT_FORMAT_H
diff --git a/cpp/tools/format/output_format.cc b/cpp/tools/format/output_format.cc
new file mode 100644
index 000000000..67d0566bf
--- /dev/null
+++ b/cpp/tools/format/output_format.cc
@@ -0,0 +1,359 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "format/output_format.h"
+
+#include <algorithm>
+#include <cstdio>
+#include <utility>
+
+#include "common/csv_utils.h"
+#include "utils/errno_define.h"
+
+namespace tsfile_cli {
+
+const char* error_code_message(int code) {
+    switch (code) {
+        case common::E_OOM:
+            return "out of memory";
+        case common::E_NOT_EXIST:
+            return "not found";
+        case common::E_INVALID_ARG:
+            return "invalid argument";
+        case common::E_OUT_OF_RANGE:
+            return "value out of range";
+        case common::E_OUT_OF_ORDER:
+            return "data is out of order";
+        case common::E_FILE_OPEN_ERR:
+            return "cannot open file";
+        case common::E_FILE_WRITE_ERR:
+            return "file write error";
+        case common::E_FILE_READ_ERR:
+            return "file read error";
+        case common::E_TSFILE_CORRUPTED:
+            return "file is corrupted";
+        case common::E_INVALID_PATH:
+            return "invalid path";
+        case common::E_DEVICE_NOT_EXIST:
+            return "device does not exist";
+        case common::E_MEASUREMENT_NOT_EXIST:
+            return "measurement does not exist";
+        case common::E_TABLE_NOT_EXIST:
+            return "table does not exist";
+        case common::E_COLUMN_NOT_EXIST:
+            return "column does not exist";
+        case common::E_INVALID_QUERY:
+            return "invalid query";
+        case common::E_TYPE_NOT_SUPPORTED:
+            return "data type not supported";
+        case common::E_TYPE_NOT_MATCH:
+            return "data type mismatch";
+        case common::E_ENCODE_ERR:
+            return "failed to encode data";
+        case common::E_DECODE_ERR:
+            return "failed to decode data";
+        default:
+            return "internal error";
+    }
+}
+
+OutputFormat resolve_format(ParsedArgs::Format f, bool stdout_is_tty) {
+    switch (f) {
+        case ParsedArgs::Format::kCsv:
+            return OutputFormat::kCsv;
+        case ParsedArgs::Format::kTsv:
+            return OutputFormat::kTsv;
+        case ParsedArgs::Format::kJson:
+            return OutputFormat::kJson;
+        case ParsedArgs::Format::kTable:
+            return OutputFormat::kTable;
+        case ParsedArgs::Format::kAuto:
+        default:
+            return stdout_is_tty ? OutputFormat::kTable : OutputFormat::kTsv;
+    }
+}
+
+const char* tsdatatype_name(common::TSDataType t) {
+    switch (t) {
+        case common::BOOLEAN:
+            return "BOOLEAN";
+        case common::INT32:
+            return "INT32";
+        case common::INT64:
+            return "INT64";
+        case common::FLOAT:
+            return "FLOAT";
+        case common::DOUBLE:
+            return "DOUBLE";
+        case common::TEXT:
+            return "TEXT";
+        case common::VECTOR:
+            return "VECTOR";
+        case common::UNKNOWN:
+            return "UNKNOWN";
+        case common::TIMESTAMP:
+            return "TIMESTAMP";
+        case common::DATE:
+            return "DATE";
+        case common::BLOB:
+            return "BLOB";
+        case common::STRING:
+            return "STRING";
+        case common::NULL_TYPE:
+            return "NULL";
+        case common::INVALID_DATATYPE:
+        default:
+            return "INVALID";
+    }
+}
+
+const char* tsencoding_name(common::TSEncoding e) {
+    switch (e) {
+        case common::PLAIN:
+            return "PLAIN";
+        case common::DICTIONARY:
+            return "DICTIONARY";
+        case common::RLE:
+            return "RLE";
+        case common::DIFF:
+            return "DIFF";
+        case common::TS_2DIFF:
+            return "TS_2DIFF";
+        case common::BITMAP:
+            return "BITMAP";
+        case common::GORILLA_V1:
+            return "GORILLA_V1";
+        case common::REGULAR:
+            return "REGULAR";
+        case common::GORILLA:
+            return "GORILLA";
+        case common::ZIGZAG:
+            return "ZIGZAG";
+        case common::FREQ:
+            return "FREQ";
+        case common::SPRINTZ:
+            return "SPRINTZ";
+        case common::INVALID_ENCODING:
+        default:
+            return "UNKNOWN";
+    }
+}
+
+const char* compression_name(common::CompressionType c) {
+    switch (c) {
+        case common::UNCOMPRESSED:
+            return "UNCOMPRESSED";
+        case common::SNAPPY:
+            return "SNAPPY";
+        case common::GZIP:
+            return "GZIP";
+        case common::LZO:
+            return "LZO";
+        case common::SDT:
+            return "SDT";
+        case common::PAA:
+            return "PAA";
+        case common::PLA:
+            return "PLA";
+        case common::LZ4:
+            return "LZ4";
+        case common::INVALID_COMPRESSION:
+        default:
+            return "UNKNOWN";
+    }
+}
+
+std::string csv_escape(const std::string& field) {
+    return common::csv_escape(field, ',');
+}
+
+std::string json_escape(const std::string& s) {
+    std::string out;
+    out.reserve(s.size() + 2);
+    for (unsigned char c : s) {
+        switch (c) {
+            case '"':
+                out += "\\\"";
+                break;
+            case '\\':
+                out += "\\\\";
+                break;
+            case '\b':
+                out += "\\b";
+                break;
+            case '\f':
+                out += "\\f";
+                break;
+            case '\n':
+                out += "\\n";
+                break;
+            case '\r':
+                out += "\\r";
+                break;
+            case '\t':
+                out += "\\t";
+                break;
+            default:
+                if (c < 0x20) {
+                    char buf[8];
+                    std::snprintf(buf, sizeof(buf), "\\u%04x", c);
+                    out += buf;
+                } else {
+                    out += static_cast<char>(c);
+                }
+        }
+    }
+    return out;
+}
+
+RowWriter::RowWriter(std::ostream& out, OutputFormat fmt,
+                     std::vector<std::string> header,
+                     std::vector<common::TSDataType> types, bool no_header)
+    : out_(out),
+      fmt_(fmt),
+      header_(std::move(header)),
+      types_(std::move(types)),
+      no_header_(no_header) {}
+
+bool RowWriter::emits_json_bare(size_t col) const {
+    if (col >= types_.size()) {
+        return false;
+    }
+    // These types serialize to a bare (unquoted) JSON token: numbers as numeric
+    // literals, BOOLEAN as the literal true/false, TIMESTAMP as a number.
+    // Everything else (strings, blobs, dates) is quoted.
+    switch (types_[col]) {
+        case common::BOOLEAN:
+        case common::INT32:
+        case common::INT64:
+        case common::FLOAT:
+        case common::DOUBLE:
+        case common::TIMESTAMP:
+            return true;
+        default:
+            return false;
+    }
+}
+
+void RowWriter::ensure_header() {
+    if (header_done_) {
+        return;
+    }
+    header_done_ = true;
+    if (no_header_) {
+        return;
+    }
+    const char sep = (fmt_ == OutputFormat::kCsv) ? ',' : '\t';
+    for (size_t i = 0; i < header_.size(); ++i) {
+        if (i) {
+            out_ << sep;
+        }
+        out_ << (fmt_ == OutputFormat::kCsv ? csv_escape(header_[i])
+                                            : header_[i]);
+    }
+    out_ << "\n";
+}
+
+void RowWriter::write(const std::vector<std::string>& cells,
+                      const std::vector<bool>& is_null) {
+    if (fmt_ == OutputFormat::kTable) {
+        rows_.push_back(cells);
+        rows_null_.push_back(is_null);
+        return;
+    }
+    if (fmt_ == OutputFormat::kJson) {
+        out_ << "{";
+        for (size_t i = 0; i < header_.size(); ++i) {
+            if (i) {
+                out_ << ",";
+            }
+            out_ << "\"" << json_escape(header_[i]) << "\":";
+            if (i < is_null.size() && is_null[i]) {
+                out_ << "null";
+            } else if (emits_json_bare(i)) {
+                out_ << (i < cells.size() ? cells[i] : "null");
+            } else {
+                out_ << "\"" << json_escape(i < cells.size() ? cells[i] : "")
+                     << "\"";
+            }
+        }
+        out_ << "}\n";
+        return;
+    }
+
+    ensure_header();
+    const char sep = (fmt_ == OutputFormat::kCsv) ? ',' : '\t';
+    for (size_t i = 0; i < cells.size(); ++i) {
+        if (i) {
+            out_ << sep;
+        }
+        bool null_cell = i < is_null.size() && is_null[i];
+        if (null_cell) {
+            continue;
+        }
+        out_ << (fmt_ == OutputFormat::kCsv ? csv_escape(cells[i]) : cells[i]);
+    }
+    out_ << "\n";
+}
+
+void RowWriter::finish() {
+    if (fmt_ != OutputFormat::kTable) {
+        if (fmt_ == OutputFormat::kCsv || fmt_ == OutputFormat::kTsv) {
+            ensure_header();
+        }
+        return;
+    }
+
+    const size_t ncols = header_.size();
+    std::vector<size_t> width(ncols, 0);
+    if (!no_header_) {
+        for (size_t i = 0; i < ncols; ++i) {
+            width[i] = header_[i].size();
+        }
+    }
+    for (const auto& row : rows_) {
+        for (size_t i = 0; i < ncols && i < row.size(); ++i) {
+            width[i] = std::max(width[i], row[i].size());
+        }
+    }
+
+    auto emit = [&](const std::vector<std::string>& cells,
+                    const std::vector<bool>& nulls) {
+        for (size_t i = 0; i < ncols; ++i) {
+            std::string cell =
+                (i < cells.size() && !(i < nulls.size() && nulls[i])) ? cells[i]
+                                                                      : "";
+            out_ << cell;
+            if (i + 1 < ncols) {
+                out_ << std::string(width[i] - cell.size() + 2, ' ');
+            }
+        }
+        out_ << "\n";
+    };
+
+    if (!no_header_) {
+        std::vector<bool> no_nulls(ncols, false);
+        emit(header_, no_nulls);
+    }
+    for (size_t r = 0; r < rows_.size(); ++r) {
+        emit(rows_[r], rows_null_[r]);
+    }
+}
+
+}  // namespace tsfile_cli
diff --git a/cpp/tools/format/output_format.h b/cpp/tools/format/output_format.h
new file mode 100644
index 000000000..c7efdd190
--- /dev/null
+++ b/cpp/tools/format/output_format.h
@@ -0,0 +1,73 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#ifndef TSFILE_CLI_OUTPUT_FORMAT_H
+#define TSFILE_CLI_OUTPUT_FORMAT_H
+
+#include <ostream>
+#include <string>
+#include <vector>
+
+#include "cli/cli_args.h"
+#include "common/db_common.h"
+
+namespace tsfile_cli {
+
+enum class OutputFormat { kCsv, kTsv, kJson, kTable };
+
+OutputFormat resolve_format(ParsedArgs::Format f, bool stdout_is_tty);
+
+// Translate a storage-engine error code (common::E_*) into a human-readable
+// phrase so CLI diagnostics carry meaning instead of a bare numeric code.
+const char* error_code_message(int code);
+
+const char* tsdatatype_name(common::TSDataType t);
+const char* tsencoding_name(common::TSEncoding e);
+const char* compression_name(common::CompressionType c);
+
+std::string csv_escape(const std::string& field);
+std::string json_escape(const std::string& s);
+
+class RowWriter {
+   public:
+    RowWriter(std::ostream& out, OutputFormat fmt,
+              std::vector<std::string> header,
+              std::vector<common::TSDataType> types, bool no_header);
+
+    void write(const std::vector<std::string>& cells,
+               const std::vector<bool>& is_null);
+    void finish();
+
+   private:
+    void ensure_header();
+    bool emits_json_bare(size_t col) const;
+
+    std::ostream& out_;
+    OutputFormat fmt_;
+    std::vector<std::string> header_;
+    std::vector<common::TSDataType> types_;
+    bool no_header_;
+    bool header_done_ = false;
+    std::vector<std::vector<std::string>> rows_;
+    std::vector<std::vector<bool>> rows_null_;
+};
+
+}  // namespace tsfile_cli
+
+#endif  // TSFILE_CLI_OUTPUT_FORMAT_H
diff --git a/cpp/tools/format/result_set_format.cc b/cpp/tools/format/result_set_format.cc
new file mode 100644
index 000000000..08cc3e1fc
--- /dev/null
+++ b/cpp/tools/format/result_set_format.cc
@@ -0,0 +1,183 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "format/result_set_format.h"
+
+#include <cstdio>
+#include <ctime>
+#include <iomanip>
+#include <limits>
+#include <random>
+#include <sstream>
+#include <utility>
+#include <vector>
+
+#include "utils/errno_define.h"
+
+namespace tsfile_cli {
+
+std::string cell_to_string(storage::ResultSet* rs, uint32_t i,
+                           common::TSDataType type) {
+    std::ostringstream ss;
+    switch (type) {
+        case common::BOOLEAN:
+            return rs->get_value<bool>(i) ? "true" : "false";
+        case common::INT32:
+            ss << rs->get_value<int32_t>(i);
+            return ss.str();
+        case common::INT64:
+        case common::TIMESTAMP:
+            ss << rs->get_value<int64_t>(i);
+            return ss.str();
+        case common::FLOAT:
+            ss << std::setprecision(std::numeric_limits<float>::max_digits10)
+               << rs->get_value<float>(i);
+            return ss.str();
+        case common::DOUBLE:
+            ss << std::setprecision(std::numeric_limits<double>::max_digits10)
+               << rs->get_value<double>(i);
+            return ss.str();
+        case common::DATE: {
+            std::tm d = rs->get_value<std::tm>(i);
+            char buf[16];
+            std::snprintf(buf, sizeof(buf), "%04d-%02d-%02d", d.tm_year + 1900,
+                          d.tm_mon + 1, d.tm_mday);
+            return buf;
+        }
+        case common::TEXT:
+        case common::STRING:
+        case common::BLOB: {
+            common::String* s = rs->get_value<common::String*>(i);
+            return s == nullptr ? std::string() : s->to_std_string();
+        }
+        default:
+            return "<UNKNOWN>";
+    }
+}
+
+int emit_result_set(storage::ResultSet* rs, OutputFormat fmt, bool no_header,
+                    std::ostream& out, long long offset, long long limit) {
+    auto meta = rs->get_metadata();
+    const uint32_t ncol = meta->get_column_count();
+    std::vector<std::string> header;
+    std::vector<common::TSDataType> types;
+    header.reserve(ncol);
+    types.reserve(ncol);
+    for (uint32_t i = 1; i <= ncol; ++i) {
+        header.push_back(meta->get_column_name(i));
+        types.push_back(meta->get_column_type(i));
+    }
+
+    RowWriter writer(out, fmt, header, types, no_header);
+    bool has_next = false;
+    int code = common::E_OK;
+    long long skipped = 0;
+    long long emitted = 0;
+    while ((code = rs->next(has_next)) == common::E_OK && has_next) {
+        if (skipped < offset) {
+            ++skipped;
+            continue;
+        }
+        if (limit >= 0 && emitted >= limit) {
+            break;
+        }
+        std::vector<std::string> cells(ncol);
+        std::vector<bool> nulls(ncol, false);
+        for (uint32_t i = 1; i <= ncol; ++i) {
+            if (rs->is_null(i)) {
+                nulls[i - 1] = true;
+            } else {
+                cells[i - 1] = cell_to_string(rs, i, types[i - 1]);
+            }
+        }
+        writer.write(cells, nulls);
+        ++emitted;
+    }
+    writer.finish();
+    return code;
+}
+
+namespace {
+
+struct BufferedRow {
+    std::vector<std::string> cells;
+    std::vector<bool> nulls;
+};
+
+BufferedRow read_current_row(storage::ResultSet* rs,
+                             const std::vector<common::TSDataType>& types) {
+    BufferedRow row;
+    const uint32_t ncol = static_cast<uint32_t>(types.size());
+    row.cells.assign(ncol, "");
+    row.nulls.assign(ncol, false);
+    for (uint32_t i = 1; i <= ncol; ++i) {
+        if (rs->is_null(i)) {
+            row.nulls[i - 1] = true;
+        } else {
+            row.cells[i - 1] = cell_to_string(rs, i, types[i - 1]);
+        }
+    }
+    return row;
+}
+
+}  // namespace
+
+int emit_result_set_sampled(storage::ResultSet* rs, OutputFormat fmt,
+                            bool no_header, std::ostream& out, long long limit,
+                            unsigned long long seed) {
+    auto meta = rs->get_metadata();
+    const uint32_t ncol = meta->get_column_count();
+    std::vector<std::string> header;
+    std::vector<common::TSDataType> types;
+    header.reserve(ncol);
+    types.reserve(ncol);
+    for (uint32_t i = 1; i <= ncol; ++i) {
+        header.push_back(meta->get_column_name(i));
+        types.push_back(meta->get_column_type(i));
+    }
+
+    std::vector<BufferedRow> reservoir;
+    reservoir.reserve(static_cast<size_t>(limit));
+    std::mt19937_64 rng(seed);
+    bool has_next = false;
+    int code = common::E_OK;
+    long long seen = 0;
+    while ((code = rs->next(has_next)) == common::E_OK && has_next) {
+        BufferedRow row = read_current_row(rs, types);
+        if (static_cast<long long>(reservoir.size()) < limit) {
+            reservoir.push_back(std::move(row));
+        } else {
+            std::uniform_int_distribution<long long> dist(0, seen);
+            long long idx = dist(rng);
+            if (idx < limit) {
+                reservoir[static_cast<size_t>(idx)] = std::move(row);
+            }
+        }
+        ++seen;
+    }
+
+    RowWriter writer(out, fmt, header, types, no_header);
+    for (const BufferedRow& row : reservoir) {
+        writer.write(row.cells, row.nulls);
+    }
+    writer.finish();
+    return code;
+}
+
+}  // namespace tsfile_cli
diff --git a/cpp/tools/format/result_set_format.h b/cpp/tools/format/result_set_format.h
new file mode 100644
index 000000000..a9fb2a4b1
--- /dev/null
+++ b/cpp/tools/format/result_set_format.h
@@ -0,0 +1,45 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#ifndef TSFILE_CLI_RESULT_SET_FORMAT_H
+#define TSFILE_CLI_RESULT_SET_FORMAT_H
+
+#include <ostream>
+#include <string>
+
+#include "common/db_common.h"
+#include "format/output_format.h"
+#include "reader/result_set.h"
+
+namespace tsfile_cli {
+
+std::string cell_to_string(storage::ResultSet* rs, uint32_t col_index,
+                           common::TSDataType type);
+
+int emit_result_set(storage::ResultSet* rs, OutputFormat fmt, bool no_header,
+                    std::ostream& out, long long offset = 0,
+                    long long limit = -1);
+
+int emit_result_set_sampled(storage::ResultSet* rs, OutputFormat fmt,
+                            bool no_header, std::ostream& out, long long limit,
+                            unsigned long long seed);
+
+}  // namespace tsfile_cli
+
+#endif  // TSFILE_CLI_RESULT_SET_FORMAT_H
diff --git a/cpp/tools/skills/tsfile-cli/SKILL.md b/cpp/tools/skills/tsfile-cli/SKILL.md
new file mode 100644
index 000000000..da6d8379a
--- /dev/null
+++ b/cpp/tools/skills/tsfile-cli/SKILL.md
@@ -0,0 +1,112 @@
+<!--
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+-->
+
+---
+name: tsfile-cli
+description: Use when you need to inspect, preview, export, OR import an Apache TsFile (.tsfile) from the command line — list devices/tables, dump schema, read file/series metadata, count rows, sample/preview rows, or write CSV/TSV into a new .tsfile — via the project's C++ `tsfile-cli` in cpp/tools.
+---
+
+# tsfile-cli
+
+Single pipe-friendly C++ binary to inspect **and** import `.tsfile` (TsFile's analogue of
+`parquet-cli`/`pqrs`). Source `cpp/tools/`. Read data → stdout, diagnostics → stderr;
+`write` imports CSV/TSV → a new file.
+
+## Binary
+
+- Name `tsfile-cli` (CMake target `tsfile_cli`). Find: `ls cpp/build/*/bin/tsfile-cli`.
+- Build only if missing: `cd cpp && bash build.sh -t=Debug`.
+- CMake ≥4 aborts on bundled ANTLR4 (`Policy CMP00xx ... OLD`) → add `--disable-antlr4`
+  (reader/CLI don't use ANTLR4).
+
+## Read
+
+`tsfile-cli <cmd> [opts] <file.tsfile>` · `tsfile-cli --help | --version | help`
+
+| cmd | output | scans pages |
+|---|---|---|
+| `ls` | device (tree) / table (table) per line | no |
+| `schema` | `target,measurement,datatype,encoding,compression` | no |
+| `meta` | model, device/table/series counts, time range, size | no |
+| `stats` | per-series `count,start,end,min,max,first,last,sum` | no |
+| `count` | per-series counts + `total` row | no |
+| `head` | first N rows (default 10, `-n`) | yes |
+| `cat` | all matching rows (streamed) | yes |
+| `sample` | reservoir sample (default 10, `-n` + `--seed`) | yes |
+
+Prefer no-scan verbs (`ls/schema/meta/stats/count`) — cheap and never hit the page-decode caveat.
+
+Table model + row verbs (`head/cat/sample/count`): without `-t`, only the **first** table is queried. Pass `-t <table>` to target a specific one.
+
+```
+opts: -f csv|tsv|json|table  (default TTY→table, pipe→tsv)
+      -d <device> | -t <table>   (mutually exclusive)
+      -m a,b,c (projection) · -n N · --offset N · --start <ms> · --end <ms> (inclusive)
+      --seed N · --no-header · --model tree|table (else auto)
+applies: -m → schema/head/cat/sample · -d/-t → row cmds/schema/stats/count · --offset ∉ sample
+json=NDJSON (num/bool bare, else quoted, null→null) · csv=RFC4180 · ts=raw epoch ms
+exit: 0 ok · 1 usage · 2 file open/corrupt · 3 query/runtime
+```
+
+```sh
+B=cpp/build/Debug/bin/tsfile-cli
+$B meta data.tsfile; $B count -t table1 -f tsv data.tsfile
+$B cat -m temp --start 1700000000000 -f csv data.tsfile 2>/dev/null | head
+```
+
+## Write
+
+`tsfile-cli write --table <name> --columns <spec> -o <out> [-f csv|tsv] [--no-header] [--header-match] [-v] [<input> | -]`
+
+Imports rows into a **new table-model** file (overwritten). Input col 0 = timestamp
+(epoch ms, int); remaining cols declared by `--columns` — **no type inference**.
+
+```
+spec  := col (',' col)*
+col   := name ':' TYPE ':' ('tag' | 'field')          # TYPE + category case-insensitive
+TYPE  ∈ { BOOLEAN, INT32, INT64, FLOAT, DOUBLE, STRING, TEXT, TIMESTAMP, DATE, BLOB }
+input := file | '-' | omitted                          # '-' or omitted = stdin
+```
+
+- `-o` required (overwritten, must differ from input); `-f` default csv (json/table → usage error).
+- header: first line skipped by default · `--no-header` if none · `--header-match` validates
+  header names vs `--columns` (mutually exclusive with `--no-header`).
+- empty cell = null · `--table` is lower-cased · `DATE` cells are `YYYY-MM-DD`, `TIMESTAMP` epoch ms · each column stored with the engine default encoding/compression for its type · success **silent**, `-v` → echoes the resolved config + `wrote N rows to <out>` on stderr.
+- **timestamps must be strictly increasing per device** (device = tag-column values); rows for
+  different tags may interleave/reuse timestamps. Out-of-order input → error with line number.
+- a failed import deletes its partial output (no half-written `.tsfile` left behind).
+- exit: `1` usage (missing `--table`/`--columns`/`-o`, bad spec, dup column, read-only flag) · `2` IO open · `3` row (field-count / type / overflow / timestamp-order / header mismatch).
+
+```sh
+printf 'time,id1,s1\n0,dev,0\n1,dev,10\n' \
+  | tsfile-cli write --table t1 --columns "id1:STRING:tag,s1:INT64:field" -o out.tsfile -
+tsfile-cli count -f tsv out.tsfile        # -> t1.dev  s1  2
+```
+
+Tree-model / JSON / programmatic writes → C++ SDK `cpp/examples/cpp_examples/demo_write.cpp`
+(`TsFileTableWriter`/`TsFileWriter` + `Tablet`); Java/Python writers under `java/`, `python/`.
+
+## Caveats
+
+- `head`/`cat`/`sample` decode pages → may abort (`decode_cur_time_page_data`, exit 134) on
+  some aligned files incl. bundled `cpp/examples/test_cpp.tsfile`. Storage-engine/file issue,
+  not a CLI bug; metadata verbs still work. Use a well-formed (e.g. self-written) file for rows.
+- table-model `target` is derived from tag bytes → may show non-printable chars in `stats/count/schema`.
+- `schema` lists all columns; `meta/stats/count` count only field series → `series_count` can be
+  fewer than `schema` rows (not a bug).
diff --git a/cpp/tools/tools_main.cc b/cpp/tools/tools_main.cc
new file mode 100644
index 000000000..97c815f47
--- /dev/null
+++ b/cpp/tools/tools_main.cc
@@ -0,0 +1,29 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include <iostream>
+#include <string>
+#include <vector>
+
+#include "cli/run_cli.h"
+
+int main(int argc, char** argv) {
+    std::vector<std::string> args(argv + 1, argv + argc);
+    return tsfile_cli::run_cli(args, std::cout, std::cerr);
+}