CLI reference

Sigla ships a command-line tool, mdv, alongside the app. The brew cask also installs two aliases: sigla (forward-looking name) and mdview (legacy, 12-month sunset). All three share the same binary and behave identically; mdview additionally prints a one-line deprecation notice.

This is the complete CLI surface.

Binary names

Name	Status	Notes
`mdv`	Canonical	Installed by the brew cask, always present
`sigla`	Alias	Installed by the brew cask; forward-looking name
`mdview`	Sunset alias	Installed by the brew cask; prints “deprecated, use mdv”

All examples below use mdv. Substitute sigla or mdview freely.

Synopsis

mdv [file ...]
mdv help | --help | -h
mdv --version | -v
mdv skill list
mdv skill extract [<name>] [<dest>] [--force] [--quiet]
mdv export <input.md> [flags]

The first non-flag argument is the verb. Anything that doesn’t match a known verb falls through to the legacy file-launch path.

Verbs

File launch (default)

mdv                           # Launch or activate Sigla
mdv README.md                 # Open a file
mdv doc1.md doc2.md           # Open multiple files
mdv ~/projects/notes/         # Open a folder as a workspace

Resolves each argument as a filesystem path, verifies it exists, then asks LaunchServices to open it with Sigla. If Sigla is already running, the file opens in the running instance.

Path resolution: tildes are expanded; relative paths are resolved against the current working directory.

`help`, `--help`, `-h`

Prints usage and exits.

`--version`, `-v`

Prints mdv <version> and exits.

$ mdv --version
mdv 0.5.0

`skill list`

Prints every bundled Claude skill, one per line. Sorted.

$ mdv skill list
plugin-dev
sigla

Useful for xargs-style scripts or for discovering what’s shipped without opening the app bundle.

`skill extract [<name>] [<dest>] [--force] [--quiet]`

Copies one of Sigla’s bundled Claude skills into a destination directory, ready to be loaded by Claude Code or any other Claude-skill-aware tool.

Argument / flag	Default	Notes
`<name>`	`sigla`	Which bundled skill to extract — see `mdv skill list`
`<dest>`	`~/.claude/skills/<name>/`	Destination directory
`--force`	off	Overwrite if `<dest>` already exists
`--quiet`	off	Suppress non-error stderr

mdv skill extract                          # sigla → ~/.claude/skills/sigla/
mdv skill extract plugin-dev               # plugin-dev → ~/.claude/skills/plugin-dev/
mdv skill extract plugin-dev ./local-skill # custom destination
mdv skill extract --force                  # overwrite existing

Which skill should I extract?

sigla — using Sigla. CLI, settings, fence-label resolution, scheme handlers, bundled-extension inventory. The right pick for everyday driving.
plugin-dev — building extensions. Full sigla.json schema, security model, debugging playbook, distribution. Extract this when you’re authoring a template- or process-kind renderer.

A bare path (anything with / or starting with .) is treated as <dest> for the default sigla skill, preserving v0.5.0 invocations.

Exit codes:

Code	Meaning
`0`	Success
`1`	Destination exists and `--force` was not passed
`2`	Argument error
`3`	Sigla.app bundle not found, or named skill doesn’t exist (the error lists available names)

Skills ship inside the signed app bundle. Source-of-truth lives at Sigla.app/Contents/Resources/Skills/<name>/.

`export <input.md> [flags]`

Renders a Markdown document to PDF (default), HTML, or sidecar diagram images — byte-for-byte equivalent to what the GUI’s ⌘⇧P produces for the same input and options. Designed for make, CI, and headless Claude Code subagent use.

mdv export input.md                               # PDF → input.pdf in cwd
mdv export input.md --to html                     # HTML → input.html in cwd
mdv export input.md -o report.html                # Format inferred from extension
mdv export input.md --emit-diagrams ./assets/     # PDF + sidecar diagram images
mdv export input.md --no-document --emit-diagrams ./assets/   # Diagrams only
mdv export - -o report.pdf                        # Stdin → PDF
mdv export input.md -o -                          # PDF → stdout
mdv export input.md --json                        # Structured JSON output
mdv export input.md --no-extensions               # Hard-disable every extension

Flags

