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

> Master the OfficeCLI query command with CSS-like selectors to precisely target elements like slides shapes and text for automation. Get stable canonical paths.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-08-07

---

**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:

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

```

```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:

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

```

```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:

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

```

```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:

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

```

```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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md)** – Documents the L1-L3 architecture and command references (line 445-518)
- **[Command-query Wiki](https://github.com/iOfficeAI/OfficeCLI/wiki/command-query)** – Complete selector grammar specification, edge-case handling, and advanced examples
- **[`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.