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

> Learn to manage document protection in OfficeCLI. Discover how the --force flag lets you bypass protection and modify locked XML content directly for your files.

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

---

**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)](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)](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Set.cs) lines 14-30 as:

```csharp
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)](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)](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:

```bash
officecli create report.docx --force

```

2. **Attempt standard editing** (fails under protection):

```bash
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**:

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

```

4. **Edit form fields** (no force needed):

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

```

5. **Re-apply protection** when modifications are complete:

```bash
officecli set / --prop protection=forms

```

## Summary

- The **resident server** validates protection mode before every write operation in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.