Streaming writer handle, CLI tool, schema inference, and write/Arrow bindings for C++/Rust/Python

.github/workflows/release.yml

@@ -56,6 +56,19 @@ jobs:
           -p:Version=${{ steps.version.outputs.value }}
           --output ./artifacts
 
+      # Portable IL tool package (see the csproj: "a dotnet tool ships as IL and is launched by
+      # whatever SDK the user has") - not the self-contained AOT binaries publish-cli attaches to
+      # the GitHub Release below, which need no .NET runtime installed but must be built per-RID.
+      # `dotnet tool install --global ExcelReader.NET.Cli` (README's documented install command)
+      # resolves this package.
+      - name: Pack CLI
+        run: >-
+          dotnet pack src/ExcelReader.Cli/ExcelReader.Cli.csproj
+          --configuration Release
+          --no-restore
+          -p:Version=${{ steps.version.outputs.value }}
+          --output ./artifacts
+
       - name: Generate SBOM
         uses: anchore/sbom-action@v0
         with:
@@ -127,6 +140,76 @@ jobs:
           files: ${{ steps.asset.outputs.name }}
           fail_on_unmatched_files: true
 
+  publish-cli:
+    name: Publish excelreader CLI (${{ matrix.os }})
+    needs: publish
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: write
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v6
+        with:
+          global-json-file: global.json
+
+      - name: Derive version from tag
+        id: version
+        shell: bash
+        run: echo "value=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Determine RID
+        id: rid
+        shell: bash
+        run: |
+          arch=$([ "$(uname -m 2>/dev/null || echo x64)" = "arm64" ] && echo arm64 || echo x64)
+          case "${{ runner.os }}" in
+            Windows) os=win ;;
+            macOS)   os=osx ;;
+            *)       os=linux ;;
+          esac
+          echo "value=${os}-${arch}" >> "$GITHUB_OUTPUT"
+
+      # PublishAot/PackAsTool=false override the project's normal dotnet-tool packaging (a
+      # dotnet tool ships as IL, launched by the caller's own SDK) with a single self-contained
+      # native executable instead - no .NET runtime required on the machine that runs it.
+      # ConsoleAppFramework is already compile-time only and Spectre.Console is AOT-compatible,
+      # so this publishes clean with zero IL2xxx/IL3xxx trim warnings.
+      - name: Publish native AOT binary
+        shell: bash
+        run: >-
+          dotnet publish src/ExcelReader.Cli/ExcelReader.Cli.csproj
+          --configuration Release
+          -r ${{ steps.rid.outputs.value }}
+          -p:PublishAot=true
+          -p:PackAsTool=false
+          -p:Version=${{ steps.version.outputs.value }}
+          --output ./cli-publish
+
+      - name: Rename asset for this platform
+        id: asset
+        shell: bash
+        run: |
+          case "${{ runner.os }}" in
+            Windows) src=ExcelReader.Cli.exe; ext=.exe ;;
+            *)       src=ExcelReader.Cli;     ext= ;;
+          esac
+          name="excelreader-${{ steps.rid.outputs.value }}${ext}"
+          cp "./cli-publish/${src}" "${name}"
+          echo "name=${name}" >> "$GITHUB_OUTPUT"
+
+      - name: Upload to the GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: ${{ steps.asset.outputs.name }}
+          fail_on_unmatched_files: true
+
   publish-rust:
     name: Publish Rust crates
     needs: publish-native-assets

.gitignore

