How to Use OfficeCLI Mark and Goto Commands for Navigation in Large Documents

The OfficeCLI mark and goto commands let you annotate specific elements in Word, Excel, or PowerPoint documents with advisory marks and instantly jump to those locations in the live watch viewer, enabling efficient navigation through massive files without modifying the original document.

The iOfficeAI/OfficeCLI tool transforms Office files into HTML for browser-based viewing through a live watch process. When working with lengthy reports, presentations, or spreadsheets, manually scrolling to specific paragraphs, tables, or cells becomes impractical. The mark and goto commands solve this by creating a runtime navigation layer that operates exclusively through named pipe communication with the watch server.

What Are the Mark and Goto Commands?

The mark command attaches advisory metadata to document elements such as paragraphs, table cells, or rows. These marks exist only in the watch server's memory and can include properties like colors, notes, or fix flags. The goto command then scrolls the live viewer to any element identified by its DOM-style path or previous mark.

Unlike editing commands that modify the .docx, .pptx, or .xlsx source files, these navigation commands are non-destructive and function only while the watch process is active. They communicate via the same named pipe infrastructure used for live document refreshes.

How the Mark and Goto Commands Work

Command Parsing and Request Building

In src/officecli/CommandBuilder.Mark.cs, the CLI parses --prop options to build a MarkRequest object that gets forwarded to WatchNotifier.AddMark. Similarly, CommandBuilder.Goto.cs handles the path argument and invokes WatchNotifier.TryScroll to execute the scroll action.

The mark command supports the special selected pseudo-path, which queries the watch server for currently highlighted elements via WatchNotifier.QuerySelection. This allows batch marking of multiple items without manually enumerating each path.

Path Resolution and Selector Conversion

OfficeCLI accepts element paths following DOM-style syntax such as /body/p[5] or /body/table[2]/tr[3]/tc[1]. The pipeline processes these through several stages:

1. Path normalization: MsysPathHint.Restore in OfficeCli.Core decodes any encoded characters in the path string.
2. Selector generation: WatchMessage.ExtractWordScrollTarget (located within WatchNotifier.cs) converts Word-specific paths into CSS selectors like #w-p-5 or [data-path="/body/table[2]/tr[3]"] that the browser viewer understands.

Inter-Process Communication via Named Pipes

The WatchNotifier class in src/officecli/Core/Watch/WatchNotifier.cs manages all communication with the watch server:

• Marking: The AddMark method serializes the MarkRequest to JSON and writes "mark <json>" to the named pipe returned by WatchServer.GetWatchPipeName(filePath). The server validates the request, assigns a unique ID, and returns a MarkResponse.
• Scrolling: The TryScroll method sends "scroll <selector>" to the pipe and expects either an "ok" confirmation or an "err:<msg>" response. If the selector does not exist in the cached HTML, the command exits with code 1 and surfaces the error to the CLI.

Both commands support a --json flag for machine-readable output, making them suitable for integration with AI agents and automation scripts.

Practical Examples for Document Navigation

Marking Individual Elements with Metadata

To flag a specific paragraph for review with an orange highlight and descriptive note:

officecli mark myReport.docx /body/p[12] --prop color=orange --prop note="Check figures"

The CLI outputs the assigned mark ID:

Marked /body/p[12] (id=9a7c3d)

For table cells, specify the full path including row and cell indices:

officecli mark myReport.docx /body/table[3]/tr[2]/tc[5] \
    --prop tofix="incorrect subtotal" --prop color=red

Marking Current Selections in Bulk

When you have highlighted multiple rows or paragraphs in the browser viewer, mark them simultaneously using the selected keyword:

officecli mark myReport.docx selected --prop note="Review after meeting"

This executes WatchNotifier.QuerySelection to retrieve the current selection from the watch server and creates individual marks for each selected element.

Jumping to Specific Elements

After marking paragraph 12 (path /body/p[12]), scroll directly to that location:

officecli goto myReport.docx /body/p[12]

Output confirms the scroll action:

Scrolled watcher(s) to /body/p[12] (#w-p-12)

If the path does not exist, the command fails with exit code 1:

officecli goto myReport.docx /body/p[999]

Cannot scroll to '/body/p[999]': selector not found in cached HTML.

Scripting Workflows with Mark and Goto

Combine both commands in shell scripts for automated review workflows:

#!/usr/bin/env bash
FILE=bigPresentation.pptx
PATH=/body/p[150]

# Highlight the critical slide

officecli mark "$FILE" "$PATH" --prop color=yellow --prop note="Key KPI slide"

# Immediately navigate there for review

officecli goto "$FILE" "$PATH"

The script fails safely if the watch server is not running, as mark will report "No watch process is running…" and exit with code 1, preventing the subsequent goto from executing.

Navigation Strategies for Large Documents

• Batch marking similar items: Select multiple elements in the browser (e.g., all table rows containing "TODO"), then run officecli mark myDoc.docx selected --prop tofix=TODO to flag them simultaneously without typing individual paths.

• Navigating between marks: Run officecli get-marks --json to retrieve all current marks with their IDs and paths, then use goto with specific paths to cycle through flagged sections.

• Preventing stale scroll targets: Always ensure the watch process reflects the latest document version by running officecli refresh myDoc.docx before using goto, as scroll selectors depend on the current HTML cache.

• Automation with JSON output: Pipe get-marks results through jq to extract paths dynamically, then feed them to goto in loops for systematic document review.

Summary

• The mark command creates runtime annotations on document elements using paths like /body/p[5] or the selected pseudo-path, storing color, note, and fix metadata via WatchNotifier.AddMark.
• The goto command scrolls the live viewer to any element using CSS selectors generated by WatchMessage.ExtractWordScrollTarget, failing with exit code 1 if the target is missing.
• Both commands communicate through named pipes defined in WatchNotifier.cs and support --json output for script integration.
• These tools enable non-destructive navigation in massive Word, Excel, and PowerPoint files without altering the original document content.

Frequently Asked Questions

Do the mark and goto commands modify the original Office file?

No. These commands operate exclusively at runtime through the watch server's named pipe. They create advisory marks in memory and scroll the HTML viewer, but never write changes back to the .docx, .pptx, or .xlsx source files.

What happens if I try to goto a path that doesn't exist?

The goto command exits with code 1 and prints an error message such as "selector not found in cached HTML." This occurs when the path has changed due to document edits or if the indices in your path argument are incorrect.

Can I use mark and goto without the watch server running?

No. Both commands require an active watch process because they depend on the named pipe connection managed by WatchServer.GetWatchPipeName. If the server is not running, mark returns "No watch process is running…" and exits with code 1, while goto will similarly fail.

How do I find the correct element path for goto?

You can discover valid paths by first using officecli mark with the selected option after clicking elements in the browser viewer, then retrieving the paths via officecli get-marks. Alternatively, the watch viewer's developer tools can reveal the data-path attributes on HTML elements, which correspond directly to the path syntax used by these commands.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}