How to Perform Virtual Column Operations on Word Tables with OfficeCLI

OfficeCLI manipulates Word document tables through virtual column operations that modify the underlying OOXML <w:tblGrid> structure, providing high-level commands to add, remove, move, and copy columns while automatically handling grid spans and width calculations.

OfficeCLI is an open-source command-line interface for automating Microsoft Office document manipulation. When working with Word tables, the tool performs virtual column operations that abstract away the complexity of the Office Open XML (OOXML) format, allowing developers to restructure tables using intuitive commands rather than manually editing raw XML. Because Word stores column definitions in the <w:tblGrid> element rather than as discrete objects, OfficeCLI calculates the correct grid positions and updates related bookmarks automatically.

Understanding the Virtual Column Architecture

Word tables do not contain explicit column objects in their OOXML representation. Instead, columns are defined by <w:gridCol> entries within the <w:tblGrid> element, and cells reference these positions via grid spans. OfficeCLI's virtual column operations translate high-level commands into precise grid manipulations.

The core parsing logic resides in WordHandler.Navigation.cs, where commands such as add column, remove column, move column, and copy column are interpreted into structural changes on the table grid. When modifying columns, the CLI writes canonical keys—including columns, columnSpace, columns.equalWidth, and columns.separator—back to the document metadata so subsequent queries reflect the current structure.

Adding a Column to a Word Table

To insert a new column, OfficeCLI creates a virtual column entry and updates the table's grid definition. The parser detects when <w:col> does not exist in the target location and generates the appropriate OOXML elements.

Execute the following command to add a column after the second existing column with a custom width measured in twips:

officecli word table addcolumn \
  --table 1 \
  --position after 2 \
  --width 2000   # 2000 twips ≈ 0.35 cm

Behind the scenes, this triggers the logic at WordHandler.Navigation.cs (lines 543-560), which creates a new grid column entry and updates the table's <w:tblGrid> element. The command automatically handles width distribution and ensures existing cell content remains aligned with the correct grid positions.

Removing Columns and Handling Grid Spans

Removing a column requires rebuilding the grid and re-indexing any grid-spanning cells that cross the deleted boundary. OfficeCLI's removal routine preserves table integrity by recalculating gridSpan attributes for merged cells.

Delete the third column from a table using:

officecli word table removecolumn \
  --table 1 \
  --index 3

This invokes the removal routine in WordHandler.Set.Element.cs (lines 2356-2389), which rebuilds the <w:tblGrid> and re-assigns spanning cells to maintain the visual structure of the table.

Moving and Copying Columns

OfficeCLI treats moving and copying as grid re-ordering operations, manipulating the <w:gridCol> entries while adjusting cell gridSpan values when columns cross boundaries.

Moving Columns

Relocate column 4 to the position before column 2:

officecli word table movecolumn \
  --table 1 \
  --from 4 \
  --to before 2

The move operation re-orders the <w:gridCol> nodes; cell gridSpan values are recomputed as described in WordHandler.Set.Element.cs (lines 3219-3222).

Copying Columns

Duplicate a column while preserving the original widths:

officecli word table copycolumn \
  --table 1 \
  --source 1 \
  --dest after 2

Copying follows the same path as moving, but the source column's width definition is cloned before insertion, ensuring the new column matches the dimensions of the original.

Querying Column Layout After Modifications

After performing virtual column operations, verify the current configuration using the query command. The CLI emits the canonical column schema through the section-layout interface.

officecli word table get \
  --table 1 \
  --format json

The output includes the canonical keys columns, columnSpace, and columns.equalWidth set by WordHandler.Query.cs (lines 1181-1191). This ensures that any subsequent automation scripts receive consistent metadata about the table structure.

Summary

• Virtual column operations in OfficeCLI abstract the OOXML <w:tblGrid> complexity, allowing high-level commands to modify Word table structures.
• Adding columns triggers logic in WordHandler.Navigation.cs (lines 543-560) to create new grid entries and distribute widths.
• Removing columns invokes WordHandler.Set.Element.cs (lines 2356-2389) to rebuild the grid and re-index spanning cells.
• Moving and copying re-order <w:gridCol> nodes while recalculating gridSpan values at lines 3219-3222 of WordHandler.Set.Element.cs.
• Layout verification uses WordHandler.Query.cs (lines 1181-1191) to expose canonical keys like columns and columnSpace for downstream automation.

Frequently Asked Questions

How does OfficeCLI handle merged cells when removing a column?

When a column is removed, OfficeCLI recalculates the gridSpan attributes of cells that span across the deleted boundary. The routine in WordHandler.Set.Element.cs (lines 2356-2389) rebuilds the <w:tblGrid> and adjusts spanning cells to ensure the visual structure remains intact without orphaned grid references.

Can I specify exact column widths when adding a new column?

Yes, use the --width parameter measured in twips (1/20 of a point). For example, --width 2000 creates a column approximately 0.35 cm wide. The CLI applies this value to the new <w:gridCol> entry in the table grid definition.

What happens to bookmarks and references when moving columns?

OfficeCLI updates the table grid structure in WordHandler.Navigation.cs while preserving the underlying cell content. Since bookmarks in Word are anchored to specific ranges rather than column indices, they remain attached to their original cell content during move and copy operations, though you should verify references that depend on specific column positions.

Where does OfficeCLI store the column layout metadata?

The CLI writes canonical keys including columns, columnSpace, columns.equalWidth, and columns.separator to the document metadata through WordHandler.Query.cs (lines 1181-1191) and WordHandler.Set.SectionLayout.cs. This ensures that the officecli word table get command returns consistent structural information after modifications.

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