# How to Use the OfficeCLI `query` Command to Search and Filter Elements Within Documents

> Master the OfficeCLI query command to efficiently search and filter elements in Word Excel and PowerPoint documents Use CSS-like selectors for powerful data extraction and formatting

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

---

**The OfficeCLI `query` command uses CSS-like selectors to search and filter elements in Word, Excel, and PowerPoint documents, with support for attribute filtering, text matching, JSON output, and compact text formats.**

The `query` command is a read-only operation designed for probing Office documents programmatically. Whether you're automating document inspection, extracting data for reporting, or building CI/CD pipelines, this command provides a fast, script-friendly interface to enumerate and filter document elements. This article explains how the `query` command works according to the iOfficeAI/OfficeCLI source code, with practical examples for every supported scenario.

## How the `query` Command Works

### Command Registration and CLI Options

The `query` verb is defined in [`src/officecli/CommandBuilder.GetQuery.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.GetQuery.cs). This file builds the command structure and parses options including `--find`, `--compact`, `--fields`, and `--json`.

When executed, the command creates a `ResidentRequest` with `Command = "query"` and sends it to the resident server if one is running. Otherwise, it opens the file directly.

```bash
officecli mydoc.docx query "paragraph" --json

```

### Resident Server Handling

In [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs), the resident server receives the request through a command-dispatch switch (case `"query"`). It forwards the request to the appropriate `IDocumentHandler.Query` implementation—`WordHandler`, `PowerPointHandler`, or `ExcelHandler` depending on file type.

The handler returns a list of `DocumentNode` objects matching your selector.

### Selector Processing with AttributeFilter

The core selector engine lives in [`src/officecli/Core/AttributeFilter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/AttributeFilter.cs). The `FilterSelector` method parses CSS-like syntax and supports:

- **Logical operators**: `and`, `or`, `not`
- **Attribute comparisons**: `=`, `!=`, `>`, `<`
- **Excel shorthand aliases**: `bold` expands to `font.bold`

The filter returns matching nodes plus any warnings for malformed selectors or unsupported properties.

## CSS-Like Selector Syntax

### Basic Element Selection

Select all elements of a given type using the element name.

```bash

# All paragraphs in a Word document

officecli mydoc.docx query "paragraph"

# All shapes in a PowerPoint presentation

officecli mydoc.pptx query "shape"

# All cells in an Excel workbook

officecli mydoc.xlsx query "cell"

```

### Attribute Filtering

Filter elements by attributes using bracket notation.

```bash

# Headings with style "Heading1"

officecli mydoc.docx query "paragraph[style=Heading1]"

# Runs not using Arial font

officecli mydoc.docx query "run[font!=Arial]"

# Cells with width greater than 100

officecli myfile.xlsx query "cell[width>100]"

```

### Logical Operators

Combine conditions with `and`, `or`, and `not`.

```bash

# Paragraphs that are Heading1 OR Heading2

officecli mydoc.docx query "paragraph[style=Heading1 or style=Heading2]"

# Bold runs NOT in Arial

officecli mydoc.docx query "run[font.bold=true and font.not(Arial)]"

```

## Text Search with the `--find` Flag

The `--find` option provides case-insensitive substring matching on displayed text. This filtering happens **after** the selector engine returns its raw matches.

```bash

# Find paragraphs containing "Budget" (case-insensitive)

officecli mydoc.docx query "paragraph" --find "budget"

# Combine selector filtering with text search

officecli mydoc.docx query "paragraph[style=Heading1]" --find "executive summary"

```

## Output Formats

### JSON Output (`--json`)

