OfficeCLI Query Command with CSS‑like Selectors: A Complete Guide

OfficeCLI's query command accepts CSS‑like selector strings to target slides, shapes, paragraphs, tables, and other document elements without writing raw XML.

The query command sits at the heart of OfficeCLI's L2 DOM layer—the intermediate abstraction that transforms complex Office documents into navigable object trees. Instead of manipulating OOXML directly, you write intuitive selectors that mirror web CSS syntax. This guide covers the full selector grammar, practical examples, and how to chain queries into automated document workflows.

---

How the OfficeCLI Query Command Works

The query command evaluates selector strings against a document's internal DOM structure. It returns matching elements as structured JSON (with --json) or human‑readable lists, providing stable paths like /slide[2]/shape[1] that subsequent commands can reuse.

In the OfficeCLI architecture, query belongs to the L2 layer as defined in [README.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md#L445). This positioning means it integrates cleanly with other DOM commands: set, add, and remove can all consume query output for read‑modify‑write operations ▶️ command reference.

Three‑Step Workflow

1. Select elements using a CSS‑like selector.
2. Inspect the returned JSON for paths and attributes.
3. Chain mutations via set, remove, or move using discovered paths.

---

CSS‑like Selector Syntax in OfficeCLI

OfficeCLI's selector engine adapts familiar CSS concepts to document structures. The parser implementation lives in the C# source under src/OfficeCLI/Selectors/.

Feature	Syntax	Example	Matches
Element type	slide, shape, paragraph, row, cell, table, run	slide	Any slide element
Attribute equality	[attr=value]	shape[name=Title]	Shapes with name exactly "Title"
Attribute comparison	[attr>value], [attr<value], etc.	row[Salary>5000]	Rows where column Salary exceeds 5000
Multiple attributes	[attr1=val1][attr2=val2]	cell[row=3][col=A]	Cell at row 3, column A
Contains text	:contains(text)	run:contains(TODO)	Text runs containing "TODO"
Logical AND	attr1 and attr2	shape[fill=FF0000] and paragraph[style=Heading1]	Red shapes and Heading 1 paragraphs
Negation	:not(selector)	:not(shape[fill=FF0000])	Everything except red‑filled shapes
Descendant combinator	ancestor descendant	slide shape	Any shape inside any slide
Child combinator	parent > child	slide > shape	Direct‑child shapes of slides only
Grouping (OR)	selector1, selector2	slide, table	All slides or all tables

---

Practical Query Command Examples

Find Shapes by Fill Color in PowerPoint

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"}}
]

The path values are stable references. Use them with set or remove without re‑querying.

Filter Excel Rows by Numeric Column Value

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 Paragraphs Containing Specific 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"}}
]

This combines attribute selection with the :contains() pseudo‑selector for precise text matching.

Combine Multiple Selectors with OR Logic

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"}}
]

The comma operator creates a union of results from both selector expressions.

---

Chaining Query Results into Document Mutations

The --json output enables pipeline workflows. Extract paths with jq, then feed them to set:

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

This pattern—query → extract paths → mutate—supports fully automated document processing without human inspection.

---

Selector Engine Implementation Details

The CSS‑like parser is implemented in C# within src/OfficeCLI/Selectors/. Key architectural decisions:

• Deterministic path generation: Every matched element receives an unambiguous path string.
• Type‑aware attribute comparison: Numeric comparisons (>, <, >=, <=) coerce values appropriately.
• Office‑specific element types: The element vocabulary (slide, shape, run, row, cell) maps directly to OOXML concepts without exposing XML complexity.

For edge‑case behavior and grammar specifics, see the command‑query Wiki page.

---

Integration with AI Agents

OfficeCLI publishes a SKILL.md file that instructs AI systems on query invocation. Because selectors are deterministic and paths are stable, agents can:

• Navigate documents without parsing OOXML schemas.
• Generate selectors from user intent ("find all red urgent shapes").
• Compose multi‑step workflows using verified path outputs.

The skill definition is available at [SKILL.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md).

---

Summary

• OfficeCLI query uses CSS‑like selectors to target document elements without XML manipulation.
• Selector syntax includes element types, attribute filters, comparisons, combinators, and pseudo‑selectors.
• Stable paths in JSON output enable reliable chaining with set, remove, and other DOM commands.
• Pipeline workflows combine query, jq, and xargs for fully automated document processing.
• AI agent support via SKILL.md makes query ideal for programmatic document manipulation.

---

Frequently Asked Questions

What Office document formats does the query command support?

OfficeCLI query works with PowerPoint (.pptx), Excel (.xlsx), and Word (.docx) files. The element type vocabulary adapts per format—slide and shape for presentations, row and cell for spreadsheets, paragraph and run for documents.

How does OfficeCLI handle attribute values with spaces or special characters?

Use standard CSS escaping or quote the entire selector string in your shell. For complex values, the command‑query Wiki page documents the exact escape sequences supported by the C# parser in src/OfficeCLI/Selectors/.

Can I use regular expressions in selectors?

The core selector engine does not support regex patterns. Use :contains() for substring matching, or chain query output with external tools like jq for pattern filtering. For regex needs, pipe JSON results to a script that applies additional filtering.

Is the query command available in the latest stable release?

Yes. query is a core L2 command documented in [README.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md#L518). Install or update via the standard OfficeCLI distribution channels listed in the repository's installation instructions.

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