# CLI Render Mermaid files or standard input to SVG, and Mermaid fences in Markdown to images, from the command line. The package includes the `ondine` binary. The binary compiles with the same module as `ondine/compiler`. The [CLI](/docs/guides/cli) guide shows common tasks. ```sh # Writes flow.svg beside flow.mmd npx ondine flow.mmd ``` ## Usage ```sh # Renders the files, or standard input if there are no files ondine [files...] [--out-dir ] [--svg] [--worker ] [--restore] [--check] ``` ## Arguments ### files * **Type:** paths The Mermaid files to render. For each file, the command writes an `.svg` file beside the source or in `--out-dir`. The name drops a `.mmd` or `.mermaid` extension. Other extensions stay, so `flow.txt` becomes `flow.txt.svg`. ```sh # Writes a.svg and b.svg ondine a.mmd b.mermaid ``` If there are no files, the command reads Mermaid from standard input and writes SVG to standard output. ```sh # Reads Mermaid from standard input and writes SVG to standard output ondine < flow.mmd > flow.svg ``` ## Markdown If a file ends in `.md` or `.markdown`, the command rewrites the file in place. Each ` ```mermaid ` fence, at any indentation, becomes a block. A later run recognizes this block and renders it again: ```html title="README.md" Mermaid flowchart diagram ``` * **Payload:** The source as UTF-8, compressed with zlib deflate, then encoded as base64url. * **Alt text:** The `accTitle` of the diagram, or else its type. * **Other fences:** The command skips fences in other languages whole. It does not rewrite fences inside blockquotes. * **MDX:** The command does not rewrite MDX files, because MDX rejects HTML comments. Use [`ondine/remark`](/docs/api/remark) for MDX files. ## Options ### --out-dir * **Alias:** `-o` * **Type:** directory The directory for rendered files. If the directory does not exist, the command creates it. ```sh # Writes public/flow.svg ondine flow.mmd -o public ``` ### --svg Links SVG files from Markdown instead of the Worker. For each diagram, the command writes `-.light.svg` and `-.dark.svg` beside the Markdown or in `--out-dir`. The number `` follows document order. If a previous block linked an SVG file and the Markdown no longer links it, the command removes that SVG file. ```sh # Writes guide-1.light.svg and guide-1.dark.svg beside guide.md ondine guide.md --svg ``` ### --worker * **Type:** URL * **Default:** `https://ondine.sh` The origin of the image Worker that Markdown images link. If the request path of a diagram is longer than the Worker limit of 4,096 characters, the command reports an error and does not change that diagram. ```sh # Links a self-hosted Worker ondine README.md --worker https://diagrams.example.com ``` ### --restore Changes each block from a previous run back into a ` ```mermaid ` fence, and removes the SVG files that the block linked. ```sh # Restores the editable fences ondine README.md --restore ``` ### --check Writes and removes nothing. If a run would change a file, the command reports `file is out of date` and exits with code 1. ```sh # Fails CI if a diagram is out of date ondine README.md --svg --check ``` ### --print Prints each Mermaid file, or standard input, in the terminal and writes no files. The command needs the optional `@resvg/resvg-wasm` peer dependency and a monospace system font. | Terminal | Output | | ------------------------ | ----------------------- | | Kitty, Ghostty | Kitty graphics protocol | | iTerm2, WezTerm, VS Code | iTerm2 inline image | | Other terminals | Braille dots | Set `ONDINE_TERMINAL` to `kitty`, `iterm`, or `text` to select the output. ```sh # Prints the diagram in the terminal ondine flow.mmd --print ``` ### --help * **Alias:** `-h` Prints the usage text and exits with code 0. ```sh # Shows the usage text ondine --help ``` ## Output The command writes each report on standard error: * **Rendered files:** `source -> output`. A Markdown run reports only the files that it changes. * **Removed files:** `source: removed file`. * **Errors:** `file:line:column: message`, or `file: message` if the error has no position. An error in a Markdown fence has a position in the Markdown file. * **Standard input:** The name ``. ```txt flow.mmd -> flow.svg bad.mmd:3:1: Parse error on line 3: ``` ## Exit Codes | Code | Meaning | | ---- | ---------------------------------------------------------------------- | | `0` | Every input rendered, or with `--check`, every file is up to date. | | `1` | At least one input failed to render. The remaining files still render. | | `1` | With `--check`, at least one file is out of date. |