Attach advisory annotations to document elements for review and agent workflows. Marks are tracked by the watch server and rendered live in the browser preview.

officecli mark <file> <path> [--prop find=... color=... note=... tofix=... regex=true]
officecli mark <file> selected [--prop ...]
officecli unmark <file> --path <p>
officecli unmark <file> --all
officecli get-marks <file> [--json]

Marks are live annotations attached to document elements, visible in the browser preview served by watch. They are stored in memory by the watch process and broadcast to all connected clients via SSE.

Common use cases:

• Human → AI review: Highlight sections that need AI attention with a tofix note
• AI → Human verification: Mark auto-generated content for human review
• Two-phase commit: Propose changes via marks, review in browser, apply via set selected

Marks require an active watch process: officecli watch <file>.

Path format: Marks use browser-side data-paths. PowerPoint emits /slide[N]/shape[@id=X] and Word emits /p[N] / /table[N] as the data-path attribute. Use get <file> selected to discover paths of currently-selected elements.

# Mark an entire paragraph with a note
officecli mark report.docx /p[3] --prop color=yellow --prop note="Review this section"
# Highlight specific text within a paragraph
officecli mark report.docx /p[3] --prop find="quarterly growth" --prop color=yellow --prop tofix="Verify latest Q1 data"
# Regex mark
officecli mark report.docx /p[3] --prop 'find=\d+%' --prop regex=true --prop color=pink
# Mark currently-selected elements in the watch browser
officecli mark report.docx selected --prop color=yellow --prop tofix="Needs rewording"
# JSON output returns mark ID and metadata
officecli mark report.docx /slide[1]/shape[@id=10000] --prop color=yellow --json

# Remove marks on a specific path
officecli unmark report.docx --path /p[3]
# Remove all marks
officecli unmark report.docx --all

# Text table output
officecli get-marks report.docx
# JSON output with version and full mark data
officecli get-marks report.docx --json

Text output format:

id path find matched color note
-------------------------- --------------------------- --------------- -------- -------- ----
mark_1712345678001_0 /p[1] hello hello #ffff00 Review
mark_1712345678002_1 /slide[1]/shape[@id=10000] r"\d+%" [25%](3) #ff00ff -

JSON output format:

{
 "version": 2,
 "marks": [
 {
 "id": "mark_1712345678001_0",
 "path": "/p[1]",
 "find": "hello",
 "color": "#ffff00",
 "note": "Review",
 "tofix": "Add context",
 "matched_text": ["hello"],
 "stale": false,
 "created_at": "2026年04月08日T01:58:48Z"
 }
 ]
}

• Live rendering: Marks are visually applied to the browser preview via CSS classes and SSE broadcasts. New connections receive the full mark state.
• Stale detection: Marks are flagged stale: true when the path no longer exists or the find text has no matches. Stale marks are rendered with a dashed outline.
• Two-phase commit: Use mark to propose changes → review in browser → apply with set <file> selected → unmark when done.
• Watch required: All mark commands require an active watch process. Returns an error otherwise.

• Mark paths use the browser data-path format, not handler query paths like /body/p[@paraId=X].
• tofix replaces the old expect property (deprecated but still accepted with a warning).
• Unknown properties trigger a deprecation warning and are ignored.

• watch - Live browser preview required for marks
• get selected - Query currently-selected elements
• set selected - Apply changes to selected elements

Based on OfficeCLI v1.0.43