CLI Interface

Loading…

CLI Interface

Relevant source files

• src/cli.rs
• src/cli/cli_parser.rs
• src/cli/execute_command.rs
• tests/cli_tests.rs

The simd-r-drive CLI provides a high-level interface for interacting with the underlying storage engine from the terminal. It serves as the primary entry point for manual data manipulation, administrative tasks like compaction, and piping data into or out of the append-only storage files.

The CLI is designed to be “pipe-friendly,” supporting both direct string arguments and binary streams via standard input (stdin) and standard output (stdout).

System Architecture and Delegation

The CLI layer is built using the clap library and acts as a thin wrapper around the DataStore API. When a command is issued, the CLI parses the arguments via the Cli struct src/cli/cli_parser.rs:16-26 matches the command in the Commands enum src/cli.rs:4-5 and delegates the logic to the appropriate DataStore methods via execute_command src/cli/execute_command.rs25

CLI to Code Entity Mapping

The following diagram illustrates how CLI components map to the internal code structures and how they interact with the core storage engine.

CLI Delegation Flow

graph TD
    subgraph "CLI_Space_(User_Interface)"
 
       A["Terminal Command"] --> B["Cli Struct"]
B --> C["Commands Enum"]
end

    subgraph "Code_Entity_Space_(src/cli/)"
        B["Cli Struct"] --- B_DEF["cli_parser.rs:16-26"]
C["Commands Enum"] --- C_DEF["src/cli/commands.rs"]
D["execute_command()"] --- D_DEF["execute_command.rs:25-25"]
end

    subgraph "Storage_Engine_Space_(src/storage_engine/)"
        E["DataStore"] --- E_DEF["DataStore::open()"]
F["DataStoreReader"]
G["DataStoreWriter"]
end

 
   C --> D
 
   D --> E
 
   E --> F
 
   E --> G

Sources: src/cli/cli_parser.rs:16-26 src/cli.rs:4-5 src/cli/execute_command.rs25

Command Execution Flow

The central logic for processing CLI requests resides in execute_command src/cli/execute_command.rs25 This function matches the parsed Commands enum and performs the necessary setup, such as opening the DataStore and handling I/O streams.

Sources: src/cli/execute_command.rs:25-175

Stream Handling and Terminal Detection

The CLI intelligently handles different output modes. When read is called, the system detects if the output is a TTY (terminal) or a pipe via is_terminal() src/cli/execute_command.rs48

• Terminal Mode: If outputting to a terminal, the CLI attempts to validate UTF-8 strings for readable display src/cli/execute_command.rs:58-63 It also appends a newline for cleaner terminal output src/cli/execute_command.rs:72-74
• Binary/Pipe Mode: If the output is redirected (e.g., > file.bin), it emits raw binary data without modification src/cli/execute_command.rs:64-67

For writes, the CLI supports write_stream src/cli/execute_command.rs100 allowing users to pipe large files into the database via stdin src/cli/execute_command.rs:98-103 It also supports custom buffer sizes for reading large entries, parsed via parse_buffer_size src/cli/execute_command.rs33 and defaulting to 64KB src/cli/execute_command.rs39

Integration Testing

The CLI interface is verified through integration tests in tests/cli_tests.rs. These tests spawn the binary using std::process::Command tests/cli_tests.rs:15-26 to ensure that the end-to-end flow—from argument parsing to disk persistence—works as expected. Tests cover basic read/write tests/cli_tests.rs:11-41 large file chunking via --buffer-size tests/cli_tests.rs:111-167 and multi-storage operations like copy tests/cli_tests.rs:171-219

CLI Command Integration

Sources: tests/cli_tests.rs:11-41 tests/cli_tests.rs:111-167 tests/cli_tests.rs:171-219

Sub-pages

CLI Commands Reference

Detailed documentation for every available command, including flag descriptions, binary output behavior, and buffer size configuration for large data transfers. For details, see CLI Commands Reference.

CLI Parser and Help System

Technical overview of the clap implementation, the Cli structure src/cli/cli_parser.rs:16-26 and how the custom help template src/cli/help_template.rs8 is integrated into the binary’s --help output. For details, see CLI Parser and Help System.