@@ -503,4 +503,6 @@ python/src/excelreader/_lib/*
 
 # CMake build output (tests/ExcelReader.NativeSmoke and any other CMake-configured project). Never
 # built to a path inside the source tree other than this, so a plain top-level rule is enough.
-build/
+build/
+# Subagent-driven-development scratch (per-plan ledgers, briefs, review packages)
+.superpowers/

.vscode/settings.json

@@ -11,5 +11,8 @@
         "-DEXCELREADER_BUILD_BENCHMARKS_COMPARE=ON",
         "-DEXCELREADER_BUILD_TESTS=ON",
         "-DCMAKE_POLICY_VERSION_MINIMUM=3.5"
-    ]
+    ],
+    "rust-analyzer.server.extraEnv": {
+        "EXCELREADER_NATIVE_LIB_DIR": "${workspaceFolder}/python/src/excelreader/_lib"
+    }
 }

ARCHITECTURE.md

@@ -48,6 +48,28 @@ Reader internals that would otherwise be duplicated four times over live in one
   the single buffer-growth-cap function (`NextBufferSize`) every pooled buffer in the stack grows
   through, so one limit policy governs all of them consistently.
 
+## The `excelreader` CLI
+
+`src/ExcelReader.Cli/` is a thin `dotnet tool` shell (`excelreader`) over Core's public API — it
+parses no spreadsheet bytes of its own. It splits in two on purpose: `Commands` is a one-line-per-
+command adapter whose XML doc comments ConsoleAppFramework's source generator turns into argument
+parsing, routing and `--help`, while `CliCommands` holds the bodies as plain functions over explicit
+writers. The split keeps the tested surface free of the framework's static output hooks, so the CLI
+tests run in parallel like every other test class. ConsoleAppFramework is compile-time only
+(`PrivateAssets`), so the published tool's only *runtime* dependency besides ExcelReader.Core is
+Spectre.Console, used for `sheets`/`schema`'s tables and `convert`'s progress spinner on a real
+terminal.
+
+Rendering follows `Commands`/`CliCommands`'s own split, one level further: `Commands` picks plain vs.
+interactive per call (`Console.IsOutputRedirected`/`IsErrorRedirected`), so a script gets the exact
+same tab-separated text and stderr line the tool always wrote, unchanged. Two small always-stderr
+helpers back that split - `ErrorConsole` (a Spectre `IAnsiConsole` pinned to `Console.Error`, since
+Spectre's own default instance targets stdout, which `convert` may be using for the converted bytes
+themselves) and `ColorizingErrorWriter` (a `TextWriter` that renders `CliCommands.Execute`'s one-line
+failure in red through `ErrorConsole` on a terminal, or passes it through byte-for-byte otherwise).
+Both live in `ExcelReader.Cli`, not `CliCommands.cs` - the interactive/plain decision is
+`Console`-shaped state, exactly what that file's tests are built to never touch.
+
 ## Why readers are split into partial classes
 
 `XlsxReader` and `XlsbReader` are large enough that one file would be unwieldy, so each is split by

ExcelReader.slnx

@@ -1,5 +1,6 @@
 <Solution>
   <Folder Name="/src/">
+    <Project Path="src/ExcelReader.Cli/ExcelReader.Cli.csproj" />
     <Project Path="src/ExcelReader.Core/ExcelReader.Core.csproj" />
     <Project Path="src/ExcelReader.Native/ExcelReader.Native.csproj" />
     <Project Path="src/ExcelReader.Generator/ExcelReader.Generator.csproj" />

README.md

@@ -18,6 +18,32 @@ ExcelReader is built for streaming spreadsheet workloads where low allocations m
 dotnet add package ExcelReader.NET
 ```
 
+## Command line
+
+```bash
+dotnet tool install --global ExcelReader.NET.Cli
+```
+
+```bash
+excelreader sheets  book.xlsb                        # 0<TAB>Sheet1
+excelreader schema  book.xlsb --sample-size 500      # 0<TAB>Id<TAB>Int64
+excelreader convert book.xlsb --output data.csv      # convert to another format, by extension
+excelreader convert book.xlsb --output data.xlsx     # .xlsx, .xlsb, .xls and .csv all work
+excelreader convert book.xlsb --format xlsx | head -c 4   # to stdout, --format picks it instead
+```
+
+Flags: `--sheet|-s <name|index>`, `--header-row N` (0 = no header), `--sample-size N`,
+`--output|-o <file>`, `--format|-f <xlsx|xlsb|xls|csv>` (defaults to `--output`'s extension, or csv
+for stdout), `--delimiter|-d <char>` (csv only). Run `excelreader <command> --help` for the full list.
+
+On a real terminal, `sheets`/`schema` render as a [Spectre.Console](https://spectreconsole.net) table
+and `convert` shows a progress spinner on stderr; piped or redirected (a script, `| head`, `2>file`),
+every command falls back to the same plain tab-separated text and stderr line it always wrote, so
+nothing here changes for anything already parsing this tool's output.
+
+Exit codes are `0` ok and `1` failure; results go to stdout and errors to stderr, so `convert` is
+safe to pipe.
+
 ## Read rows
 
 ```csharp
@@ -863,13 +889,13 @@ dotnet test --project tests/ExcelReader.Tests/ExcelReader.Tests.csproj --configu
 
 ## Other languages
 
-ExcelReader ships a NativeAOT shared library with a C ABI, so non-.NET languages can read XLSX,
-XLSB, XLS and CSV without a .NET runtime installed.
+ExcelReader ships a NativeAOT shared library with a C ABI, so non-.NET languages can read and write
+XLSX, XLSB, XLS and CSV without a .NET runtime installed.
 
 - C ABI header: [`src/ExcelReader.Native/include/excelreader.h`](src/ExcelReader.Native/include/excelreader.h)
 - Python package: [`python/`](python/README.md)
-- C++ package: header-only CMake wrapper, `xl::Workbook`/`xl::parse_sheet` over the same ABI — see [`cpp/README.md`](cpp/README.md).
-- Rust crate: safe `Workbook`/`parse_sheet` bindings, downloadable via `cargo add excelreader` — see [`rust/excelreader/README.md`](rust/excelreader/README.md).
+- C++ package: header-only CMake wrapper, `xl::Workbook`/`xl::parse_sheet`/`xl::write_sheet` over the same ABI — see [`cpp/README.md`](cpp/README.md).
+- Rust crate: safe `Workbook`/`parse_sheet`/`write_sheet` bindings, downloadable via `cargo add excelreader` — see [`rust/excelreader/README.md`](rust/excelreader/README.md).
 
 ```python
 from excelreader import open_workbook
@@ -879,7 +905,28 @@ with open_workbook("book.xlsx") as workbook:
         print([cell.value for cell in row])
 ```
 
-Reading only — the writers are not exposed across the ABI yet.
+Writing goes through one export, `xl_write_typed`: a whole sheet in a single call, from columnar
+buffers the ABI borrows rather than copies. All three bindings expose it — Python as
+`write_workbook`/`write_arrow`/`write_pandas`/`write_polars`, C++ as `xl::write_columns` and
+`xl::write_sheet<T>`, Rust as `writer::write_columns` and `writer::write_sheet`. In C++ and Rust the
+same struct mapping drives both directions, so reading a sheet and writing it back needs one
+mapping, not two:
+
+```rust
+use excelreader::writer::write_sheet;
+use excelreader::XL_FORMAT_XLSX;
+
+write_sheet("out.xlsx", XL_FORMAT_XLSX, &rows, None)?;
+```
+
+```cpp
+auto written = xl::write_sheet("out.xlsx", rows);   // format inferred from the extension
+```
+
+Row-by-row decoded reads remain Python-only. The Arrow export is available from Python
+(`to_arrow`/`to_record_batch`), C++ (`xl::parse_arrow<T>`, in the separate `<xl/excelreader_arrow.hpp>`
+header — no Apache Arrow C++ dependency, you get the raw C Data Interface pair), and Rust
+(`excelreader::arrow::parse_arrow`, behind the `arrow` cargo feature, returning an `arrow::array::RecordBatch`).
 
 ## Contributing