Use `--json` for machine-readable output suitable for programmatic processing. The implementation in [`CommandBuilder.GetQuery.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.GetQuery.cs) (lines 28-34) hydrates child nodes on-the-fly using `handler.Get(path, depth: 1)`, ensuring the JSON structure matches a normal `get --json` response.

```bash

# Get all bold cells as JSON

officecli mydoc.xlsx query "cell[font.bold=true]" --json

```

```json
{
  "nodes": [
    {
      "type": "cell",
      "path": "/sheet1/row5/cell2",
      "text": "Total Revenue",
      "format": {
        "font.bold": true,
        "fill.color": "#FFFFFF"
      }
    }
  ],
  "total": 1
}

```

### Compact Text Output (`--compact`)

The `--compact` flag produces a stable, line-oriented text format defined in [`CommandBuilder.GetQuery.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.GetQuery.cs) (lines 81-95). This format is a **stability contract** with fixed column order, TAB separators, truncation marker `…`, and a final `total:` line—ideal for piping to other tools.

```bash

# Compact output for easy parsing

officecli mydoc.docx query "shape" --compact

```

```

shape	/ppt/slide3/shape2	Text Box...		total: 1

```

### Adding Custom Fields (`--fields`)

Append extra attributes to compact output with the `--fields` option. The implementation looks up each field in the node's `Format` dictionary (lines 61-65).

```bash

# Include position and size data

officecli mydoc.pptx query "shape" --compact --fields x,y,width,height

```

```

shape	/ppt/slide1/shape1	Title		x=100	y=200	width=400	height=50	total: 1

```

## Performance: Using the Resident Server

For repeated queries against the same document, start a resident server to eliminate file-open overhead.

```bash

# Start resident server (keeps file open in memory)

officecli open mydoc.docx

# Subsequent queries use the resident automatically

officecli query mydoc.docx "table"
officecli query mydoc.docx "paragraph[style=Heading1]" --json
officecli query mydoc.docx "shape" --find "diagram" --compact

```

The resident path is handled in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) at lines 94-100, with proper exit code propagation for both success and failure cases.

## Error Handling and Exit Codes

Malformed selectors or unsupported properties trigger warnings on **stderr** and a non-zero exit code. This applies consistently whether using the resident server or direct file access.

```bash
officecli mydoc.docx query "invalid[property//syntax]"  # exits non-zero with warning

```

## Summary

- **Primary interface**: CSS-like selectors processed by `AttributeFilter.FilterSelector` in [`src/officecli/Core/AttributeFilter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/AttributeFilter.cs)
- **Command definition**: [`src/officecli/CommandBuilder.GetQuery.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.GetQuery.cs) with options `--find`, `--compact`, `--fields`, `--json`
- **Resident acceleration**: [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) dispatches to `IDocumentHandler.Query` implementations
- **Output formats**: JSON for machines, compact text for scripts (stability contract with TAB separators)
- **Performance**: Use `officecli open` to enable resident server for repeated queries

## Frequently Asked Questions

### What file types does the `query` command support?

OfficeCLI supports **Word (.docx)**, **Excel (.xlsx)**, and **PowerPoint (.pptx)** files through their respective handlers: `WordHandler`, `ExcelHandler`, and `PowerPointHandler`. Each handler implements `IDocumentHandler.Query` to provide document-specific element enumeration.

### How do I filter elements by their visible text content?

Use the **`-f/--find <text>`** flag. This performs case-insensitive substring matching after the selector engine returns matches. For example: `officecli doc.docx query "paragraph" --find "confidential"` finds all paragraphs containing "confidential" regardless of case.

### What's the difference between `--json` and `--compact` output?

**`--json`** produces hierarchical, machine-readable output with full node metadata including children. **`--compact`** produces a stable, line-oriented text format with TAB-separated columns—designed for Unix-style piping and guaranteed not to change between versions. Add **`--fields`** to append custom attributes to compact output.

### Can I use the `query` command in a CI/CD pipeline?

Yes. The command returns **non-zero exit codes** on failure (malformed selectors, file errors) and writes warnings to **stderr**, making it suitable for automated workflows. The **`--compact`** format's stability contract ensures your parsing logic won't break with updates.