Usage

Usage

Sync source: src/plugin/tools/officecli.ts (tool schemas — the single source of truth for this page), README.md, docs/WORKFLOWS.md

The plugin registers two tools: officecli (single tool, action-based) and edit (overrides the built-in edit for draft routing).

Core lifecycle

create / edit / revert → [draft] → accept → real file written
                          ↖ undo (discard draft, release lock)

• create / edit never write the real file. They create or update a draft under the data dir and acquire the file lock (lazy acquire).
• accept is the single write path: flushes the draft to disk, records an accept-point in history, releases the lock.
• Binary files (.png, .pdf, .docx, .xlsx, .pptx, …): the edit override rejects them with "use officecli for binary files". Use officecli instead.

Action reference

All calls: officecli(action="...", filePath="..."). Array/object parameters are JSON strings (the tool schema takes strings and the code JSON.parses them).

Action	Extra params	What it does
create	content (required); filePath or filePaths	Create a new draft (no real file written). filePaths: JSON array → one draft per path.
edit	content (required, non-empty)	Update the current session's draft; acquires lock if needed.
accept	filePath or filePaths; timestamp?	Write draft → real file, record history, release lock. Batch mode is all-or-nothing.
undo	—	Discard the draft, release the lock.
revert	timestamp (accept-point from history)	Create a draft from that snapshot; still needs accept to write.
history	—	Returns [{timestamp, sessionID}] accept-points for the file.
list	filePath?	List active drafts across files (lock status, orphaned flag, age).
diff	—	Unified markdown diff: draft vs real file. Review before accept.
generate	templatePath + (data + filePath or dataArray + filePaths)	Substitute {{var}} placeholders in a Template; creates one draft per data entry. Missing keys → error listing them. data/dataArray/filePaths are JSON strings; dataArray and filePaths must be equal-length arrays.
preview	—	Render draft (or real file) to HTML via pandoc; returns output path.
validate	rules (JSON string, e.g. {"required":[...],"patterns":[...]})	Run content rules against the draft; returns per-rule pass/fail report.
lock-status	—	Lock details: sessionID, owner, status, stale, touchedAt.
force-release	—	Take over a lock. Only allowed when the lock is stale; fresh foreign locks are rejected.
export	targetPath (must differ from source)	Convert to a derived file (pdf/docx/xlsx/pptx) outside the write path. Text content is preserved; layout is approximate.
metadata	properties? (JSON string)	With properties: write pending values to the draft sidecar. Without: read merged metadata (real file + sidecar).
watermark	text; position?; size?; opacity?	DOCX/PDF watermark via sidecar. Empty text clears it.
annotate	annotations (JSON string of overlay ops)	Image overlays: note / highlight / stamp (DRAFT, APPROVED, CONFIDENTIAL). annotations: "[]" clears.
comment	commentId, author, commentText; anchor: range (DOCX) / cellRef (XLSX) / slide,x,y (PPTX); suggestedText?	Add a comment to the draft. With suggestedText it becomes an approvable suggestion.
approve	commentId	Apply the suggestion's suggestedText into the draft and remove the comment. Fails if the comment has no suggestedText.
track-insert / track-delete	commentId, author, content, paragraph, offset	DOCX-only native track changes. Errors on XLSX/PPTX — use comment with suggestedText there.
list-comments	—	List comments in the draft or real file.
review	—	Summary of all comments (+ track changes for DOCX).

edit override

Registered as a plugin tool named edit (replaces the built-in). Signature: {filePath, oldString, newString}.

• Text files: routed into the plugin draft lifecycle transparently — the agent just "edits".
• Binary files: rejected, with the instruction to use officecli.

Common workflows

Simple create → review → accept

officecli(action="create", filePath="./report.docx", content="# Report...")
officecli(action="diff", filePath="./report.docx")
officecli(action="accept", filePath="./report.docx")

Read a document

officecli(action="read", filePath="./invoice.pdf")   # returns markdown

Batch generation from a template

Template = any file containing {{var}} placeholders (agent creates it with create + accept first):

officecli(action="generate",
  templatePath="./templates/decision-template.md",
  filePaths='["./decisions/a.docx", "./decisions/b.docx"]',
  dataArray='[{"DEPT": "Microbiology", "AMOUNT": 10000}, {"DEPT": "Radiology", "AMOUNT": 20000}]')
officecli(action="accept", filePaths='["./decisions/a.docx", "./decisions/b.docx"]')

History and revert

officecli(action="history", filePath="./budget.docx")   # → [{timestamp, sessionID}]
officecli(action="revert", filePath="./budget.docx", timestamp=1234567890)
officecli(action="accept", filePath="./budget.docx")

Locks (multi-session)

• Locks are per-file claims; acquired lazily on the first mutating call by the session.
• Another session's active lock → mutating calls fail with the owning session ID.
• Check with lock-status; take over a stale lock with force-release (stale threshold is configurable, default 24h).
• A session displaced by force-release gets an error on its next mutating call; its draft becomes an orphan.

Format conversion

officecli(action="export", filePath="./report.docx", targetPath="./report.pdf")

Conversion goes through the markdown pipeline: content is preserved, exact layout is not. For layout-sensitive output, generate the target format directly instead.

Errors

• Real failures are thrown as typed Tool.Error — the tool call simply fails with the message.
• Informational results (e.g. "no lock on X") are returned as normal output, not errors.
• generate fails fast: bad JSON, mismatched array lengths, or missing template keys are all errors; nothing is silently left empty.