OfficeIMO Document Tools

OfficeIMO.Tool

OfficeIMO.Tool is the installable command-line interface for OfficeIMO document conversion, extraction, inspection, markup, output, intake, and MCP workflows.

Install

Install it globally from NuGet when you want officeimo available from any directory:

dotnet tool install --global OfficeIMO.Toolofficeimo --version

For a repository-pinned local tool, create or reuse a tool manifest:

dotnet new tool-manifestdotnet tool install OfficeIMO.Tooldotnet tool run officeimo help# The .NET SDK also resolves a manifest-local tool through this shorthand:dotnet officeimo help

Update or remove a global installation with the standard .NET tool commands:

dotnet tool update --global OfficeIMO.Tooldotnet tool uninstall --global OfficeIMO.Tool

MCP clients

server.json describes the local STDIO server as io.github.EvotecIT/officeimo, backed by the OfficeIMO.Tool NuGet package. Clients supply OFFICEIMO_MCP_ALLOWED_ROOTS. The agent plugin launches dotnet dnx OfficeIMO.Tool@<package-version> mcp serve --stdio --yes with .NET SDK 10.0.100 or later; the trailing flag accepts the pinned package download on SDKs that prompt, and older SDKs pass it through harmlessly to the MCP host.

Registry clients place the download-consent flag before the package argument. This route requires an SDK whose dotnet dnx --help lists --yes, qualified with SDK 10.0.113. Some other .NET 10 feature bands lack that option; use the plugin's explicit launcher above on those SDKs. The registry entry exposes the same bounded operations as the plugin.

PDF copies and searchable scans

Create a separate PDF, split folder, or searchable scan with an explicit destination:

officeimo pdf extract report.pdf --pages last,1-3 --output selected.pdfofficeimo pdf split report.pdf --pages-per-document 10 --output report-partsofficeimo pdf decrypt protected.pdf --password-env PDF_OWNER_PASSWORD --output clear.pdfofficeimo pdf flatten report.pdf --output raster.pdf --acknowledge-raster-output --dpi 150officeimo pdf optimize report.pdf --output optimized.pdfofficeimo pdf sanitize report.pdf --output sanitized.pdfofficeimo pdf providers --ocr-provider-assembly ./providers/OfficeIMO.Ocr.Tesseract.dllofficeimo pdf ocr scan.pdf --output searchable.pdf --ocr-provider tesseract-cli --ocr-provider-assembly ./providers/OfficeIMO.Ocr.Tesseract.dll --ocr-language eng

Page selections retain order and repeated pages and support expressions such as last,1-3, odd, and all,!2. The selected pages are resolved against the captured input. Existing files or folders require --force; a source or folder containing it cannot be the destination. Decryption requires the owner password in the named environment variable. Other protected-document operations retain the PDF engine's permission and signature policy.

Flattening copies rendered appearances. Native text, forms, links, signatures, and attachments are omitted, so --acknowledge-raster-output is required. The managed renderer's fidelity limits still apply. Searchable OCR adds a text layer to the source pages; confidence does not certify recognition accuracy.

The tool includes no OCR executable or model. Supply a trusted optional provider deployment with its managed dependencies. OfficeIMO.Ocr.Tesseract registers tesseract-cli and uses a separately installed Tesseract executable. Repeated --ocr-option key=value entries configure the provider; executable/model paths are chosen by the invoking host. See the Tesseract provider options.

These commands emit bounded JSON containing status, artifact paths/counts/bytes, and diagnostic codes. Document text, recognized words, passwords and provider messages are excluded. Defaults limit selection to 100 pages or split parts, input to 256 MiB, output to 512 MiB, and raster work to 25 million pixels per page. Use the --maximum-pages, --maximum-input-bytes, --maximum-output-bytes, and --maximum-pixels-per-page options within the ranges listed by officeimo pdf --help.

Invoice workflows

Invoice commands return versioned JSON with separate model, mapping and standards results. Inspecting an invoice can succeed while reporting invalid model data; validate returns a failure exit code for those errors. Schema and business-rule statuses remain NotRun unless standards validation is explicitly configured.

