CLI reference

The flowmark command validates source, renders SVG, formats files, and exposes parsed or compiled models for tooling.

Install

pnpm add --save-dev @ministryplace/flowmark-cli
pnpm flowmark --help

Use pnpm dlx @ministryplace/flowmark-cli … for a one-off evaluation. Use a project-local dependency for builds and CI.

After the first stable release, the same published CLI is available from the first-party Homebrew tap:

brew install ministryplace/tap/flowmark

Commands

example.txt

flowmark render [inputs...] [options]
flowmark check [inputs...] [--json]
flowmark ast [input] [--pretty]
flowmark graph [input] [--pretty]
flowmark format [inputs...] [--check | --write | --output file]
flowmark studio [inputs...] [--no-open] [--allow-write]
flowmark lsp --stdio
flowmark doctor [--json]
flowmark completions <bash|zsh|fish>

Inputs may be files, directories, quoted glob patterns, or - for source on stdin. Directories are searched recursively for .flowmark files in stable order, and duplicate matches are processed once. Options may appear before or after inputs.

Input discovery

flowmark check .
flowmark check "docs/**/*.flowmark" "examples/**/*.flowmark"
flowmark check docs/ --exclude "docs/drafts/**"
git ls-files "*.flowmark" | flowmark check --files-from -
cat architecture.flowmark | flowmark check --stdin-filename docs/architecture.flowmark

Flag	Purpose
--exclude pattern	exclude a Git-ignore-style pattern; repeat for more patterns
--ignore-file file	use a rules file other than the project-root .flowmarkignore
--files-from file||-	read additional input paths, one per line, from a file or stdin
--stdin-filename file	assign a logical path to diagram source read from stdin

With no input, a command reads piped diagram source. --files-from - explicitly changes stdin to a newline-delimited path list; blank lines and lines beginning with # are ignored.

render

flowmark render architecture.flowmark \
  --output architecture.svg \
  --theme light

Flag	Purpose
-o, --output	write SVG to a file; otherwise SVG goes to stdout
--out-dir dir	write one SVG per input under a directory
--output-template template	name batch outputs with {path}, {dir}, {name}, and {ext}
--theme name	select a built-in or project-defined theme
--profile name	select a named export profile from project config
--config file	use an explicit config instead of upward discovery
--theme-file file	load a deterministic JSON custom-property map
--live-theme	retain variables for an inline host; snapshot is the default
--background mode	use transparent or an explicit theme background
--embed-fonts	embed the bundled Inter font in the SVG
--print-safe	use a light snapshot, theme background, and print-safe settings

Diagnostics go to stderr so stdout can remain valid SVG. A failed render exits non-zero and does not emit a successful SVG. Multiple inputs require --out-dir or --output-template; the default {path}.svg template preserves input directories, and colliding destinations are rejected.

SVG output snapshots resolved theme variables by default, so it works in Finder, presentation software, desktop Markdown readers, and other hosts without Flowmark CSS. --live-theme prints a warning because that output intentionally depends on its inline host.

Project config and profiles

The CLI discovers flowmark.config.json by walking upward from the current directory. Command flags override profile values. A published JSON Schema is included with the CLI package:

data.json

{
  "$schema": "./node_modules/@ministryplace/flowmark-cli/schema/flowmark.config.schema.json",
  "version": 1,
  "defaultProfile": "paper",
  "themes": {
    "brand": {
      "--flow-accent": "#0057b8"
    }
  },
  "profiles": {
    "paper": {
      "theme": "light",
      "background": "theme",
      "embedFonts": true,
      "printSafe": true,
      "format": "svg"
    }
  }
}

The profile model reserves png and pdf formats for future exporters; this CLI version reports a usage error if either is requested.

check

flowmark check architecture.flowmark
flowmark check docs/ "examples/**/*.flowmark"
flowmark check architecture.flowmark --json

