Skip to content

command batch

Jump to bottom
zmworm edited this page Apr 4, 2026 · 29 revisions

batch

Execute multiple commands in a single open/save cycle.

Synopsis

officecli batch <file> [--input <file>] [--commands '<json>'] [--force] [--json]

Description

Executes a sequence of commands from a JSON array, opening the document once and saving once at the end. This is more efficient than running individual commands.

By default, execution stops on the first error so the caller (e.g. an AI agent) can inspect the failure and decide how to proceed. Succeeded commands' changes are still saved to disk. Use --force to continue executing all commands regardless of errors.

Commands are read from a JSON file (--input), inline JSON (--commands), or from stdin.

Arguments

Name Type Required Default Description
file FileInfo Yes - Office document path

Options

Name Type Required Default Description
--input FileInfo No stdin JSON file containing batch commands
--commands string No - Inline JSON array of batch commands (alternative to --input or stdin)
--force bool No false Continue execution even if a command fails. Default: stop on first error.
--json bool No false Output results as structured JSON

Input Format

The input is a JSON array of command objects. Each object has the following fields:

Field Type Required Description
command string Yes Command name: get, query, set, add, remove, move, view, raw, raw-set, validate. Alias: op
path string No DOM path (for get, set, remove, move)
parent string No Parent path (for add)
type string No Element type (for add)
from string No Source path for copy (for add)
index int No Insert position (for add, move)
to string No Target parent (for move)
props object No Properties as key-value pairs (for set, add)
selector string No CSS-like selector (for query)
mode string No View mode (for view)
depth int No Child depth (for get)
part string No Part path (for raw, raw-set)
xpath string No XPath expression (for raw-set)
action string No XML action (for raw-set)
xml string No XML fragment (for raw-set)

Output Format

Text Mode (default)

Each result is prefixed with its 1-based index:

[1] OK
[2] output text here
[3] ERROR: error message
---
3 commands: 2 succeeded, 1 failed

JSON Mode

{
  "results": [
    { "index": 0, "success": true, "output": "..." },
    { "index": 1, "success": true, "output": "..." },
    { "index": 2, "success": false, "error": "error message", "item": { "command": "set", "path": "/slide[999]", "props": { "title": "bad" } } }
  ],
  "summary": {
    "total": 3,
    "executed": 3,
    "succeeded": 2,
    "failed": 1,
    "skipped": 0
  }
}

When get or query commands return structured data, the output field contains the parsed JSON object directly (not a double-encoded string).

Failed results include the original batch item in the item field, so the caller can inspect the failing command and its parameters without having to correlate by index.

Large Output (spill-to-file)

When the JSON output exceeds 8 KB, the full results are written to a temp file and a slim envelope is returned inline:

{
  "outputFile": "/tmp/officecli_batch_abc123.json",
  "outputSize": 156234,
  "results": [
    { "index": 0, "success": true },
    { "index": 1, "success": true },
    { "index": 2, "success": false, "error": "Slide 999 not found", "item": { "command": "set", "path": "/slide[999]", "props": { "title": "bad" } } }
  ],
  "summary": { "total": 3, "executed": 3, "succeeded": 2, "failed": 1, "skipped": 0 }
}

The temp file contains the full original JSON with all output fields. Error messages and the original item are always inline so the caller can act without reading the file.

Examples

From stdin

echo '[
  {"command": "set", "path": "/body/p[1]", "props": {"style": "Heading1", "text": "Title"}},
  {"command": "add", "parent": "/body", "type": "paragraph", "props": {"text": "New paragraph"}},
  {"command": "set", "path": "/body/p[2]", "props": {"bold": "true"}}
]' | officecli batch report.docx

From file

officecli batch report.docx --input commands.json

JSON output

officecli batch report.docx --input commands.json --json

Continue on error

officecli batch report.docx --input commands.json --force

Complex batch example

commands.json:

[
  {
    "command": "set",
    "path": "/",
    "props": { "title": "Quarterly Report", "author": "Finance Team" }
  },
  {
    "command": "add",
    "parent": "/body",
    "type": "paragraph",
    "props": { "text": "Executive Summary", "style": "Heading1" }
  },
  {
    "command": "add",
    "parent": "/body",
    "type": "paragraph",
    "props": { "text": "This report covers Q4 2024 performance." }
  },
  {
    "command": "add",
    "parent": "/body",
    "type": "table",
    "props": { "rows": "4", "cols": "3" }
  },
  {
    "command": "set",
    "path": "/body/tbl[1]/tr[1]/tc[1]",
    "props": { "text": "Category", "bold": "true", "shd": "4472C4", "color": "FFFFFF" }
  },
  {
    "command": "set",
    "path": "/body/tbl[1]/tr[1]/tc[2]",
    "props": { "text": "Q3", "bold": "true", "shd": "4472C4", "color": "FFFFFF" }
  },
  {
    "command": "set",
    "path": "/body/tbl[1]/tr[1]/tc[3]",
    "props": { "text": "Q4", "bold": "true", "shd": "4472C4", "color": "FFFFFF" }
  },
  {
    "command": "get",
    "path": "/body",
    "depth": 1
  },
  {
    "command": "validate"
  }
]

Excel batch example

[
  { "command": "add", "parent": "/", "type": "sheet", "props": { "name": "Summary" } },
  { "command": "set", "path": "/Summary/A1", "props": { "value": "Total Revenue", "bold": "true" } },
  { "command": "set", "path": "/Summary/B1", "props": { "formula": "=SUM(Sheet1!B:B)", "numFmt": "#,##0.00" } },
  { "command": "add", "parent": "/Summary", "type": "chart", "props": {
    "chartType": "bar",
    "title": "Revenue by Quarter",
    "categories": "Q1,Q2,Q3,Q4",
    "series1": "Revenue:1000,2000,1500,3000"
  }}
]

PowerPoint batch example

[
  { "command": "add", "parent": "/", "type": "slide", "props": { "title": "Introduction", "layout": "title" } },
  { "command": "set", "path": "/slide[1]", "props": { "background": "1A1A2E" } },
  { "command": "add", "parent": "/slide[1]", "type": "shape", "props": {
    "text": "Welcome",
    "x": "2cm", "y": "3cm", "width": "20cm", "height": "5cm",
    "font": "Arial", "size": "36", "bold": "true", "color": "FFFFFF",
    "fill": "none"
  }},
  { "command": "add", "parent": "/", "type": "slide", "props": { "layout": "blank" } },
  { "command": "add", "parent": "/slide[2]", "type": "chart", "props": {
    "chartType": "pie",
    "title": "Market Share",
    "categories": "Product A,Product B,Product C",
    "data": "Share:40,35,25",
    "x": "2cm", "y": "2cm", "width": "20cm", "height": "15cm"
  }}
]

Notes

  • All commands in a batch share a single open/save cycle, making batch mode significantly faster than individual commands.
  • By default, execution stops on the first error. Use --force to continue all commands regardless of failures.
  • Succeeded commands' changes are always saved to disk, even when a later command fails (partial save by design — add commands are not idempotent, so rollback would cause duplicates on retry).
  • Returns non-zero exit code when any command fails.
  • Read-only commands (get, query, view, validate) can be mixed with write commands.
  • Add commands accept path as fallback when parent is not set.
  • When using resident mode (open), each batch item is forwarded individually to the resident process.

See Also

Based on OfficeCLI v1.0.32

Clone this wiki locally