# How to Import CSV Data into Excel Worksheets Using the OfficeCLI Import Command > Easily import CSV data into Excel using the OfficeCLI import command. Bulk-load files with automatic delimiter detection and explicit formatting. Learn how now. - Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI) - Tags: how-to-guide - Published: 2026-07-29 --- **The OfficeCLI `import` command bulk-loads CSV or TSV data into existing Excel workbooks using `officecli import ` 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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. ```bash officecli import [options] ``` Available options include: - `--file ` – Path to the CSV or TSV file - `--stdin` – Read CSV data from standard input - `--format ` – Force a specific delimiter format - `--header` – Treat the first row as headers (adds AutoFilter and freeze pane) - `--start-cell ` – 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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 `` 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: ```bash officecli import book.xlsx /Sheet1 --file data.csv ``` Stream TSV data via stdin with header detection and custom start cell: ```bash cat data.tsv | officecli import book.xlsx /Sheet1 \ --stdin --format tsv --header --start-cell B2 ``` Force CSV format parsing regardless of file extension: ```bash officecli import book.xlsx /Sheet1 --file data.dat --format csv ``` Capture JSON output for integration with automation scripts: ```bash 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Import.cs) and [`ExcelHandler.Import.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.