The default output writes human-readable diagnostics and a summary to stderr. --json writes a versioned machine-readable envelope containing every input and a batch summary to stdout. The command exits 1 when at least one diagnostic has severity error; warnings do not fail the command.

capabilities and analyze

flowmark capabilities --pretty
flowmark analyze architecture.flowmark --pretty
flowmark analyze diagrams/ --json

capabilities returns the versioned built-in language and renderer surface: diagram families, keywords, operators, semantic node kinds, shapes, icons, layout policies, presentation modes, and quality checks. The manifest declares registryScope: "built-in"; applications that register custom themes, icons, shapes, or node types own discovery of those host extensions.

analyze runs the real rendering pipeline without emitting SVG. Its versioned JSON envelope contains diagnostics plus rendered width, height, aspect ratio, node/edge counts, and algorithm versions for every resolved input. Errors exit 1. Human-readable quality warnings remain machine readable so CI or an agent can decide whether the artifact meets its destination-specific bar.

format

flowmark format architecture.flowmark --write
flowmark format diagrams/ --check
flowmark format diagrams/ --write
flowmark format input.flowmark --output formatted.flowmark
flowmark format - < input.flowmark

Without --write or --output, formatted source goes to stdout. --write replaces the input file and cannot be used with stdin. --check processes every resolved input and exits 1 if any source would change.

ast and graph

flowmark ast architecture.flowmark --pretty
flowmark graph architecture.flowmark --pretty

ast exposes parser output. graph exposes the compiled semantic model. Both write JSON to stdout, print diagnostics to stderr, and exit non-zero when errors are present. These commands are intended for tooling and debugging. Their versioned envelopes are stable transport contracts; the nested parser and graph data evolve with the corresponding public models.

Human output and environment checks

Human diagnostics include source frames, underlined ranges, diagnostic codes, and hints. Color is automatic for terminals and disabled for redirected output or NO_COLOR; override it with --color auto|always|never. --quiet suppresses summaries and progress, --verbose shows progress, and --debug adds stack traces to unexpected operational failures.

flowmark doctor checks the Node runtime, bundled font, discovered config, and SVG renderer. Add --json for its versioned machine envelope. flowmark completions bash|zsh|fish prints a completion script suitable for that shell’s normal completion directory.

Local authoring studio

flowmark studio architecture.flowmark
flowmark studio diagrams/ --no-open
flowmark studio architecture.flowmark --allow-write

Studio opens an offline browser workspace with Monaco editing, live SVG preview, diagnostics, layout and theme controls, graph inspection, synchronized source/graph selection, and SVG export. Files are watched, so external edits refresh the active document.

The server binds only to 127.0.0.1, uses a new unguessable session token, and restricts access to the resolved input roots. Browser writes are rejected unless --allow-write is supplied. The default is to open the browser; --no-open prints the authenticated URL without launching it. --port number selects a loopback port when a local integration requires one; otherwise the CLI chooses an available port.

The browser host consumes the versioned, browser-safe synchronization API published by @ministryplace/flowmark-studio. That package is for editor integrations; ordinary authors should launch Studio through the CLI.

Language server

flowmark lsp --stdio

The command speaks Language Server Protocol JSON-RPC over stdin/stdout. It supports document diagnostics, completion, hover, definition, references, rename, document symbols, folding ranges, semantic tokens, formatting, and code actions. Editors should launch it as a child process and must not mix human-readable output into the protocol stream.

The server, Studio’s Monaco host, flowmark check, and flowmark format share @ministryplace/flowmark-language-service. The public browser-compatible API is documented in the language service reference.

Global flags

example.txt

-h, --help       show usage
-v, --version    print the installed package version
--color mode     auto, always, or never
--quiet          suppress summaries and progress
--verbose        show progress details
--debug          show stack traces for operational failures

Unknown flags and missing option values exit with status 2. Operational or rendering failures exit with status 3. Source diagnostics and format-check differences exit with status 1. A successful command exits with status 0. stdout remains the data channel; diagnostics and human status remain on stderr.

For repeatable automation, see CI and automation.