OfficeCLI dump vs batch Commands: Document Serialization Methods Explained

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, 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.

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 (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 (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.

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, 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 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 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 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.

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