# OfficeCLI dump vs batch Commands: Document Serialization Methods Explained

> Understand OfficeCLI dump vs batch commands. Learn how dump serializes single documents and batch efficiently handles multiple commands for streamlined operations.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: deep-dive
- Published: 2026-07-11

---

**The `dump` command retrieves raw plain-text serialization of a single document or cell, while `batch` sends multiple commands in one round-trip to efficiently perform many reads or writes together.**

The OfficeCLI SDK provides two distinct pathways for document serialization when communicating with the **officecli** resident process. Understanding when to use the **dump** command versus the **batch** command is essential for optimizing performance and getting the correct output format from your Excel and Office documents.

## Core Differences Between dump and batch Commands

The primary distinction lies in how each method communicates with the resident process and what they return:

| Feature | **dump** (single-command) | **batch** (multi-command) |
|---------|---------------------------|---------------------------|
| **Purpose** | Returns raw plain-text serialization of a document, sheet, or cell. | Sends a list of command objects in one round-trip for bulk operations. |
| **API Method** | `Document.send(item, asJson = false)` | `Document.batch(items, options?)` |
| **Output Format** | Raw text (CSV, XML, or JSON) without envelope. | JSON envelope containing results for each batched item. |
| **Performance** | One round-trip per command. | One round-trip for multiple commands, reducing pipe overhead. |
| **Use Case** | Exporting, debugging, or diffing single documents. | Bulk updates or retrieving multiple data points efficiently. |

## How dump Works for Document Serialization

In [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js), the `Document.send` method handles single-command operations. When you invoke the dump functionality, the SDK builds a request with `asJson` explicitly set to `false`, which tells the resident to reply with plain-text instead of a JSON envelope.

The implementation extracts the command name from the supplied item and forwards it to the resident. According to the source code comments, setting `asJson` to `false` "requests plain-text output (view/raw/dump), mirroring the CLI's `--json`" behavior.

```javascript
import { open } from 'officecli-sdk';

async function dumpDocument(path) {
  const doc = await open(path);
  // asJson=false requests raw text rather than JSON envelope
  const result = await doc.send({ command: 'dump', path: '/' }, false);
  await doc.close();
  return result;   // Returns plain-text (e.g., CSV or XML)
}

dumpDocument('myWorkbook.xlsx')
  .then(text => console.log('Serialized dump:\n', text))
  .catch(err => console.error('Dump failed:', err));

```

Key implementation details in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) (lines 503-505) show that the `send` method checks the `asJson` flag to determine whether to return raw text or parse a JSON response.

## How batch Works for Document Serialization

The `Document.batch` method, located in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) (lines 19-22), builds a JSON array (`batchJson`) of command items and forwards them as a single `batch` command. This approach packs all items into one payload, allowing the resident to process each item sequentially and return a combined envelope.

```javascript
import { open } from 'officecli-sdk';

async function batchDump(path, sheetNames) {
  const doc = await open(path);
  const items = sheetNames.map(name => ({
    command: 'dump',
    path: `/Sheet/${name}`,
  }));
  // Sends all dump commands in one round-trip
  const envelope = await doc.batch(items);
  await doc.close();
  // envelope.results contains an array of results
  return envelope.results.map(r => r.text);
}

batchDump('myWorkbook.xlsx', ['Sheet1', 'Sheet2'])
  .then(dumps => dumps.forEach((txt, i) => console.log(`Sheet ${i+1} dump:\n`, txt)))
  .catch(err => console.error('Batch dump failed:', err));

```

The resident processes the entire `batchJson` array and returns a JSON envelope containing the result of each batched item, including success or error information for individual operations.

## When to Use dump vs batch for Document Serialization

Use **dump** when you need the exact serialized content of a single document or specific resource. This method is ideal for exporting data, debugging document structure, or creating diffs between versions. The raw text output avoids the overhead of JSON parsing when you need the actual file content.

Use **batch** when applying many changes or retrieving multiple data points. This method significantly reduces the overhead of repeated pipe communication by bundling commands together. It is the preferred approach for setting many cells, updating multiple sheets, or performing bulk read operations where network latency or process communication costs matter.

## Summary

- **dump** uses `Document.send` with `asJson=false` to retrieve raw plain-text serialization from [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js), suitable for single-document exports.
- **batch** uses `Document.batch` to send multiple commands in one round-trip via a `batchJson` payload, defined in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) lines 19-22.
- **dump** returns raw text (CSV, XML) directly, while **batch** returns a JSON envelope containing results for each operation.
- Choose **dump** for debugging and single-document serialization; choose **batch** for bulk operations and performance optimization.

## Frequently Asked Questions

### What is the difference between dump and batch in OfficeCLI?

The **dump** command retrieves the raw serialized representation of a single document or cell as plain text, while the **batch** command sends multiple commands to the resident process in one round-trip and returns a JSON envelope with results for each operation. According to the iOfficeAI/OfficeCLI source code, dump operates via `Document.send` with `asJson=false`, whereas batch uses `Document.batch` to pack commands into a `batchJson` array.

### How do I get raw text output instead of JSON in OfficeCLI?

Pass `false` as the second argument to `Document.send()`. This sets the `asJson` parameter to `false`, which triggers the dump mode in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) and requests plain-text output from the resident process. The resident then returns the raw serialization (such as CSV or XML) rather than wrapping it in a JSON envelope.

### Can I combine multiple dump operations into a single call?

Yes. Create an array of command objects where each object specifies `command: 'dump'` and the desired path, then pass this array to `Document.batch()`. The method defined in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) packs these into a `batchJson` payload and sends them together, returning a JSON envelope where each result contains the raw text dump for the corresponding item.

### Which method offers better performance for bulk operations?

The **batch** method provides significantly better performance for bulk operations because it sends multiple commands in a single round-trip to the resident process. This reduces the overhead of repeated pipe communication compared to calling **dump** multiple times via `Document.send`, which requires a separate round-trip for each command.