How to Use the Query Command in OfficeCLI with CSS-like Selectors

The query command in OfficeCLI enables precise targeting of document elements—slides, shapes, table rows, and text runs—using CSS-like selector strings that return stable, canonical paths for automation workflows.

OfficeCLI is an open-source command-line tool for manipulating Office documents without directly parsing OOXML. The query command operates within the tool's L2 DOM layer, providing a middle-tier abstraction that translates CSS-like selectors into specific element references for PowerPoint, Excel, and Word files.

Understanding CSS-like Selector Syntax

The selector engine implemented in src/OfficeCLI/Selectors/ (C# source) adapts standard web CSS syntax to Office document hierarchies. The language supports element types, attribute filters, combinators, and logical operators.

Element Type Selection

Target structural components using Office-specific tag names:

• slide – Matches any slide in a presentation deck
• shape – Matches drawing objects, text boxes, or placeholders
• table – Matches table structures in Excel or Word
• row – Matches table rows (supports attribute filters for column values)
• cell – Matches individual table cells
• paragraph – Matches text blocks in Word documents
• run – Matches text runs within paragraphs

Attribute Filters and Comparisons

Refine selections using bracket notation with equality or comparison operators:

• Equality matching: shape[name=Title] matches shapes where the name attribute equals "Title"
• Numeric comparison: row[Salary>5000] matches rows where the Salary column exceeds 5000
• Multiple attributes: cell[row=3][col=A] matches the cell at row 3, column A
• Content filtering: run:contains(TODO) matches text runs containing the substring "TODO"

Combinators and Logical Operators

Navigate document hierarchies and combine conditions:

• Descendant combinator (space): slide shape matches any shape nested at any depth within a slide
• Child combinator (>): slide > shape matches only direct children of the parent element
• Grouping (,): slide, table matches all slides or all tables
• Logical AND: shape[fill=FF0000] and paragraph[style=Heading1] matches elements satisfying both conditions simultaneously
• Negation (:not()): :not(shape[fill=FF0000]) excludes elements matching the inner selector

Practical Query Examples

Execute queries against Office documents using the officecli query <file> "<selector>" --json pattern. The JSON output includes each element's tag, stable path, and attribute dictionary.

Find Shapes by Color in PowerPoint

Locate all shapes with a specific fill color:

officecli query deck.pptx "shape[fill=FF0000]" --json

[
  {"tag":"shape","path":"/slide[1]/shape[3]","attributes":{"fill":"FF0000","text":"Urgent"}},
  {"tag":"shape","path":"/slide[4]/shape[1]","attributes":{"fill":"FF0000","text":"Alert"}}
]

Filter Excel Rows by Numeric Threshold

Extract rows where specific column values meet criteria:

officecli query budget.xlsx "row[Salary>5000]" --json

[
  {"tag":"row","path":"/Sheet1/row[12]","attributes":{"Salary":"7200","Name":"Alice"}},
  {"tag":"row","path":"/Sheet1/row[45]","attributes":{"Salary":"9500","Name":"Bob"}}
]

Locate Styled Text Patterns in Word

Find paragraphs with specific styles containing target text:

officecli query report.docx "paragraph[style=Heading1]:contains(Summary)" --json

[
  {"tag":"paragraph","path":"/body/p[7]","attributes":{"style":"Heading1","text":"Executive Summary"}},
  {"tag":"paragraph","path":"/body/p[22]","attributes":{"style":"Heading1","text":"Summary of Findings"}}
]

Combine Multiple Conditions

Use grouping and logical operators for complex selections:

officecli query deck.pptx "shape[fill=FF0000], table[col>5]" --json

[
  {"tag":"shape","path":"/slide[2]/shape[5]","attributes":{"fill":"FF0000"}},
  {"tag":"table","path":"/slide[3]/table[1]","attributes":{"colCount":"7"}}
]

Chaining Queries with DOM Commands

The query command returns stable canonical paths (e.g., /slide[2]/shape[1]) that remain consistent across read-modify-write cycles. According to the OfficeCLI architecture documented in README.md (line 518), these paths enable reliable navigation without parsing raw OOXML.

Pipe query results to other L2 DOM commands (set, remove, add) for automated mutations:

officecli query deck.pptx "shape[fill=FF0000]" --json \
  | jq -r '.[].path' \
  | xargs -I{} officecli set deck.pptx {} --prop title="Priority"

This workflow selects red-filled shapes, extracts their paths using jq, and passes each path to the set command to update the title property.

Implementation and Documentation References

The selector grammar and command implementation are maintained in specific repository locations:

• src/OfficeCLI/Selectors/ – C# implementation of the CSS-like parser and DOM traversal engine

• README.md – Documents the L1-L3 architecture and command references (line 445-518)

• Command-query Wiki – Complete selector grammar specification, edge-case handling, and advanced examples

• SKILL.md – Integration patterns for AI agents using the query command in automated workflows

Summary

• The query command operates in OfficeCLI's L2 DOM layer, abstracting OOXML complexity behind familiar CSS-like syntax.
• Selectors support element types, attribute comparisons (including numeric >, <, =), hierarchical combinators (descendant and child), and logical operators (AND, OR, NOT).
• Commands return stable canonical paths that enable reliable chaining with set, add, and remove operations.
• The parser implementation lives in src/OfficeCLI/Selectors/ and handles PowerPoint (.pptx), Excel (.xlsx), and Word (.docx) document trees uniformly.
• Use --json output to pipe results into jq or other CLI tools for shell-based automation scripts.

Frequently Asked Questions

What file formats does the OfficeCLI query command support?

The query command supports PowerPoint (.pptx), Excel (.xlsx), and Word (.docx) formats through the same unified selector interface. The underlying engine in src/OfficeCLI/Selectors/ adapts the CSS-like syntax to each format's specific DOM structure—slides and shapes for PowerPoint, rows and cells for Excel, and paragraphs and runs for Word.

How do I escape special characters in attribute values?

When attribute values contain spaces or special characters, wrap the entire selector string in double quotes and use standard CSS escaping. For example: shape[name="Main Title"] or paragraph:contains("Q1 Results"). The parser handles quoted strings according to the grammar specification in the command-query Wiki.

Can I use regular expressions in selectors?

Currently, the selector engine supports exact string matching, numeric comparisons (>, <, >=, <=), and the :contains() pseudo-class for substring matching. Full regular expression support is not implemented in the C# parser; pipe the JSON output to jq and apply regex filters there for complex pattern matching.

What is the difference between the space combinator and the > combinator?

The space (descendant) combinator in slide shape matches shapes at any depth within a slide, including those nested inside groups. The child combinator (>) in slide > shape matches only direct children of the parent element, excluding nested descendants. This mirrors standard CSS behavior as implemented in the OfficeCLI selector evaluation engine.

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