command mark

mark / unmark / get-marks

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.

Synopsis

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]

Description

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

mark — attach a mark

Arguments

Name	Type	Required	Description
file	FileInfo	Yes	Office document path
path	string	Yes	Data-path (e.g., /p[1], /slide[1]/shape[@id=10000]) or selected pseudo-path

Properties

Property	Description
find	Text to highlight within the element (literal or regex). Empty = mark entire element.
regex	Set to true to treat find as regex (alternative to r"..." prefix)
color	CSS color for highlight (e.g., #ffff00, yellow)
note	Free-form annotation text
tofix	Display label for "what should be fixed" (shown in tooltip as find → tofix)

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.

Examples

# 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

unmark — remove marks

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

# Remove all marks
officecli unmark report.docx --all

get-marks — list all marks

# 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-08T01:58:48Z"
    }
  ]
}

Behavior

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

Notes

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

See Also

• 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.64