officeimo invoice inspect invoice.xmlofficeimo invoice validate invoice.xml
# Replace existing source headers while retaining XML extensions.officeimo invoice edit invoice.xml --output invoice.edited.xml `    --number INV-002 --issue-date 2026-09-30 --buyer-reference BUYER-002
# Convert with an explicit, pinned target contract.officeimo invoice convert invoice.xml --output invoice.ubl.xml `    --release En16931_1_3_16 --syntax Ubl --profile En16931
# Create a hybrid invoice with Polish labels and an embedded font.officeimo invoice hybrid invoice.xml --output invoice.pdf `    --release FacturX_1_09_2_Zugferd_2_5_2 --syntax Cii --profile En16931 `    --language pl-PL --font ./fonts/InvoiceFont.ttf `    --columns Item,Quantity,Unit,NetPrice,Vat,NetAmount `    --unit-display Description --payment-display Description `    --modern --compact-details --page-identity
officeimo invoice batch validate first.xml second.xml --max-items 100 --stop-on-failure
# Validate exact source bytes with pinned authority artifacts and the Saxon runner.officeimo invoice validate invoice.xml --standards-release En16931_1_3_16 `    --rule-bundle ./rules/xrechnung.zip --saxon-jar ./saxon/saxon-he-12.10.jar

render creates a separate presentation PDF; hybrid embeds the captured CII XML. An explicit target is required for conversion and rendering. Unmapped source data and unsupported target fields block those operations. --allow-profile-loss permits only the documented reductions of lower Factur-X profiles and returns warnings for them. XML standards validation does not certify the PDF's archival conformance.

edit accepts --number, --issue-date, --due-date, --buyer-reference and --payment-reference; dates use yyyy-MM-dd. It replaces existing unique plaintext fields and retains other XML content. Signed XML and unsupported date representations are blocked. It retains the input syntax/profile and accepts no target options. A successful edit can report model or mapping errors; inspect those JSON findings and request standards validation when required. Requested standards stages must pass on exact edited bytes before publication. Use batch edit to apply the same captured replacements to several inputs.

File outputs are created atomically and never overwrite existing files. Batch writing uses --output-directory, naming each output <input-stem>.invoice.xml or <input-stem>.invoice.pdf. All inputs and destinations are checked before execution; colliding or existing destinations fail before any output is created. Batch publication is per item. Limits default to 256 inputs, 64 MiB of combined input and 64 MiB of returned artifacts. --max-input-bytes and --max-output-bytes change those combined budgets; each XML input remains limited to 16 MiB. For the pinned authority downloads and runtime requirements, see the standards validator guide.

File batches and printing

DOC conversion blocks known legacy import loss by default; --allow-legacy-loss explicitly accepts the reported reductions. TXT conversion treats HTML and Markdown as literal text, detects Unicode BOMs and otherwise uses strict UTF-8. Use --text-encoding and --tab-size for explicit text settings. The adapter's diagnostics remain on standard error.

Batch conversion uses the existing executable workflow catalog. PDF routes include DOC, DOCX, TXT, XLSX, PPTX, HTML, Markdown, RTF, Draw, DjVu and Publisher. Files without an eligible route are counted as skipped. Checkpoints are optional. Resolve relative paths from the directory where the command runs:

