How to Use CSS-Like Queries with the OfficeCLI Query Command: Boolean Operators Explained

The OfficeCLI query command supports CSS-like selectors where multiple attribute predicates inside brackets imply logical AND, while comma-separated selectors create logical OR unions, enabling complex boolean searches across Word, Excel, and PowerPoint documents.

The iOfficeAI/OfficeCLI repository provides a command-line interface for searching Office documents using a selector language inspired by CSS. Mastering how to use CSS-like queries with boolean operators allows you to precisely filter rows, shapes, paragraphs, and other elements across .docx, .xlsx, and .pptx files without opening the applications.

How the Query Engine Processes Boolean Logic

The selector engine implemented in AttributeFilter.cs evaluates queries by parsing element selectors, attribute predicates, and pseudo-selectors against the OOXML document tree. The CLI entry point in CommandBuilder.GetQuery.cs routes these selectors to format-specific handlers such as WordHandler.Query.cs, ExcelHandler.Query.RowWhere.cs, and PowerPointHandler.Query.cs.

Implicit AND via Attribute Predicates

When you place multiple conditions inside a single pair of brackets, the engine treats them as logical AND operations. Every predicate must evaluate to true for the element to match.

# Rows where Score > 80 AND Year < 2025

officecli query "$FILE" 'row[Score>80 Year<2025]' --json

This syntax corresponds to the AttributeFilter.ParseSelector method, which creates a SelectorPart tree where space-separated predicates within [ ] are combined with conjunction logic.

Explicit OR via Comma Separators

To express OR logic, separate distinct selectors with a comma (,). This creates a union of result sets, similar to CSS group selectors.

# All shapes OR pictures (union of both sets)

officecli query "$FILE" 'shape, picture' --json

The comma operator works across different element types or different attribute constraints, allowing heterogeneous result collections.

Combining AND and OR

You can nest boolean logic by combining bracketed predicates with comma-separated selectors.

# Rows matching (Score>80 AND Year<2025) OR Status="Closed"

officecli query "$FILE" 'row[Score>80 Year<2025], row[Status="Closed"]' --json

This pattern leverages both the implicit AND within brackets and the explicit OR via commas to build complex filter conditions.

Advanced Selector Features

Pseudo-Selectors for Content Filtering

Pseudo-selectors provide additional filtering based on element content rather than attributes. The engine supports :contains("text"), :empty, and :no-alt.

# Paragraphs containing the word "Revenue"

officecli query "$FILE" 'paragraph:contains("Revenue")' --json

# Empty cells OR cells with only whitespace

officecli query "$FILE" 'cell:empty, cell:contains("")' --json

When combined with attribute predicates, pseudo-selectors act as additional AND conditions: cell[formula]:contains("#REF!") matches only cells that have a formula attribute AND contain the text "#REF!".

Hierarchical Relationships

The query language supports CSS-style combinators to navigate document hierarchy:

• Descendant combinator (space): Matches elements at any depth within the ancestor.
• Child combinator (>): Matches only direct children.

# Any shape anywhere inside a slide (deep search)

officecli query "$FILE" 'slide shape' --json

# Direct child shapes only (immediate children)

officecli query "$FILE" 'slide > shape' --json

Regex Matching with ~=

The ~= operator enables regex-style pattern matching within attribute values.

# Cells whose formula contains "SUM" (case-insensitive)

officecli query "$FILE" 'cell[formula~=SUM]' --json

This operator is handled in AttributeFilter.cs alongside standard comparison operators (=, !=, >, <).

Practical Query Examples

Filter Excel Rows by Multiple Criteria

# Numeric comparison with implicit AND

officecli query spreadsheet.xlsx 'row[Score>80 Year<2025 Status="Active"]' --json

Search Word Documents for Specific Content

# Paragraphs containing "Quarterly" that are not empty

officecli query document.docx 'paragraph:contains("Quarterly"):not(:empty)' --json

Target Specific PowerPoint Elements

# Shapes with specific fill color OR pictures without alt text

officecli query presentation.pptx 'shape[fill=1E2761], picture:no-alt' --json

Programmatic Result Counting

# Count matching shapes using JSON output

count=$(officecli query "$FILE" 'shape[fill=1E2761]' --json |
        jq '.data.results | length')
echo "Found $count shapes with the specified fill color"

Summary

• Implicit AND: Multiple predicates inside [ ] brackets require all conditions to be true, as handled by AttributeFilter.cs.
• Explicit OR: Comma-separated selectors (selector1, selector2) create unions of matching elements.
• Pseudo-selectors: :contains(), :empty, and :no-alt filter based on content rather than attributes.
• Combinators: Use > for direct children and space for any descendant in the OOXML hierarchy.
• Regex matching: The ~= operator enables pattern matching within attribute values.
• Case insensitivity: Element names and attribute keys are case-insensitive throughout the parser.

Frequently Asked Questions

How do I combine multiple conditions in a single OfficeCLI query?

Separate multiple attribute predicates with spaces inside a single bracket pair to imply logical AND. For example, row[Score>80 Year<2025] matches only rows where both conditions are true simultaneously. For logical OR, use comma-separated selectors like row[Score>80], row[Status="Pending"].

What is the difference between space and comma in OfficeCLI selectors?

A space between element names indicates a descendant relationship (the second element can be anywhere inside the first), while a comma separates independent selectors and combines their results with OR logic. For example, slide shape finds shapes nested anywhere within slides, whereas shape, picture returns all shapes and all pictures regardless of hierarchy.

Can I use regex patterns in OfficeCLI query attributes?

Yes, the ~= operator enables regex-style matching within attribute values. For example, cell[formula~=SUM] matches cells where the formula attribute contains the substring "SUM". This is implemented in AttributeFilter.cs alongside standard comparison operators.

Which Office document types support the CSS-like query command?

The query command supports Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) files through dedicated handlers: WordHandler.Query.cs, ExcelHandler.Query.RowWhere.cs, and PowerPointHandler.Query.cs. Each handler maps the generic CSS-like selectors to format-specific OOXML elements such as paragraphs, rows, or slides.

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