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.Tool

officeimo --version

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

dotnet new tool-manifest

dotnet tool install OfficeIMO.Tool dotnet 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.Tool

dotnet 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@ 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.pdf

officeimo pdf split report.pdf --pages-per-document 10 --output report-parts officeimo pdf decrypt protected.pdf --password-env PDF_OWNER_PASSWORD --output clear.pdf officeimo pdf flatten report.pdf --output raster.pdf --acknowledge-raster-output --dpi 150 officeimo pdf optimize report.pdf --output optimized.pdf officeimo pdf sanitize report.pdf --output sanitized.pdf officeimo pdf providers --ocr-provider-assembly ./providers/OfficeIMO.Ocr.Tesseract.dll officeimo 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.xml

officeimo 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 .invoice.xml or .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-State officeimo 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 printers officeimo workflow printers --paper-sources "Office printer" officeimo workflow print report.pdf --printer "Office printer" --pages 1-3 --pages-per-sheet 2 --copies 1 --duplex long officeimo 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 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.json

officeimo workflow job plan ./monthly.officeimojob.json officeimo workflow job run ./monthly.officeimojob.json --format ndjson officeimo 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.offic