How to Import CSV Data into Excel Worksheets Using the OfficeCLI Import Command

The OfficeCLI import command bulk-loads CSV or TSV data into existing Excel workbooks using officecli import <file> <parent-path> with support for stdin input, automatic delimiter detection, and explicit cell formatting.

The iOfficeAI/OfficeCLI repository provides a robust solution for importing CSV data into Excel worksheets using the dedicated import command. This tool handles complex parsing scenarios—including quoted fields and embedded delimiters—while preserving data types and respecting Excel's dimensional limits.

Understanding the OfficeCLI Import Command Architecture

The import functionality spans two critical source files. In src/officecli/CommandBuilder.Import.cs, the CLI syntax is defined and options like --file, --stdin, --format, --header, and --start-cell are parsed and validated. The actual Excel manipulation occurs in src/officecli/Handlers/Excel/ExcelHandler.Import.cs, where the ExcelHandler.Import method orchestrates the data transfer from CSV strings to worksheet cells.

Command Syntax and Prerequisites

Before executing the import command, ensure your target workbook exists and carries a .xlsx extension. The basic syntax requires the workbook path, worksheet identifier (e.g., /Sheet1), and either a --file argument pointing to your CSV or the --stdin flag to pipe data.

officecli import <workbook.xlsx> <worksheet-path> [options]

Available options include:

• --file <path> – Path to the CSV or TSV file
• --stdin – Read CSV data from standard input
• --format <csv|tsv> – Force a specific delimiter format
• --header – Treat the first row as headers (adds AutoFilter and freeze pane)
• --start-cell <reference> – Starting cell address (default is A1)
• --json – Output results in JSON format

The Import Pipeline: From CSV to Excel Cells

Input Parsing and Validation

The command first validates that the target workbook exists and has a valid .xlsx extension. It then reads input from either the file specified via --file or from standard input when --stdin is provided. The raw CSV string, delimiter preference, header flag, and start cell address are packaged and forwarded to the Excel handler.

Delimiter Detection Logic

Delimiter selection follows a strict hierarchy defined in CommandBuilder.Import.cs. If --format is explicitly provided (e.g., csv or tsv), it overrides automatic detection. Otherwise, the file extension determines the delimiter—files ending in .tsv or .tab use tab characters, while all others default to commas. This ensures correct parsing regardless of file naming conventions.

Excel Dimension Safety Checks

Before writing any data, ExcelHandler.Import verifies that the import operation will not exceed Excel's hard limits of 1,048,576 rows or 16,384 columns (XFD). If the CSV data dimensions would violate these boundaries, the handler throws a descriptive ArgumentException to prevent workbook corruption.

Row Up-Sert Strategy

The handler implements an efficient row up-sert mechanism to avoid duplicate <row> elements—a specific fix for the documented "BUG-R11-import-dup-row" issue. Existing rows are indexed once and reused when possible, while new rows are inserted in sequential order only when necessary. This maintains worksheet integrity and prevents XML structure errors.

Cell Value Type Detection

For each cell populated during the import, SetCellValueWithTypeDetection automatically identifies and applies the appropriate data type:

• Numbers – Stored as numeric values
• ISO dates – Converted to Excel date serial numbers with format yyyy-mm-dd
• Booleans – Stored as Excel boolean types
• Formulas – Strings beginning with = are stored as formula cells
• Text – Default string storage for all other values

Header Row Handling

When the --header flag is enabled, the import process adds an AutoFilter covering the entire imported range and creates a freeze pane immediately below the header row. This preserves header visibility during vertical scrolling and enables native Excel filtering on the imported dataset.

Practical Code Examples

Import a local CSV file into Sheet1 starting at cell A1:

officecli import book.xlsx /Sheet1 --file data.csv

Stream TSV data via stdin with header detection and custom start cell:

cat data.tsv | officecli import book.xlsx /Sheet1 \
    --stdin --format tsv --header --start-cell B2

Force CSV format parsing regardless of file extension:

officecli import book.xlsx /Sheet1 --file data.dat --format csv

Capture JSON output for integration with automation scripts:

officecli import book.xlsx /Sheet1 --file data.csv --json

Summary

• The import command in iOfficeAI/OfficeCLI provides robust CSV-to-Excel importing via CommandBuilder.Import.cs and ExcelHandler.Import.cs.
• It supports both file-based (--file) and stdin (--stdin) input sources with automatic or explicit (--format) delimiter detection.
• Built-in dimension checks prevent exceeding Excel's 1,048,576 row and 16,384 column (XFD) limits before any data is written.
• Automatic data type detection via SetCellValueWithTypeDetection preserves numbers, ISO dates, booleans, and formulas during import.
• The --header option adds AutoFilter and freeze panes for improved worksheet navigation and data management.

Frequently Asked Questions

Can I import data into a specific cell range rather than just a starting cell?

The --start-cell parameter defines only the upper-left corner of the import range (e.g., B2). The command does not support restricting the lower bounds—the import continues until all CSV data is written or Excel's maximum dimensions are reached. Data expands rightward and downward from the specified start cell, overwriting existing content in those cells.

How does OfficeCLI handle CSV files with quoted fields or embedded commas?

The ParseCsv method in ExcelHandler.Import.cs properly handles RFC 4180-compliant CSV features including quoted fields, escaped quotes (represented as double double-quotes), embedded delimiters within quoted strings, and line breaks inside quoted values. This ensures complex data structures import correctly without requiring manual preprocessing or cleaning.

What happens if the target Excel file already contains data in the import range?

The import uses an up-sert strategy where existing rows are updated in place rather than duplicated. As implemented in the source code to address "BUG-R11-import-dup-row", the handler indexes existing rows by their row number and reuses them when possible, inserting new rows only when necessary. Any existing cells within the target range will be overwritten with new CSV values, while cells outside the import dimensions remain untouched.

Is there a limit to how much data I can import at once?

Yes. The ExcelHandler.Import method explicitly validates against Excel's architectural specifications: maximum 1,048,576 rows and 16,384 columns (XFD). If your CSV data would exceed either limit, the command throws an ArgumentException before modifying the workbook, preventing the generation of invalid or corrupted Excel files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}