Skip to content

command batch

Jump to bottom
zmworm edited this page Mar 31, 2026 · 23 revisions

batch

Execute multiple commands in a single open/save cycle.

Synopsis

officecli batch <file> [--input <file>] [--commands '<json>'] [--stop-on-error] [--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 and ensures all changes are applied atomically.

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
--stop-on-error bool No false Stop execution on first error. Default: continue all commands.
--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
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

[
  { "success": true, "output": "..." },
  { "success": true, "output": "..." },
  { "success": false, "error": "error message" }
]

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

Stop on first error

officecli batch report.docx --input commands.json --stop-on-error

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.
  • If --stop-on-error is not set, all commands execute regardless of individual failures.
  • Returns non-zero exit code when any command fails (even without --stop-on-error).
  • 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.28

Clone this wiki locally