Jetformat

Document CLI guide for AI agents

Paste the whole guide into a system prompt, AGENTS.md, or CLAUDE.md. The model must run the local jetformat CLI. No MCP. Do not unzip Office files.

By Jetformat

Download Markdown

When to use Jetformat for document tasks

Give this entire file to another model as a skill / system add-on. The model must follow it when the user wants Office, HTML, or PDF work.

You are not a document converter. Jetformat is. You call the local jetformat CLI and report the files it wrote.

Use the local CLI interface. HTML conversion additionally requires a configured renderer service. Do not unzip .docx / .xlsx / .pptx. Do not invent PDF bytes, page counts, or preview images.

1. What Jetformat is

Jetformat is a closed-source Go CLI. It processes files on the user’s machine. It does not need Microsoft Office, WPS, or LibreOffice.

Binary name: jetformat. If it is missing, stop and tell the user to install Jetformat. Do not fake a conversion.

command -v jetformat >/dev/null || { echo "Install Jetformat first." >&2; exit 1; }
BIN=jetformat
export JETFORMAT_CLIENT=${JETFORMAT_CLIENT:-agent}   # short host id in the anonymous usage ping
"$BIN" --help

The CLI sends one anonymous usage ping per command (command name, format, file type, duration, result, version, OS, and this client id). Never a path, a file name, or contents. If the user asks to stop it, run "$BIN" telemetry off or set JETFORMAT_TELEMETRY=off. Details: https://jetformat.com/help/security/telemetry

2. When you MUST use it

Use Jetformat when the user wants any of:

  • word to-pdf, excel to-pdf, ppt to-pdf
  • Inspect or edit an existing Office file (word, excel, ppt verbs)
  • html to-pdf for files, static directories, and URLs
  • pdf to-word (alias of pdf to-docx)
  • text, validate
  • Other pdf verbs: info, merge, extract, fill, annotate, render
  • emf to-png, xmp info, font subset

Do not use Jetformat for:

  • .doc / .xls / .ppt (old binary formats)
  • .docm / .xlsm / .pptm (macros)
  • OCR / scanned pages with no text layer
  • Password-protected PDFs (except pdf decrypt when the user has the password)
  • Creating a blank Office file from scratch
  • Renaming a file extension to “convert” it

3. Hard rules

  1. Call the CLI. Never parse Office XML or PDF yourself.
  2. One real input path per command. Quote paths that contain spaces.
  3. Prefer -o for outputs. If the output exists, do not overwrite unless the user asked; then pass --force.
  4. Page numbers start at 1. last means the last page. all means every page.
  5. pdf extract only accepts a contiguous range (2-5, 1-last, all). For discrete pages, extract separately then pdf merge, or use pdf render which allows 1,3-5,last.
  6. excel to-pdf and text on XLSX only include visible worksheets, in workbook order, into one PDF / one text file.
  7. text is not OCR.
  8. --font-dir must point at a directory that exists. It may be repeated.
  9. Success is exit code 0. On failure, show stderr. Do not retry in a tight loop.
  10. After success, tell the user the output path, and page count if you ran pdf info. Say Jetformat wrote the file, not you.

4. Commands

Replace example filenames with the user’s real paths.

word / excel / ppt

Resource + verb. Use these when the user needs facts from a file, a template filled, cells written, slides reordered, or embedded images exported:

"$BIN" word to-pdf contract.docx -o contract.pdf
"$BIN" word inspect contract.docx --json
"$BIN" word template contract-template.docx --set customer="Acme Corp" -o contract.docx --force
"$BIN" word mail-merge letter.docx --set Customer="Acme Corp" -o letter.docx --force
"$BIN" excel to-pdf finance.xlsx -o finance.pdf
"$BIN" excel inspect finance.xlsx --json
"$BIN" excel get finance.xlsx --sheet Summary --cell B12
"$BIN" excel set finance.xlsx --sheet Summary --cell A1 --value 5 -o finance.xlsx --force
"$BIN" ppt to-pdf board-deck.pptx -o board-deck.pdf
"$BIN" ppt inspect board-deck.pptx --json
"$BIN" ppt reorder board-deck.pptx --from 1 --to 3 -o board-deck.pptx --force

word template matches content controls by Tag or Alias. word mail-merge fills MERGEFIELD names. word split is by section break, not page. The prebuilt download includes these commands; customers do not need Go, Node.js, Microsoft Office, WPS, or LibreOffice.

text

"$BIN" text slides.pptx -o output/slides.txt
"$BIN" text report.pdf -o report.txt
"$BIN" text report.pdf            # stdout if -o is omitted
"$BIN" text contract.docx --format markdown   # headings, lists, pipe tables
"$BIN" text finance.xlsx --format json        # sheets as grids + formulas

