# Workbook Lifecycle

Inspect the intended workbook's saved/read-only state, properties, and external
dependencies before changing its format or publishing output. Session lifecycle
is separate; see [session and saving guidance](/reference/behavioral-rules/#sessions-and-failures).

Current commands and supported inputs come from CLI help or MCP tool descriptions.

## Metadata and document properties

Use built-in properties for existing document metadata and custom properties
for workbook-specific information. Custom properties can be removed; built-in
ones are maintained by Excel. Avoid putting private paths, credentials, or
connection strings in published properties.

Use MCP `workbook_read` action `inspect` or `excelcli workbook inspect` for a
bounded workbook overview. It returns worksheet visibility and used-range
geometry, table locations, and visible user-defined names, with per-section
counts and omitted-item counts. `sheet_name` narrows worksheet and table
metadata; the named-range section remains workbook-wide. Hidden worksheets are
reported, not skipped. The operation reads through Excel and does not change the
workbook or its view.

Cell previews are optional. Set `include_preview=true` and provide `sheet_name`;
optionally set `range_address` to limit the source range. Without it, the
preview starts at the top-left of Excel's UsedRange. The preview reads at most
10 rows by 10 columns, and reports omitted rows and columns. `max_cell_characters`
and `max_preview_characters` further bound text in returned values and formulas.
Row and column limits are applied before reading cell contents; text limits are
applied to the response. For example:

```text
MCP: workbook_read(action: 'inspect', workbook_session_id: sessionId,
     sheet_name: 'Summary', include_preview: true, range_address: 'A1:F100',
     max_preview_rows: 5, max_preview_columns: 6)
CLI: excelcli -q workbook inspect --session <session-id> --sheet-name Summary
     --include-preview true --range-address A1:F100 --max-preview-rows 5
     --max-preview-columns 6
```

Excel reports an empty worksheet's UsedRange as `$A$1`. Its preview contains a
null value and an empty formula; the returned address does not mean the cell is
populated.

If Excel cannot read a protected or otherwise inaccessible range, the operation
reports an error rather than presenting it as empty.

## Save and publish

Inspect `readOnly` with MCP `workbook_read` action `get-info` or
`excelcli workbook get-info` before editing. Protected workbooks require visible
authentication; Excel decides editing rights. Do not change protection to work
around a genuine permission restriction.

Workbook-changing actions reject read-only access before editing. Inspection,
window controls, calculation other than workbook precision changes, and authorized
Save As/copy/export remain available. MCP `calculation_mode` action `set-precision`
and `excelcli calculation set-precision` require editing rights.
Excel still enforces permissions on outputs.

Writes change the open workbook, not necessarily the saved file. Saving a
read-only workbook or a save cancelled by Excel returns an error. A failed save
leaves the session open and any unsaved changes available for inspection; do not
assume they were persisted or automatically discard them.

Successful saving confirms Excel's saved state, not completion of OneDrive
synchronization or upload to SharePoint.

Choose the output according to the task. Saving under a new name changes the
active workbook's path; saving a same-format copy leaves the active workbook
unchanged. PDF/XPS output is a published view, not an editable workbook.

Saved `.xlsx`, `.xlsm`, `.xlsb`, and `.xls` workbooks can be reopened with
`file(action: 'open', file_path: ...)` (MCP) or `excelcli session open <FILE>` (CLI).

Replacing an output needs authorization. A format conversion can remove
features: saving a macro-enabled workbook as `.xlsx` removes its VBA content.
Inspect the result and active path before continuing work.

For unattended exports, avoid opening viewers or modal previews. Configure
the [print layout](/reference/worksheet/#styling-and-outlines) before publishing.

## External Excel links

Discover the actual linked sources before refreshing them. A refresh can change
calculated results; it is not merely inspecting the workbook.

Breaking a link permanently replaces linked formulas with their current values.
Do it only when that change is intended, and inspect the resulting values before
saving. There is no tool-level undo. Closing without saving loses all earlier
unsaved work too.

Printing and print preview are not exposed: a default printer can produce
physical output, and modal preview can block unattended sessions.