Flag	Default	Meaning
`<input>`	—	Source Markdown file, or `-` for stdin
`--to <format>`	`pdf`	Primary output format: `pdf` \| `html`
`--output <path>`, `-o`	`<input-basename>.<fmt>` in cwd	Output file path, or `-` for stdout
`--emit-diagrams <dir>`	(off)	Write each rendered diagram as a standalone image file into `<dir>`. Creates the directory if absent
`--no-document`	off	Skip the primary output (PDF/HTML); requires `--emit-diagrams`
`--diagram-format <map>`	`*=png`	Per-extension format preference: `mermaid=png,plantuml=svg,*=png`
`--force`	off	Overwrite existing output files without error
`--json`	off	Emit a single JSON object to stdout instead of human-readable progress
`--theme <id>`	`gitHub`	Document theme (PDF only): `gitHub` \| `technical` \| `appleDocs`
`--paper <size>`	`letter`	Paper size (PDF only): `letter` \| `a4`
`--orientation <o>`	`portrait`	Page orientation (PDF only): `portrait` \| `landscape`
`--header "<text>"`	none	Running header text (PDF only)
`--no-footer`	off	Suppress the running footer (PDF only)
`--start-h1-new-page`	off	Every top-level H1 starts on a fresh page (PDF only)
`--no-extensions`	off	Hard-disable every extension; fenced blocks fall back to `<pre><code>`
`--extension <id>[,<id>...]`	(all loaded)	Allowlist — only listed extensions run; principle of least privilege for CI
`--quiet`	off	Suppress non-error stderr

--no-extensions and --extension are mutually exclusive in spirit (the kill overrides the allowlist).

Without --force, writing to an existing file exits with code 1 and leaves the file unchanged.

--no-document without --emit-diagrams is an argument error (code 2).

Diagram sidecar filenames follow the convention {input-basename}-diagram-{n}-{extension-id}.{ext}, or {input-basename}-{name}-{extension-id}.{ext} when a name= slug appears in the fence info-string.

`--json` output schema

When --json is passed, stdout receives a single JSON object and all human-readable progress is suppressed:

{
  "schema": "mdv-export/v1",
  "input_sha256": "<64 hex chars>",
  "primary_output": "/abs/path/to/output.pdf",
  "sidecars": ["/abs/path/to/doc-diagram-1-mermaid.png"]
}

Exit codes:

Code	Meaning
`0`	Success
`1`	Input file not found, unreadable, or output exists without `--force`
`2`	Argument error
`3`	Sigla.app bundle not found
`4`	Export generation failed

The same PDF pagination contract the GUI uses applies: images, tables, short code blocks, and diagrams are never split across pages. Very long code blocks fall back to splitting (no amount of padding helps there). See PDF export.

Deprecated: `md-to-pdf`

mdv md-to-pdf is a hidden alias for mdv export retained for one minor version. It accepts the same flags as the v0.5.0 md-to-pdf verb, rewrites them to mdv export equivalents, prints a deprecation notice to stderr, and exits normally. The alias will be removed in v0.6.0 — migrate to mdv export now.

Environment variables

`MDV_APP_PATH`

Absolute path to the Sigla.app bundle the CLI should drive. Wins over the default probe order.

export MDV_APP_PATH=/Users/me/build/Sigla.app
mdv ./test.md

If the path doesn’t exist, the CLI prints a warning to stderr and falls back to the probe order.

`SIGLA_BINARY_<ID_UPPER>`

Overrides the binary path for a process-kind extension. The id is upper-cased, hyphens become underscores:

Extension id	Variable
`plantuml`	`SIGLA_BINARY_PLANTUML`
`graphviz`	`SIGLA_BINARY_GRAPHVIZ`
`my-tool`	`SIGLA_BINARY_MY_TOOL`

SIGLA_BINARY_PLANTUML=/usr/local/opt/plantuml/bin/plantuml mdv ./diagram.md

The override is prepended to the manifest’s binary.search array — it doesn’t replace the search list, so a typo still falls through to a known good location.

`XDG_CONFIG_HOME`

If set, custom themes and user extensions live under $XDG_CONFIG_HOME/sigla/ instead of ~/.config/sigla/. Respected by both the app and the CLI.

How the CLI finds Sigla.app

For verbs that need the app bundle (file launch, skill extract, export), the CLI probes in this order:

MDV_APP_PATH environment variable (if set; warned if missing)
/Applications/Sigla.app (brew cask default)
~/Applications/Sigla.app (per-user install)
Bundle ID resolution via LaunchServices (com.slantedt.sigla)

If all four fail, file-launch falls back gracefully to LaunchServices; skill extract and export exit with code 3.

Exit code summary

Verb	0	1	2	3	4
File launch	success	file not found	—	—	—
`skill extract`	success	dest exists (no `--force`)	arg error	bundle not found	—
`export`	success	input not found / output exists (no `--force`)	arg error	bundle not found	export generation failed

Notes on packaging

In the Mac App Store (sandboxed) build of Sigla, the CLI doesn’t ship — the sandbox doesn’t allow installing executables into the user’s PATH. skill extract and export are brew-only features.

The brew distribution is not sandboxed and includes the CLI by default.

Cross-references

PDF export — the same export pipeline mdv export drives; PDF-specific knobs documented there
Extensions overview — --no-extensions and --extension semantics
Extensions — authoring — SIGLA_BINARY_* override mechanism

CLI reference

Binary names

Synopsis

Verbs

File launch (default)

help, --help, -h

--version, -v

skill list

skill extract [<name>] [<dest>] [--force] [--quiet]

export <input.md> [flags]