officeimo workflow batch --input-directory ./Documents --output ./PDF# Enable durable checkpoints; rerun to verify and reuse completed artifacts.officeimo workflow batch --input-directory ./Documents --output ./PDF --checkpoint ./PDF-Stateofficeimo workflow batch --input-directory ./Documents --output ./PDF --checkpoint ./PDF-State --retry-failed# Explicit files and other existing conversion targets use the same command.officeimo workflow batch report.pdf appendix.pdf --output ./HTML --target html
officeimo workflow printersofficeimo workflow printers --paper-sources "Office printer"officeimo workflow print report.pdf --printer "Office printer" --pages 1-3 `  --pages-per-sheet 2 --copies 1 --duplex longofficeimo workflow print-plan report.pdf --pages-per-sheet 6 --page-subset odd `  --scale custom --custom-scale 40 --alignment bottom-right --margin 18 `  --margin-left 24 --margin-right 24 --color grayscale

Ordinary batches accept --conflict fail|rename|replace. Checkpoint jobs require fail and separate source, output and state trees. Changed completed inputs/settings/resources, altered or missing outputs and existing outputs without a verified receipt require inspection. Concurrency and execution budgets can change without discarding verified artifacts. Item failures produce a nonzero exit code. See the batch contract for resource limits, diagnostics and recorded-artifact reuse across compatible engine updates.

Printer submission uses prepared raster sheets. The returned job identifier proves queue acceptance; physical delivery is unconfirmed. After an interrupted submission, check the queue before retrying. Windows file printers require --output-file naming a new local file. macOS/Linux delivery uses the existing CUPS service boundary and requires its command-line tools.

Both print-plan and print accept 1/2/4/6/9 pages per sheet, --page-subset all|odd|even, nine-position --alignment, and per-edge point margins (--margin-left, --margin-top, --margin-right, --margin-bottom). Odd/even refers to original document page numbers within --pages. --scale custom --custom-scale <percent> uses 1–1000 percent of source physical size and clips overflow. --color grayscale changes the prepared pixels; --color color retains source colors, subject to the device's capabilities. Layout margins do not remove printer hardware margins.

Saved conversion jobs

Save reviewed batch settings without executing them, inspect the plan, then run the same local job from any working directory:

officeimo workflow batch --input-directory ./documents --output ./pdf --checkpoint ./conversion-state --save-job ./monthly.officeimojob.jsonofficeimo workflow job plan ./monthly.officeimojob.jsonofficeimo workflow job run ./monthly.officeimojob.json --format ndjsonofficeimo workflow job run ./monthly.officeimojob.json --retry-failed

Paths inside the job resolve against its file location. Saving captures portable settings and never reads secret values or converts files. Unknown schema versions, unknown fields and unsupported renderer settings are rejected. A plan reports selection, destinations and collisions without writing outputs or checkpoints; execution revalidates current inputs. Registered iWork routes use the host's ordinary batch registration; checkpoints still require supported built-in routes.

Use --source-password-env NAME and --pdf-password-env NAME for runtime secret references. Saved jobs never contain password values. PowerShell runs the same definition with Invoke-OfficeConversionJob -Path ./monthly.officeimojob.json. Studio's local-folder workbench loads source-folder jobs that target PDF using automatic route selection and have no password references. Use the CLI or PowerShell for explicit-file lists, other targets, fixed conversion routes or jobs with password environment-variable references.

Ordinary workflow batch keeps its aggregate JSON default. --format json adds a versioned per-file report, bounded to 10,000 retained items and 16 MiB of serialized item data, with an explicit truncation marker. --format ndjson streams each item and a final summary. Saved-job execution defaults to the versioned JSON report. Human diagnostics stay on stderr. A batch with no selected conversions fails unless --allow-empty explicitly accepts that outcome; partial failures and cancellation keep their failure/cancellation exit codes and retain already published outputs.

If discovery or its file budget stops a run after earlier files complete, the final report retains those item outcomes and includes summary.failureSummary. The command fails even when no individual conversion failed; JSON and NDJSON still include the terminal summary.

See the complete job examples for expected results and checkpoint retry instructions.

Retain a readable attempt independently of checkpoint state by choosing a new report path outside the input, output and checkpoint trees:

mkdir runsofficeimo workflow job run ./monthly.officeimojob.json --report ./runs/first.jsonofficeimo workflow job report ./runs/first.jsonofficeimo workflow job run ./monthly.officeimojob.json --retry-failed --report ./runs/retry.json

The report parent folder must exist. Existing report files are preserved. Each attempt records the saved definition's fingerprint, timing, aggregate outcome and bounded per-file results. Inspection never runs the job or opens its referenced files. A report left by an exited writer appears as interrupted; a live writer remains running. Reports describe past observations. The normal source, output and checkpoint checks still determine whether an artifact can be reused.

If report creation fails, conversion does not start. If final recording fails after conversions, the command reports the recording error and returns failure while retaining completed outputs and their conversion counts. Use a separate report filename for each attempt rather than replacing earlier evidence.

Common workflows

# Office documents to PDFofficeimo convert report.docx report.pdfofficeimo convert archive.doc archive.pdfofficeimo convert report.txt report.pdf --text-encoding utf-8 --tab-size 4officeimo convert workbook.xlsx workbook.pdfofficeimo convert deck.pptx deck.pdf
# Draw pages to PDF, with source page sizes and explicit layer/loss choicesofficeimo convert diagram.odg diagram.pdfofficeimo convert diagram.fodg diagram.pdf --diagram-layers screenofficeimo convert diagram.odg diagram.pdf --require-no-loss
# DjVu scans to searchable PDF, using existing text layersofficeimo convert book.djvu book.pdfofficeimo convert scan.djv scan.pdf --require-no-loss
# Convert Apple ZIP files or local directory packages through shared workflowsofficeimo convert document.pages document.docxofficeimo convert budget.numbers budget.xlsxofficeimo convert presentation.key presentation.pptxofficeimo convert document.pages document.pdf
# Supported documents to Markdown or JSON through OfficeIMO.Readerofficeimo convert workbook.xlsx workbook.mdofficeimo convert report.docx report.json
# Extract to standard output or a fileofficeimo read report.docx --format markdownofficeimo extract report.docx --format markdown --output report.md
# Return a compact JSON inspection resultofficeimo inspect deck.pptx
# Inspect and convert tabular data without loading an editable workbookofficeimo tabular sheets workbook.xlsxofficeimo tabular schema workbook.xlsx --sheet Dataofficeimo tabular convert input.csv output.xlsxofficeimo tabular convert workbook.xlsb output.tsv --sheet Dataofficeimo tabular convert pipe-delimited.csv output.csv --delimiter '|' --output-delimiter ','
# Analyze embedded Word images without writing a fileofficeimo workflow optimize-images input.docx --analyze
# Optimize a separate Word copy, or choose a .pdf outputofficeimo workflow optimize-images input.docx --output optimized.docx --mode both --dpi 144 --quality 85
# Process an explicit batch; each output is independently staged and reopenedofficeimo workflow optimize-images first.docx second.docx --output-directory optimized --format pdf --mode both
# Export selected PDF pages to validated imagesofficeimo workflow export-pages report.pdf --output .\report-pages --pages 1-3,last --format png
# Assemble an ordered PDF from files, folders, images, and ZIP archivesofficeimo workflow assemble cover.png report.docx appendices .\attachments.zip --output complete.pdf
# Inspect print-sheet placement without requiring a platform printer driverofficeimo workflow print-plan complete.pdf --paper A4 --pages-per-sheet 2 --scale fit
# Inspect or assess provenance with versioned JSON outputofficeimo provenance inspect report.docxofficeimo provenance assess page.html
# Remove selected, structurally valid carriers through the owning format packageofficeimo provenance remove report.docx --output report.cleaned.docx
# Plan and apply source-bound PDF redactions through reusable JSON contractsofficeimo pdf redact providers --ocr-provider-assembly ./providers/MyOcr.Provider.dllofficeimo pdf redact plan contract.pdf --recipe redaction.recipe.json --evidence contract.plan.jsonofficeimo pdf redact apply contract.pdf --recipe redaction.recipe.json --decisions contract.decisions.json `    --output contract-redacted.pdf --evidence contract-redacted.evidence.json `    --ocr-provider my-provider --ocr-language en --ocr-option model=documentofficeimo pdf redact batch --request redaction.batch.json

The positional destination is optional for supported Office and Draw inputs to PDF conversion. When omitted, the tool writes a sibling .pdf file. --output <path> remains available for scripts that prefer named options.

Markdown and JSON destinations are semantic Reader projections rather than fixed-layout renderings. They use the same handlers as officeimo reader read and support every input format reported by officeimo reader capabilities.

officeimo reader read accepts iWork directory bundles with .pages, .numbers, or .key extensions as individual documents. Folder discovery also keeps each bundle intact. Export files and asset directories must be outside the source bundle; reported size and content hashes describe the bounded captured package. These Reader outputs are semantic extraction, with the same rendering limits as other Reader routes.

Apple-to-OOXML and Apple-to-PDF conversion accept ZIP files and local directory packages and returns JSON with typed fidelity diagnostics, producer/projection facts, source snapshot SHA-256, coverage, and publication status. Defaults reject partial editable reconstruction and previews without known complete coverage. Use --iwork-mode auto|editable|visual, --allow-partial, --allow-incomplete-preview, and --normalize-worksheet-names only when those acceptance choices fit the task. --max-input-bytes and --max-output-bytes bound conversion. Directory-package checksums describe a private transport ZIP, identified by snapshotKind = DirectoryPackage. Root replacement and changes to file membership or content prevent publication. The destination must be outside the source package and separate from its members. Native permission-scoped directory intake remains outside this local-filesystem contract. PDF requires complete editable reconstruction and retains both source and PDF-stage evidence; partial output, previews, content exclusion and PDF-stage omissions or failures are rejected.

All convert destinations are protected from accidental replacement. Pass --force explicitly when an existing output file should be replaced.

Command areas

• officeimo invoice inspects, validates, converts and renders CII/UBL invoices through the shared invoice workflows, individually or in bounded batches.

• officeimo convert routes Apple-to-OOXML and Apple-to-PDF destinations through OfficeIMO.Workflows.IWork, Office PDF destinations to their first-party adapters, Draw PDF destinations through OfficeIMO.Workflows, and Markdown/JSON destinations to OfficeIMO.Reader.

• officeimo read and officeimo extract are convenient aliases for officeimo reader read.

• officeimo inspect is a convenient alias for officeimo agent inspect.

• officeimo tabular lists workbook sheets, reports reader schemas, and converts CSV, TSV, XLSX, XLSB, or XLS tabular data.

• officeimo workflow exports PDF pages, assembles mixed document sources, and creates deterministic print-sheet plans.

• officeimo pdf redact plans, applies, verifies, and batch-runs source-bound PDF redaction recipes with privacy-safe JSON evidence. batch --request accepts the strict officeimo.pdf.redaction.batch-request.v1 file-set contract, preserves deterministic relative-path ordering, and supports atomic-all or continue-per-item publication. Framework-dependent tool builds load optional provider assemblies only from explicit --ocr-provider-assembly paths and select one with --ocr-provider; NativeAOT hosts must register a statically linked provider through OcrEngineCatalog. The default tool still includes no OCR runtime or model. Use --ocr-language, --ocr-min-confidence, and repeated --ocr-option key=value values for non-secret configuration. Passwords are accepted only through named environment variables, and provider credentials should remain behind environment or secret-store references. Output, evidence, and manifests can never replace the PDF, recipe, decisions, or batch-request input, even with --force; zero-area verification of re-encrypted output accepts --expected-output-sha256 from prior apply evidence. Signing a derivative remains an API-host responsibility because the CLI does not construct external signers.

• officeimo provenance discovers format owners and runs bounded inspect, assess, selective-remove, and batch workflows with versioned JSON or readable text output.

• officeimo html converts HTML or MHTML to PDF and reports renderer capabilities.

• officeimo reader extracts individual documents or folders as Markdown or JSON and reports supported formats.

• officeimo markup parses, validates, emits, previews, and exports OfficeIMO Markup.

• officeimo agent returns bounded JSON for inspection, search, selected fetch, conversion, and capability discovery.

• officeimo mcp serve --stdio exposes the compact agent operations to MCP clients.

Run officeimo help or append <area> --help for the complete command contract.

Workflow output is protected from accidental replacement. Pass --force to replace an existing image folder or assembled PDF. Assembly preserves caller source order, expands folders and ZIP entries in deterministic path order, and applies bounded archive entry, size, and compression checks before publication. Supported explicit inputs are PDF, DOCX, XLSX, PPTX, HTML, common raster image formats, folders, and ZIP archives.

Provenance workflows

# Machine-readable output is the defaultofficeimo provenance capabilitiesofficeimo provenance inspect .\report.docxofficeimo provenance assess .\page.html
# Text output is available for interactive useofficeimo provenance inspect .\image.png --format text
# Existing output is refused unless --force is explicitofficeimo provenance remove .\report.docx --output .\report.cleaned.docx
# Batch work is sequential and bounded; removal requires an explicit destination directoryofficeimo provenance batch inspect .\one.docx .\two.pdf --max-items 20officeimo provenance batch remove .\one.docx .\two.pdf --output-directory .\cleaned

The JSON envelopes use officeimo.provenance.capabilities.v2, officeimo.provenance.result.v2, or officeimo.provenance.batch.v2 schema identifiers. The capabilities response reports the exact extensions, structural formats, owning package, and memory/browser qualification. Successful inspection can still report provenance evidence; findings are data and do not change the process exit code. Execution failures use the shared exit-code table below.

audit and check assess files or directories without changing them:

# Recurse through qualified files; patterns match slash-separated paths relative to each rootofficeimo provenance audit .\documents --include "*.html" --exclude "private/*" --format ndjson
# Fail on potentially dangerous Unicode; use --fail-on carriers or any for a different evidence policyofficeimo provenance check .\documents --format sarif > provenance.sarif

audit returns success when assessments execute successfully, even when findings are present. check returns exit code 1 when its selected policy finds evidence, and existing error codes for failed assessments. --fail-on dangerous-text is the default; it requires text inspection. Unsupported text checks remain explicit in reports. Neither command configures cryptographic or watermark providers.

Directory discovery skips symbolic links and .git, bin, obj, and node_modules directories. --no-recursive limits discovery to the root. --include and --exclude accept repeatable simple wildcards (* and ?, with * also matching directory separators). Explicit file inputs obey the filters and produce failures when missing or unsupported. The default is 256 assessed files, configurable with --max-items up to 10,000, and at most 100,000 visited entries. Exceeding a bound or finding no eligible files fails the audit instead of reporting a partial or empty success.

Use check in CI or a pre-commit hook to inspect the current working files. It does not inspect Git's index or fetch a website. NDJSON emits one result-v2 document per assessed file; SARIF 2.1.0 exports Unicode findings, structural carrier notes, input hashes, check coverage, and execution failures. A structural carrier note is evidence, not an authenticity or AI verdict.

Reports include the digest of the exact captured bytes and explicit Completed, Disabled, Unsupported, NotConfigured, Failed, or NotRequested check states. A missing text or provider result is not represented as a completed zero-finding check.

Removal preserves the input format, keeps malformed carriers by default, and routes package-aware changes to the owning OfficeIMO library. A mutation that would invalidate an Office package signature is blocked unless --remove-invalidated-signatures is supplied. Use --keep-c2pa, --keep-external-c2pa, or --keep-ai-source to preserve a carrier class, and --no-embedded to skip supported embedded assets. The CLI accepts only extensions registered to an OfficeIMO owner and rejects renamed package subtypes; generic ZIP files and unregistered formats are outside this workflow.

Tabular conversion writes through an atomic sibling staging file and refuses to replace an existing destination unless --force is supplied. Workbook output is limited to .xlsx, .xlsb, and .xls; CSV and TSV are supported as delimited output. Select a workbook sheet with --sheet <name> or --sheet-index <zero-based-index>. Recognized .tsv inputs always use a tab unless --delimiter explicitly overrides it. --delimiter controls input parsing; --output-delimiter independently controls CSV or TSV serialization, whose default comes from the output extension. Sheet-list and schema output escape backslashes and control characters as \\, \t, \r, \n, or \uXXXX so each name remains on one output line.

Office documents to PDF

officeimo convert .\report.docxofficeimo convert .\workbook.xlsx .\published\workbook.pdfofficeimo convert .\deck.pptx --output .\deck.pdf --forceofficeimo convert .\brochure.pub .\brochure.pdf

The input extension selects OfficeIMO.Word.Pdf, OfficeIMO.Excel.Pdf, or OfficeIMO.PowerPoint.Pdf. The tool opens the source read-only, applies structural package-bomb checks, bounds Open XML part parsing, writes diagnostics to standard error, and refuses to replace an existing PDF unless --force is supplied.

Conversion defaults to a 64 MiB input limit, 10,000,000 characters per XML part, and a 256 MiB PDF output limit. Operators processing larger trusted documents can set --max-input-bytes, --max-characters-in-part, or --max-output-bytes explicitly. Native Office PDF exports stream to an atomic staging file. Draw PDF conversion uses bounded in-memory serialization and workflow reopen validation before atomic publication. A rejected or failed conversion preserves the destination.

ODG and FODG conversion keeps source page dimensions, including blank pages, and selects print-visible layers by default. Use --diagram-layers screen|print to choose visibility. Located fidelity diagnostics go to standard error; --require-no-loss rejects source or PDF-stage losses before publication. Batch conversion accepts the same diagram choices and --maximum-xml-characters-in-part; mixed batches apply diagram settings only to diagram routes. Checkpoint reuse retains source and page locations in recorded loss diagnostics.

Publisher PDF conversion supports Publisher 2002-and-later publications. It keeps source page dimensions and writes fidelity diagnostics to standard error. Use --require-no-loss to reject a conversion when OfficeIMO reports fidelity loss. Publisher 97/98 and 2000 files require conversion to a later Publisher format first.

Static HTML conversion

officeimo html convert report.html --output report.pdf --profile print-pagedofficeimo html render report.html --encoder png --output report-pages.zip --max-input-bytes 8388608

The HTML commands accept HTML, MHTML and ZIP site bundles. Local and remote resource reads are disabled by default; bounded data URIs and archive resources remain available. PDF and page-image archives use print pagination by default. Use html render --profile screen-full-page for a single continuous screenshot. --max-input-bytes changes the input-size ceiling while preserving the untrusted DOM, CSS, selector and responsive-image limits. ZIP entry and decoded-byte budgets remain separate from the encoded input limit. Use officeimo html help for the profile, page-selection and archive-limit options.

Compact agent workflow

The agent commands are designed for bounded model context. They do not replace the complete Reader result used by applications and archival pipelines.

$search = officeimo agent search .\report.docx --query "renewal date" --take 5 | ConvertFrom-Json
officeimo agent fetch `    --source-id $search.sourceId `    --id $search.results[0].id `    --path .\report.docx

