CLI Commands Reference

Loading…

CLI Commands Reference

Relevant source files

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

This page provides a comprehensive technical reference for the simd-r-drive Command Line Interface (CLI). The CLI serves as the primary entry point for interacting with the append-only storage engine, providing commands for data manipulation, maintenance, and inspection.

Architecture Overview

The CLI is built using the clap crate for argument parsing and delegates all core logic to the DataStore engine. The execution flow follows a pattern of parsing arguments into a Cli struct, which contains a Commands enum, and then dispatching these to the execute_command function src/cli/execute_command.rs:25-26

CLI Data Flow and Entity Mapping

The following diagram illustrates how CLI commands map to specific functions within the DataStore and how data streams through the system.

Diagram: CLI to Storage Engine Mapping

graph TD
    subgraph "CLI Layer (src/cli/)"
 
       A["Cli Struct (src/cli/cli_parser.rs)"] --> B["Commands Enum (src/cli/commands.rs)"]
B --> C["execute_command() (src/cli/execute_command.rs)"]
end

    subgraph "Logic & Data Flow"
        C -- "Read/Stream" --> D["EntryStream (src/storage_engine/entry_stream.rs)"]
C -- "Write/Stream" --> E["DataStoreWriter::write_stream()"]
C -- "Maintenance" --> F["DataStore::compact()"]
end

    subgraph "Core Engine (src/storage_engine/)"
 
       D --> G["DataStoreReader::read()"]
E --> H["DataStore::write_stream()"]
F --> I["EntryIterator (src/storage_engine/entry_iterator.rs)"]
end

    style A stroke-dasharray: 5 5
    style G font-weight:bold
    style H font-weight:bold

Sources: src/cli/execute_command.rs:1-7 src/cli/execute_command.rs:25-174 src/cli/commands.rs:5-65

Command Reference

Read

Retrieves the value associated with a specific key and outputs it to stdout.

• Usage: <storage> read <key> [--buffer-size <size>]
• Buffer Management: Defaults to 64KB if --buffer-size is not provided src/cli/execute_command.rs:30-39 It uses parse_buffer_size to handle human-readable strings like “32K” or “1M” src/cli/execute_command.rs:33-34
• Output Modes:
  • Terminal: If stdout is a TTY (checked via is_terminal()), the CLI attempts to validate the data as UTF-8. If valid, it prints as text; otherwise, it falls back to raw bytes src/cli/execute_command.rs:48-63 A newline is appended for readability src/cli/execute_command.rs:72-74
  • Piped/Binary: If redirected (e.g., > file.bin), it outputs raw binary data without modification or trailing newlines src/cli/execute_command.rs:64-67

Sources: src/cli/commands.rs:7-14 src/cli/execute_command.rs:27-85 tests/cli_tests.rs:111-167

Write

Stores a value for a given key. Supports both direct arguments and piped input.

• Usage: <storage> write <key> [value]
• Direct Write: If value is provided as an argument, it is written directly to the store using DataStore::write() src/cli/execute_command.rs:91-95
• Piped Stdin: If value is omitted and stdin is not a terminal, the CLI uses DataStore::write_stream() to pipe data from stdin directly into the storage file src/cli/execute_command.rs:96-103
• Validation: If neither a value nor a pipe is detected (checked via is_terminal() and the FORCE_NO_TTY environment variable), the command exits with an error src/cli/execute_command.rs:96-108

Sources: src/cli/commands.rs:17-23 src/cli/execute_command.rs:87-111 tests/cli_tests.rs:45-67

Copy, Move, and Rename

These commands manage entry lifecycle across the same or different storage files.

Sources: src/cli/commands.rs:26-46 src/cli/execute_command.rs:113-160

Delete

Marks a key as deleted by appending a “tombstone” entry to the storage file.

• Usage: <storage> delete <key>
• Implementation: Calls DataStore::delete(), which ensures the key is no longer reachable via the index by writing a null-payload entry src/cli/execute_command.rs:165-167

Sources: src/cli/commands.rs:49-52 src/cli/execute_command.rs:162-169

Compact

Reclaims disk space by removing shadowed (old) versions of keys and deleted entries.

• Usage: <storage> compact
• Logic: It opens the storage in read-write mode and triggers the compaction process via DataStore::compact() src/cli/execute_command.rs:171-174

Sources: src/cli/commands.rs55 src/cli/execute_command.rs:171-174

Info and Metadata

Provides diagnostic information about the storage file or a specific entry.

• Info: Displays high-level storage stats like file size and entry count src/cli/commands.rs58
• Metadata: Retrieves the EntryMetadata for a specific key, including its hash, offset, and checksum src/cli/commands.rs:61-64

Sources: src/cli/commands.rs:58-64 src/cli/execute_command.rs26

Execution Logic and Error Handling

The CLI uses a centralized execute_command function to handle the lifecycle of a command, from opening the DataStore to handling I/O errors.

Diagram: Write Command Execution Flow

sequenceDiagram
    participant U as "User/Shell"
    participant C as "execute_command (src/cli/execute_command.rs)"
    participant S as "DataStore (src/storage_engine/mod.rs)"
    participant F as "File System"

    U->>C: write key [value]
    alt "Value Provided"
        C->>S: DataStore::write(key, value)
        S->>F: Append Entry
    else "Piped Stdin"
        U->>C: "echo 'data' | bin write key"
        C->>S: DataStore::write_stream(key, stdin)
        loop "Chunked Read"
            S->>F: Append Chunks via SIMD/Scalar
        end
    end
    C->>U: Print 'Stored key'

Key Functions

• DataStore::open_existing(&path): Used by commands that require an existing file (Read, Info, Metadata) src/cli/execute_command.rs28
• DataStore::open(&path): Used by commands that can create a file if it’s missing (Write) src/cli/execute_command.rs88
• parse_buffer_size(String): Converts inputs like “64K” into usize bytes src/cli/execute_command.rs33

Sources: src/cli/execute_command.rs:25-174 src/utils/mod.rs:1-10

Global Options

Storage Path

The first argument to the binary is always the path to the storage file. If the file does not exist, commands like write will create it automatically via DataStore::open, while read will fail via DataStore::open_existing src/cli/execute_command.rs28 src/cli/execute_command.rs88

Buffer Size Flag

Available on the read command, the --buffer-size (or -b) flag controls the internal memory allocation for streaming data from the storage engine to stdout. This is particularly useful when reading very large entries to prevent excessive memory consumption src/cli/commands.rs:11-13

Sources: src/cli/commands.rs:7-14 tests/cli_tests.rs:111-167