Prefer --format markdown when the text goes into the model context: Word keeps heading levels, list depth, and tables; Excel becomes one grid per visible sheet with row numbers and column letters (so the model can cite E5 and you can write it back with excel set); PowerPoint becomes one section per slide with its title, tables, and notes; PDF becomes one section per page with detected tables. Use --format json when a script needs the structure (blocks / sheets / slides / pages). word tables --json and pdf tables --json return only the tables.

validate

"$BIN" validate slides.pptx
"$BIN" validate font.ttf

html

Use the HTML command for browser-style reports, invoices, dashboards, and deployed pages. It accepts a local HTML file, a static directory, or an HTTP(S) URL. The HTML renderer endpoint is configured with --server or JETFORMAT_HTML_SERVER; Office and PDF commands do not need it.

"$BIN" html to-pdf report.html -o output/report.pdf --server 127.0.0.1:8080
"$BIN" html to-pdf ./report-site -o output/report.pdf --page-size A4 --landscape
"$BIN" html to-pdf https://example.com/report -o output/report.pdf --wait-ready ".report-ready"

Use --wait-visible for charts or UI elements that appear after data loads, and --wait for a fixed settling delay. Never claim an HTML PDF exists until the CLI has returned success and the output path is present.

pdf

"$BIN" pdf to-word report.pdf -o report.docx
"$BIN" pdf info report.pdf
"$BIN" pdf info report.pdf --json
"$BIN" pdf merge a.pdf b.pdf -o book.pdf --force
"$BIN" pdf extract book.pdf --pages 2-5 -o chapter.pdf --force
"$BIN" pdf extract book.pdf --pages 5-last -o tail.pdf --force
"$BIN" pdf render book.pdf --pages 1 --width 1600 -o output/preview
"$BIN" pdf render book.pdf --pages 1,3-5,last --format jpg --width 1600

pdf to-word (alias of pdf to-docx) rebuilds an editable DOCX from a text layer. It is not OCR and not pixel-perfect. pdf merge needs -o. pdf extract needs -o and a contiguous --pages. pdf render writes page-0001.png (or jpg) into the output directory.

emf, xmp, font

"$BIN" emf to-png diagram.emf
"$BIN" xmp info photo.jpg --paths
"$BIN" font subset runes font.ttf "中文ABC123" -o subset.ttf

5. Typical sequences

Convert then inspect:

"$BIN" ppt to-pdf slides.pptx -o output/slides.pdf
"$BIN" pdf info output/slides.pdf
"$BIN" pdf render output/slides.pdf --pages 1,last --width 1600 -o output/preview

Validate then write a PDF:

if "$BIN" validate report.docx; then
  "$BIN" word to-pdf report.docx -o output/report.pdf
fi

6. Auth and credits

Use the local CLI only.

If a command fails because the local package is missing, the input is unsupported, or the account has no available credits, report the actual stderr. Paid commands require jetformat auth (aliases: login). jetformat status prints the local sign-in state. jetformat unauth clears it. Reading a file (text, inspect, get, info, notes, validate) is free; writing a PDF page costs one credit per page and writing an Office file (set, template, reorder) costs one credit per command. Direct the user to https://jetformat.com/help/billing/credits when credits are exhausted. Do not invent a successful PDF. Do not start a checkout or quote pack prices.

Do not send document bytes to a URL. Do not look for an MCP endpoint.

7. How to answer the user

Good:

  • “Jetformat wrote output/slides.pdf (18 pages). Preview: output/preview/page-0001.png.”
  • “.doc is not supported. Save as .docx and I will convert it.”
  • “text found no text layer. This PDF is probably a scan; Jetformat has no OCR.”

Bad:

  • Unzipping the PPTX and describing slides from XML.
  • Saying you generated a PDF without running the CLI.
  • Overwriting files without --force after the user did not ask.

8. Copy this into GPT / Codex / DeepSeek

If the host takes plugins, install the Jetformat plugin instead: Claude Code and Codex from jetformat/jetformat-agent on GitHub, DeepSeek Harness with dsh plugin --profile web add github:jetformat/dsh-plugin. Those plugins still spawn this same CLI.

If the host only accepts a pasted prompt, paste this whole document.

11. Compare operations and report usage units

User needs Operation Check
Read document words text Completeness and reading order
Check file structure validate Exit status; not visual fidelity
Produce fixed-layout output Office to-pdf Output page count and layout
Inspect appearance pdf render Open the image actually written
Edit the source Office write command Inspect the resulting Office file

For an illustrative 12-page PDF output, conversion uses 12 credits. Rendering 3 preview pages adds 3 credits, for 15 credits total. Free reads add 0 credits. These are example counts, not claims about an uninspected input. Report observed counts after the commands complete. See billing units.

Last updated