Hi everyone, I would like to start a discussion about introducing tsfile-cli, a file-oriented command-line interface for Apache TsFile.
1. Motivation Many users first encounter a single .tsfile and need to answer relatively simple questions: What storage model does it use? Which tables or devices does it contain? What is the schema, time range, or row count? Can I inspect a few rows, stream data through a pipe, or convert CSV/TSV data into a new TsFile? Today, answering these questions often requires writing a C++/Java/Python program, constructing a reader, or using several specialized tools. The existing tools remain valuable, but they address different use cases: low-level physical debugging, bulk data import, SDK/API access, or queries against an IoTDB server. What is currently missing is a single, local, and pipe-friendly entry point for working with an individual TsFile. 2. AI-Assisted Access This capability is also increasingly important for AI-assisted workflows. An AI assistant cannot safely infer the schema and semantics of a binary TsFile. Without a stable command-line contract, it may generate one-off programs, guess at APIs, or repeatedly retry after ambiguous failures. A predictable CLI with machine-readable output, stable exit codes, explicit error handling, and a maintained SKILL.md gives both users and AI assistants a reliable way to inspect and process TsFile files. 3. Scope and Boundaries tsfile-cli is intended to complement the existing SDKs and IoTDB tools, not replace them. It does not introduce a new storage engine or a server-side query layer. Instead, it provides a thin, file-level interface on top of the existing TsFile C++ APIs. The initial scope focuses on one local TsFile at a time, covering common inspection, query, conversion, and automation tasks without requiring an IoTDB server or a language-specific application. 4. Current Implementation The initial implementation is already available in the repository under cpp/tools/. It currently includes commands for: listing tables or devices; inspecting schema and file metadata; collecting statistics and row counts; previewing, streaming, or sampling rows; importing CSV/TSV data into a new table-model TsFile. The implementation is built together with the C++ module. Its command behavior and examples are documented in: cpp/tools/README.md cpp/tools/skills/tsfile-cli/SKILL.md The initial implementation was introduced in PR #829. 5. Requirements Document The requirements document, including the proposed scope, command contracts, AI integration, testing, and future capabilities, is available here: https://apache-iotdb-project.feishu.cn/docx/Hbd3dA7lco78ofxAn5jc3talnkb It describes the motivation, target users, tree/table model boundaries, command contracts, output formats, error handling, safety requirements, AI integration, testing, and possible future capabilities such as controlled file export. The requirements document represents the proposed product direction. The current implementation should be understood as an initial baseline, rather than a claim that every proposed capability has already been completed. 6. Contributions I would particularly like to thank Zeyu Zhang, who has contributed substantially to this work. His contributions include multiple bug fixes and the addition of table-model TAG filtering in PR #837. This work helped move tsfile-cli from an initial prototype toward a more usable implementation. 7. Feedback Requested I would appreciate feedback from the community on: whether a standard file-level CLI would be useful as part of the TsFile distribution; the appropriate boundary between tsfile-cli, the SDKs, and IoTDB tools; the proposed command, output, and error contracts; the priority of the next implementation steps; how the CLI should eventually be packaged and released. Feedback on both the requirements document and the existing implementation would be very welcome. Best regards, Zhang Hongyin