For PST, OST, OLM, EMLX, Mbox, MBX, and directories of messages, search uses lightweight store summaries. fetch materializes only the selected message. Whole-store conversion is intentionally rejected.

Mailbox search examines at most 10,000 summaries per execution and reports itemsScanned and scanLimitReached. A scan limit means the response does not establish that later items have no matches. Use search-email for bounded semantic content search with durable continuation:

$page = officeimo agent search-email ./archive.pst --query "renewal date" `    --fields "Subject,TextBody,HtmlBody" --take 5 --max-items-scanned 1000 | ConvertFrom-Json
if ($page.nextCheckpoint) {    $page = officeimo agent search-email ./archive.pst --query "renewal date" `        --fields "Subject,TextBody,HtmlBody" --checkpoint $page.nextCheckpoint `        --take 5 --max-items-scanned 1000 | ConvertFrom-Json}

search-email accepts one case-insensitive query phrase and the same mailbox metadata filters as search. Fields are Subject, Sender, Recipients, TextBody, HtmlBody, RtfBody, AttachmentNames, Bodies or All; attachment payloads are not searched. Defaults allow 10,000 processed items per batch, 16 MiB of decoded properties and 2,000,000 searchable characters per item. --max-decoded-bytes and --max-searchable-characters can reduce those bounds. Complete-source hashing also reads the selected source to bind the checkpoint, independently of the item scan budget. Opening/indexing work follows the store reader's own container limits; Mbox, EMLX and OLM can decode content while opening. The requested decoded-property limit also applies to those reads. MIME body alternatives share that budget, EMLX includes its metadata trailer, and OLM counts scalar XML values. ZIP/XML input, headers and attachment payloads have separate store-reader limits.

Follow nextCheckpoint even when a batch returns zero matches. isComplete records enumeration completion, while truncated also records output trimming. The checkpoint resumes after the last delivered match if the output budget shortens a page, so later matches remain available. Source or query changes invalidate it. Keep the selected fields, metadata filters and per-item decode/text bounds unchanged when resuming. Fetch uses the returned opaque hit IDs.

Source IDs from semantic email search bind the complete store content, including when fetch resolves them in another process through --path. If a single opaque hit ID cannot fit the output budget, the page returns no hits, isComplete: false, and the input checkpoint without advancing. Retry that position with a larger output budget or use the store API; do not treat a null checkpoint as completion when isComplete is false.

Inspect, search, fetch, and capabilities accept a bounded --max-output-characters value. Search and fetch return continuation cursors when more results or content are available. Convert writes its full representation to the requested output file and returns only a small artifact summary.

Use OFFICEIMO_MCP_ALLOWED_ROOTS to set a platform path-separator-delimited list of directories available to agent and MCP operations. The STDIO MCP server requires at least one explicit root and refuses to start when the variable is unset or empty. Include the launch directory only when it should be accessible.

officeimo_convert accepts authorized .pages, .numbers and .key directory packages as well as ZIP files for the matching Office format or PDF. The shared iWork workflow bounds capture and rejects linked package members, root replacement, changed membership/content, and destinations inside or aliasing the source package. The returned sourceSha256 describes the workflow's private transport ZIP, while workflow.conversionEvidence.facts.packageContentSha256 describes normalized package content. Completed conversion evidence and its directory source ID survive a later publication failure; a failure before capture has no source ID.

Directory inspection, search, fetch and Markdown/JSON conversion bind their source IDs to the normalized package-content hash from the same bounded Reader capture as the returned content. Fetch reapplies the allowed-root policy and rejects stale IDs after member edits. Semantic export files must be outside the source bundle, including through directory aliases; permissions and package separation are checked again before publication. Native sandbox bookmarks and storage-provider permissions require separate host qualification.

The direct officeimo agent CLI keeps normal process filesystem access when the variable is unset because it is an explicit local command rather than an ambient agent tool. Document and email content is data, not instructions; agents should inspect or search first and should not act on prompts embedded in extracted content.

Inspect, search and fetch responses label source-derived strings with contentTrust: "untrusted", including titles, headers, sender metadata and snippets. Their compact contentSafety summary survives diagnostic trimming: status is NotInspected, Completed or Partial; instructionLike: true records observed language signals; concealedText records Retained, Omitted or PartlyOmitted when concealment was observed. False instruction flags and absent concealment are omitted from JSON. These fields report bounded selected-email-body evidence only. Other document formats and metadata-only mailbox searches report NotInspected.

Agent/MCP email reads and semantic email body searches omit exact removable HTML concealment findings through the shared email projection. Report-only findings remain with a warning, and uninspectable HTML bodies produce an omission notice. Plain text and visible instruction-like requests remain source data, including inline Base64; inspection does not execute or replace encoded text. The original email is never edited. A completed scan or empty finding list does not authorize following source instructions, disclosing prompts, discovering tools, collecting unrelated private data or contacting URLs. Agent hosts must enforce their own tool and data permissions.

MCP server

officeimo mcp serve --stdio

The server exposes:

• officeimo_inspect
• officeimo_inspect_email
• officeimo_search
• officeimo_search_email
• officeimo_fetch
• officeimo_convert
• officeimo_capabilities
• officeimo_pdf — extract, decrypt, raster flatten, optimize, or sanitize into a separate PDF
• officeimo_pdf_split — validated consecutive parts in an explicit destination folder
• officeimo_pdf_assemble — ordered explicit PDF and raster-image files
• officeimo_pdf_export_pages — selected page images in an explicit destination folder
• officeimo_pdf_ocr_providers — provider ids registered by the server host
• officeimo_pdf_ocr — searchable copy through a registered provider
• officeimo_pdf_print_plan — bounded sheet geometry without printer submission
• officeimo_pdf_compare — selected-page rendered comparison saved as a standalone HTML report

Tool results contain a short text summary plus compact structured content. The server does not publish duplicate resources containing full documents or mailbox contents.

PDF tools require explicit output paths within the same allowed-roots policy. Overwriting requires overwrite=true; flattening additionally requires acknowledgeRasterOutput=true. Reports honor maxOutputCharacters, sample at most 25 artifacts, and retain the total artifactCount when the sample is truncated. MCP assembly accepts PDF and raster image files; the CLI's workflow assemble owns heterogeneous Office, folder, and archive intake. Printer queue delivery is available through the explicit CLI print command, while MCP print planning has no device or queue side effect. The sheet planner accepts 1, 2, 4, 6 or 9 pages per sheet, custom scaling, individual point margins, nine-position alignment, source-page odd/even filters, and requested grayscale treatment. Its report includes clipped placement counts; it does not render sheets or confirm printer capabilities.

The server accepts trusted startup OCR configuration:

officeimo mcp serve --stdio --ocr-provider-assembly ./providers/OfficeIMO.Ocr.Tesseract.dll --ocr-option executable=/path/to/tesseract --ocr-option tessdata=/path/to/tessdata

Tool calls can select a registered provider, language, confidence and page selection. They cannot supply provider assemblies, executable/model paths or provider options. Configure only providers whose runtime and data-access behavior you authorize.

Protected PDF tools read only environment-variable names explicitly admitted by the trusted host. No names are admitted by default. Start the server with repeated --pdf-password-env PDF_OWNER_PASSWORD options to admit selected names; then pass passwordEnvironmentVariable="PDF_OWNER_PASSWORD" in a PDF tool call. An unrelated process environment variable remains unavailable even when it contains valid PDF credentials. Password values stay out of tool arguments and reports.

Use officeimo agent inspect-email ./message.eml --max-output-characters 6000 or officeimo_inspect_email for the bounded mail-data and HTML safety report. EML/MSG/OFT/TNEF reports include body alternatives, charsets, attachment metadata, protection classification and unverified signature status. ICS/VCF reports root counts; store/OAB reports cover catalogs without inspecting every message or entry. The optional HTML pass reports concealment and the shared active-content policy, without body previews or signature values. Its status makes unavailable and oversized inspection explicit. When details exceed the output budget they are omitted and truncated is true; summary counts remain, and an insufficient minimum budget is rejected. Existing allowed-root and source-identity restrictions apply.

Mail-data identities use the same bounded discovery profile as inspection. They hash individual files or the selected Store/OAB owner sources, including OAB Full Details components, and are checked again after inspection. Supporting legacy OAB components remain outside the entry catalog. Identity checks may reopen and hash the source; report samples limit retained output rather than source hashing I/O. Install the OfficeIMO Document Tools plugin for Codex, Claude Code, or another client supporting portable Agent Plugins. It bundles document and mailbox skills with a pinned NuGet tool launcher. Configure authorized document roots before starting the client.

Exit codes

Contributing

Contributors can run the current checkout without installing the package:

dotnet run --project OfficeIMO.Tool/OfficeIMO.Tool.csproj --framework net8.0 -- helpdotnet run --project OfficeIMO.Tool/OfficeIMO.Tool.csproj --framework net8.0 -- convert report.docx report.pdf

The CLI remains a thin surface over the owning OfficeIMO packages; reusable conversion and extraction behavior belongs in those packages rather than in command handlers.

Selected PDF comparison reports

officeimo workflow compare current.pdf revised.pdf --output review.html \  --expected-pages 120-124,last --actual-pages 121-125,last

Each selector uses original document page numbers and preserves order. Null or an omitted selector selects the whole corresponding document. The comparison admits at most 100 selected pages per side. Pages pair by selection position; extra selected pages are unmatched. The standalone HTML report includes page links, selected scope, document totals, render limitations and snapshot SHA-256 values. It reports rendered appearance, without semantic or moved-page detection. Existing reports require --force. --password-env and --comparison-password-env read independently selected password environment variables; credentials stay out of the report.

For MCP, inspect both PDFs first and pass their returned sourceId values to officeimo_pdf_compare as sourceId and comparisonSourceId, with an explicit separate outputPath ending in .html. Optional expectedPages and actualPages use the same selectors. Source ids are rechecked before capture and publication; changed sources require inspecting again. Both sources and the output remain within the host's allowed roots. overwrite explicitly permits replacing an existing report. Password variable names must be admitted by the trusted server host. The response contains bounded artifact metadata, not the embedded gallery.