0
# Mermaid CLI
1

2
Mermaid CLI is a command-line interface for converting Mermaid diagram definitions into various output formats including SVG, PNG, and PDF. It provides both a CLI tool (`mmdc`) and a Node.js API for programmatic usage, supporting single diagrams, batch processing of markdown files, and extensive customization options.
3

4
## Package Information
5

6
- **Package Name**: @mermaid-js/mermaid-cli
7
- **Package Type**: npm
8
- **Language**: JavaScript (ESM) with TypeScript support
9
- **Installation**: `npm install -g @mermaid-js/mermaid-cli`
10

11
## Core Imports
12

13
```javascript
14
import { run, renderMermaid, cli, error } from "@mermaid-js/mermaid-cli";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { run, renderMermaid, cli, error } = require("@mermaid-js/mermaid-cli");
21
```
22

23
## Basic Usage
24

25
### CLI Usage
26

27
```bash
28
# Basic diagram conversion
29
mmdc -i diagram.mmd -o diagram.svg
30

31
# Convert with dark theme and transparent background
32
mmdc -i input.mmd -o output.png -t dark -b transparent
33

34
# Process markdown file with embedded mermaid diagrams
35
mmdc -i README.md -o README-processed.md
36

37
# Pipe from stdin
38
cat diagram.mmd | mmdc -i - -o output.svg
39
```
40

41
### Node.js API Usage
42

43
```javascript
44
import { run } from "@mermaid-js/mermaid-cli";
45

46
// Convert single diagram
47
await run("diagram.mmd", "output.svg");
48

49
// Convert with options
50
await run("input.mmd", "output.png", {
51
  outputFormat: "png",
52
  parseMMDOptions: {
53
    backgroundColor: "transparent",
54
    mermaidConfig: { theme: "dark" }
55
  }
56
});
57
```
58

59
## Architecture
60

61
Mermaid CLI is built around several key components:
62

63
- **CLI Interface**: Command-line tool (`mmdc`) with comprehensive option parsing and validation
64
- **Core Engine**: Uses Puppeteer to render diagrams in a headless browser environment
65
- **Format Support**: Converts to SVG, PNG, and PDF with configurable styling options
66
- **Batch Processing**: Processes markdown files containing multiple mermaid code blocks
67
- **Node.js API**: Programmatic interface for integration into Node.js applications
68

69
## Capabilities
70

71
### Command Line Interface
72

73
Complete CLI tool for converting Mermaid diagrams with extensive customization options including themes, styling, and output formats.
74

75
```bash { .api }
76
mmdc [options]
77

78
Options:
79
  -i, --input <input>              Input mermaid file or "-" for stdin
80
  -o, --output [output]            Output file or "-" for stdout
81
  -e, --outputFormat [format]      Output format: svg, png, pdf
82
  -t, --theme [theme]              Theme: default, forest, dark, neutral
83
  -b, --backgroundColor [color]    Background color for PNG/SVG
84
  -w, --width [width]              Page width (default: 800)
85
  -H, --height [height]            Page height (default: 600)
86
  -s, --scale [scale]              Puppeteer scale factor (default: 1)
87
  -c, --configFile [file]          JSON configuration file for mermaid
88
  -C, --cssFile [file]             CSS file for styling
89
  -I, --svgId [id]                 SVG element ID attribute
90
  -f, --pdfFit                     Scale PDF to fit chart
91
  -a, --artefacts [path]           Output artefacts path for markdown input
92
  -p, --puppeteerConfigFile [file] JSON configuration for Puppeteer
93
  -q, --quiet                      Suppress log output
94
  --iconPacks <icons...>           Icon packs to use (Iconify NPM packages)
95
```
96

97
[Command Line Interface](./cli.md)
98

99
### Node.js API
100

101
Programmatic interface for rendering Mermaid diagrams within Node.js applications, supporting both high-level operations and fine-grained control.
102

103
```javascript { .api }
104
async function run(
105
  input: string | undefined,
106
  output: string,
107
  options?: RunOptions
108
): Promise<void>;
109

110
async function renderMermaid(
111
  browser: Browser | BrowserContext,
112
  definition: string,
113
  outputFormat: "svg" | "png" | "pdf",
114
  options?: ParseMDDOptions
115
): Promise<RenderResult>;
116

117
interface RunOptions {
118
  puppeteerConfig?: LaunchOptions;
119
  quiet?: boolean;
120
  outputFormat?: "svg" | "png" | "pdf";
121
  parseMMDOptions?: ParseMDDOptions;
122
  artefacts?: string;
123
}
124

125
interface RenderResult {
126
  title: string | null;
127
  desc: string | null;
128
  data: Uint8Array;
129
}
130
```
131

132
[Node.js API](./nodejs-api.md)
133

134
## Types
135

136
```javascript { .api }
137
// Puppeteer types used by the API
138
interface Browser {
139
  // Puppeteer browser instance
140
  close(): Promise<void>;
141
  newPage(): Promise<Page>;
142
}
143

144
interface BrowserContext {
145
  // Puppeteer browser context instance
146
  close(): Promise<void>;
147
  newPage(): Promise<Page>;
148
}
149

150
interface LaunchOptions {
151
  // Puppeteer launch configuration
152
  headless?: boolean | "shell";
153
  args?: string[];
154
  timeout?: number;
155
  executablePath?: string;
156
  [key: string]: any;
157
}
158

159
interface Viewport {
160
  width: number;
161
  height: number;
162
  deviceScaleFactor?: number;
163
}
164

165
interface ParseMDDOptions {
166
  viewport?: Viewport;
167
  backgroundColor?: string | "transparent";
168
  mermaidConfig?: object;
169
  myCSS?: string;
170
  pdfFit?: boolean;
171
  svgId?: string;
172
  iconPacks?: string[];
173
}
174

175
interface MarkdownImageProps {
176
  url: string;
177
  alt: string;
178
  title?: string | null;
179
}
180
```