fm-saxml-converter

Generate structured, navigable documentation from FileMaker Pro Save a Copy as XML exports.

fm-saxml-converter turns a FileMaker SaveAsXML file into a folder of cross-linked Markdown pages — one file per table, field, layout, layout object, script, relationship, custom function, and value list — backed by a normalized JSON model of the solution. Optionally it adds a browser viewer, and tools that let AI agents query the solution.

The CLI is exposed as fm-saxml.

Why this exists

A FileMaker SaveAsXML export contains everything about a solution, but the raw XML is not readable, not navigable, and not stable across FileMaker versions. This project produces a documentation layer that is:

• Human-readable — Markdown pages with consistent headings, summary tables, and per-entity backlinks.
• AI-readable — predictable structure, machine-parseable front matter, and JSON sidecars for indexing.
• Linkable — every reference between entities (script step → field, layout → table occurrence, calculation → custom function) becomes a link, with "Used By" lists on the other end.
• Safe to share — credentials and other secrets are replaced with placeholders before anything is written.

Requirements

• A FileMaker Pro Save a Copy as XML export
• Python 3.11+ (not needed if you use the standalone executable)

Quick start

1. In FileMaker Pro: Tools → Save a Copy as XML…

2. Run the converter on that file:

   fm-saxml MySolution.xml
   

   (On Windows you can also drag the XML file onto fm-saxml.exe.)

3. Open the new MySolution_docs folder that appears next to your XML file.

Add --open to have the folder opened for you. Run fm-saxml doctor if something doesn't work and include its output in any bug report.

Installation

Easiest — no Python needed: download the fm-saxml executable for Windows, macOS or Linux from the project's Releases page.

chmod +x fm-saxml-macos                              # make it executable (Linux: fm-saxml-linux)
xattr -d com.apple.quarantine fm-saxml-macos         # macOS only: clear the download quarantine flag
./fm-saxml-macos --version

curl -L -o fm-saxml https://github.com/Blue-Kachina/fm-doc-saxml/releases/latest/download/fm-saxml-macos
chmod +x fm-saxml

With Python 3.11+:

pipx install fm-saxml-converter      # or run without installing: uvx --from fm-saxml-converter fm-saxml MySolution.xml

To install from source, see the technical README.

Updating

Check your version with fm-saxml --version, then upgrade the same way you installed:

When a newer version exists, fm-saxml prints a one-line notice after a run (checked at most once a day, never blocks, silent in CI and when output is piped). Disable it with FM_SAXML_NO_UPDATE_CHECK=1.

Usage

Most of the time, this is all you need:

fm-saxml <export file or folder>

The docs are written to <input name>_docs next to the input. Use --out <folder> (or -o) to put them somewhere else. If the output folder already has files in it, you'll be asked before they're overwritten; --force (or -f) skips the question.

Converted docs are local output: build them from your own export and don't commit them. To keep every solution in one place, set FM_SAXML_DOCS_ROOT (or pass --docs-root): each build then goes to <docs root>/<solution>, where tools find it with fm_saxml.find_docs("<solution>"). A rebuild swaps the new docs in only once they're complete.

Reading the docs from Python

import fm_saxml

docs = fm_saxml.load("Invoices_docs")
docs.find("script", "post invoice")
docs.refs_to("field:Invoices::Total")

See JSON contract for the rest.

Multi-file solutions

FileMaker Pro 26 can Save a Copy as XML for several files at once. Point fm-saxml at the folder it wrote:

fm-saxml ./SaXML_PROD_2026-10-14

Each file gets its own subfolder, and references from one file into another become links between them. See Multi-file solutions for the details.

Commands

fm-saxml <file> is shorthand for fm-saxml build <file>.

Common options

Run fm-saxml <command> --help for every option. The technical README covers the rest, including CI flags, the output layout, and known limitations.

Documentation

License

MIT

The secret-detection rules in src/fm_saxml/scrub/ are adapted from the FileMaker XML Scrubber by Andrew Kear, Clockwork Creative Technology, used under CC BY 4.0.