How to Manage Document Protection and Use the --force Flag in OfficeCLI

OfficeCLI provides a --force flag on write commands like set, add, and create to bypass document protection and modify locked content directly in the underlying XML.

OfficeCLI treats Microsoft Office document protection the same way Word or Excel do—many edits are blocked when protection is active. According to the iOfficeAI/OfficeCLI source code, you can manage these restrictions and override protection gates using the --force flag, which allows direct XML manipulation even when a document is locked for forms, comments, or read-only access.

How Document Protection Works in OfficeCLI

The protection logic resides in the resident server, which maintains an in-memory DOM of the open document. Before executing any write operation, the server validates the document's protection mode (none, readOnly, forms, comments, etc.). If a write targets a location locked under the current protection mode, the server throws a CliException with the message "Document is protected … use --force to override" at [src/officecli/ResidentServer.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) lines 1223-1224.

The --force Flag Implementation

Each write command in OfficeCLI defines its own --force option to skip protection checks and write directly to the document XML.

set command: Defined in [src/officecli/CommandBuilder.Set.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Set.cs) lines 14-30 as:

var forceOption = new Option<bool>("--force") { Description = "Force write even if document is protected" }

The handler reads this flag (result.GetValue(forceOption)) and, when true, routes the request through a "force write" path that bypasses protection gates.

add command: Implements identical --force handling in [src/officecli/CommandBuilder.Add.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Add.cs) lines 43-44.

create command: Uses --force primarily to overwrite existing files, though it serves the same protection-bypass purpose in Word-specific contexts.

Working with Forms Protection

According to the Word-specific documentation in [skills/officecli-word-form/SKILL.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-word-form/SKILL.md) lines 60-70, protection=forms locks non-field content while allowing edits to form fields (Structured Document Tags or SDTs). Attempting to edit static text under forms protection triggers the protection error unless you use --force.

To identify which content remains editable without forcing, use the Query("editable") method, which returns the set of fields a typical Word user could still fill (lines 398-404).

Practical Workflow for Protected Documents

Follow this sequence when managing document protection in OfficeCLI:

1. Create or overwrite the file:

officecli create report.docx --force

2. Attempt standard editing (fails under protection):

officecli set /body/p[1] --prop text="New text"

# Returns: ERROR: Document is protected (mode: forms). Use --force to override

3. Force-write locked content:

officecli set /body/p[1] --prop text="New text" --force

4. Edit form fields (no force needed):

officecli set /body/sdt[2] --prop text="Answer"

5. Re-apply protection when modifications are complete:

officecli set / --prop protection=forms

Summary

• The resident server validates protection mode before every write operation in ResidentServer.cs
• The --force flag bypasses protection gates on set, add, and create commands, allowing direct XML modification
• Under forms protection, only SDT form fields are editable without forcing; static content requires --force
• Use Query("editable") to identify which document regions remain editable under current protection settings
• Always re-apply protection after completing forced edits to maintain document security boundaries

Frequently Asked Questions

What happens if I try to edit a protected document without --force?

OfficeCLI throws a CliException with the message "Document is protected … use --force to override". This check occurs in the resident server at ResidentServer.cs lines 1223-1224 before any XML modification, ensuring locked content remains unchanged unless explicitly overridden.

Does --force behave differently for the create command?

Yes. While --force on set and add specifically bypasses document protection checks, on create it primarily functions as an "overwrite existing file" flag. However, in Word-specific contexts, it also serves the dual purpose of allowing writes to protected documents during the creation process.

Can I edit form fields without using --force?

Yes. Under protection=forms, Structured Document Tags (SDTs) remain editable because they constitute the intended fillable portion of forms-protected documents. Only static content like body paragraphs requires the --force flag to modify, as implemented in the protection gate logic.

How do I identify which parts of a document are editable before applying --force?

Use the Query("editable") command to return the set of fields available for editing under current protection settings. This query evaluates the document's protection mode and returns only the regions a typical Word user could fill, helping you determine which modifications require forced access versus which can proceed normally.

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