# OfficeCLI Query Command with CSS‑like Selectors: A Complete Guide > Master the OfficeCLI query command using CSS-like selectors to target document elements like slides, shapes, and tables. Simplify your automation tasks with this powerful guide. - Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI) - Tags: how-to-guide - Published: 2026-08-04 --- **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)](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](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md#L518). ### 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]`, `[attr5000]` | 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 ```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"}} ] ``` The `path` values are stable references. Use them with `set` or `remove` without re‑querying. ### Filter Excel Rows by Numeric Column Value ```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 Paragraphs Containing Specific 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"}} ] ``` This combines **attribute selection** with the **`:contains()`** pseudo‑selector for precise text matching. ### Combine Multiple Selectors with OR Logic ```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"}} ] ``` 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`: ```bash 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](https://github.com/iOfficeAI/OfficeCLI/wiki/command-query). --- ## Integration with AI Agents OfficeCLI publishes a [`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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)](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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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](https://github.com/iOfficeAI/OfficeCLI/wiki/command-query) 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)](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.