mermaid-cli Documentation

File: README.md Copy Chapter

mermaid-cli

This is a command-line interface (CLI) for mermaid. It takes a mermaid definition file as input and generates an SVG/PNG/PDF file as output.

Installation Copy Chapter

npm install @mermaid-js/mermaid-cli

Usage Copy Chapter

Convert Mermaid mmd Diagram File To SVG

mmdc -i input.mmd -o output.svg

Note

See Alternative installations if you don't want to install the package globally.

Locate how to call the mmdc executable for your preferred method
i.e. Docker, Yarn, NPM, local install, etc.

Examples Copy Chapter

Create A PNG With A Dark Theme And Transparent Background Copy Section

mmdc -i input.mmd -o output.png -t dark -b transparent

Animating an SVG file with custom CSS Copy Section

The --cssFile option can be used to inline some custom CSS.

Please see ./test-positive/flowchart1.css for an example of a CSS file that has animations.

Warning: If you want to override mermaid's themeCSS, we recommend instead adding {"themeCSS": "..."}) to your mermaid --configFile. You may also need to use !important to override mermaid's themeCSS.

Warning: Inline CSS files may be blocked by your browser, depending on the HTTP Content-Security-Policy header of the website that hosts your SVG.

mmdc --input test-positive/flowchart1.mmd --cssFile test-positive/flowchart1.css -o docs/animated-flowchart.svg

Example output: docs/animated-flowchart.svg

Transform a markdown file with mermaid diagrams Copy Section

mmdc -i readme.template.md -o readme.md

This command transforms a markdown file itself. The mermaid-cli will find the mermaid diagrams, create SVG files from them and refer to those in the markdown output.

This:

### Some markdown

```mermaid
graph
   [....]
```

### Some more markdown

```mermaid
sequenceDiagram
   [....]
```

### Mermaid with custom title/desc

```mermaid
graph
   accTitle: My title here
   accDescr: My description here
   A-->B
```

Becomes:

### Some markdown



### Some more markdown



### Mermaid with custom title/desc

Piping from stdin Copy Section

You can easily pipe input from stdin. This example shows how to use a heredoc to
send a diagram as stdin to mermaid-cli (mmdc).

cat << EOF  | mmdc --input -
    graph TD
    A[Client] --> B[Load Balancer]
EOF

See All Available Options Copy Section

mmdc -h

Alternative installations

Use Docker/Podman: Copy Chapter

docker pull minlag/mermaid-cli

or pull from Github Container Registry

docker pull ghcr.io/mermaid-js/mermaid-cli/mermaid-cli

or e.g. version 8.8.0

docker pull minlag/mermaid-cli:8.8.0

The container looks for input files in /data. So for example, if you have a
diagram defined on your system in /path/to/diagrams/diagram.mmd, you can use
the container to generate an SVG file as follows:

docker run --rm -u `id -u`:`id -g` -v /path/to/diagrams:/data minlag/mermaid-cli -i diagram.mmd

Or, if using Podman, instead do:

podman run --userns keep-id --user ${UID} --rm -v /path/to/diagrams:/data:z ghcr.io/mermaid-js/mermaid-cli/mermaid-cli -i diagram.mmd

The key differences in the podman command versus the docker command are:

• The addition of the --userns keep-id argument. This allows the container to keep the same UID as the current user's UID in the container namespace instead of mapping to a subuid. To learn more, see the userns=mode documentation.
• The addition of :z to the end of the volume mapping. This instructs podman to relabel the files in the volume with the SELinux label container_file_t, which allows processes in the container to access the files. See the "Labeling Volume Mounts" section of podman-run (1) for more info.

In previous version, the input files were mounted in /home/mermaidcli. You can
restore this behaviour with the --workdir option:

docker run [...] --workdir=/home/mermaidcli minlag/mermaid-cli [...]

Use Node.JS API Copy Chapter

It's possible to call mermaid-cli via a Node.JS API.
Please be aware that the NodeJS API is not covered by semver, as mermaid-cli follows
mermaid's versioning.

import { run } from "@mermaid-js/mermaid-cli";

await run(
    "input.mmd",
    "output.svg", // {optional options},
);

Install locally Copy Chapter

Some people are having issues
installing this tool globally. Installing it locally is an alternative solution:

npm install @mermaid-js/mermaid-cli
./node_modules/.bin/mmdc -h

Run with npx Copy Section

npx is installed by default with NPM. It
downloads and runs commands at the same time. To use Mermaid CLI with npx, you
need to use the -p flag because the package name is different than the command
it installs (mmdc). npx -p @mermaid-js/mermaid-cli mmdc -h

Install with [brew](https://brew.sh) Copy Chapter

Warning

This method of installation is no longer supported.
For more details, see the discussion.
An old version of mermaid-cli can be installed with brew.

sh Copy

brew install mermaid-cli

Known issues Copy Chapter

1. Linux sandbox issue
2. Docker permission denied issue
3. How to setup up mermaid to use already installed chromium?

For contributors Copy Chapter

Contributions are welcome. See the contribution guide.

File: docs/already-installed-chromium.md Copy Chapter

The text below is taken from Issue #331.

If you run mermaid-cli with the --help flag, there's an option for --puppeteerConfigFile, which is a JSON configuration file for puppeteer.

These are options passed to puppeteer.launch.

The useful options for you are:

• executablePath Path to a browser executable to use instead of the bundled Chromium. Note that Puppeteer is only guaranteed to work with the bundled Chromium, so use this setting at your own risk. You may find https://github.com/puppeteer/puppeteer/blob/main/versions.js useful to see which versions of Chrome are compatible with versions of puppeteer.
• product (in case you want to use firefox instead of chrome)
• timeout can be used to increase/decrease timeout before puppeteer throws an error

You'll probably want a file called puppeteerConfigFile.json with contents:

{
    "executablePath": "C:\\path\\to\\your\\chrome.exe"
}

Then run mermaid-cli with option mmdc --puppeteerConfigFile puppeteerConfigFile.json.

You might also be able to do the same thing with environment variables by following: https://pptr.dev/#environment-variables.

Btw, if you set PUPPETEER_SKIP_DOWNLOAD=1 as an env variable when running yarn install or npm install, it should skip downloading CHROMIUM too.

File: docs/docker-permission-denied.md Copy Chapter

When running the Docker image with Docker or Podman you get the following error:

› podman run -it -v "$(pwd)":/data:z minlag/mermaid-cli -i /data/diagram.mmd
node:fs:582
  handleErrorFromBinding(ctx);
  ^

Error: EACCES: permission denied, open '/data/diagram.mmd.svg'
    at Object.openSync (node:fs:582:3)
    at Object.writeFileSync (node:fs:2143:35)
    at /home/mermaidcli/node_modules/@mermaid-js/mermaid-cli/index.bundle.js:169:10
    at Generator.next (<anonymous>)
    at step (/home/mermaidcli/node_modules/@mermaid-js/mermaid-cli/index.bundle.js:4:191)
    at /home/mermaidcli/node_modules/@mermaid-js/mermaid-cli/index.bundle.js:4:361
    at processTicksAndRejections (node:internal/process/task_queues:96:5) {
  errno: -13,
  syscall: 'open',
  code: 'EACCES',
  path: '/data/diagram.mmd.svg'
}

You can solve this issue by using docker -u option with your UID:

docker run -u $UID -it --rm -v "$(pwd)":data minlag/mermaid-cli -i /data/diagram.mmd

The issue is described in issue #140

File: docs/linux-sandbox-issue.md Copy Chapter

(node:8281) UnhandledPromiseRejectionWarning: Error: Failed to launch chrome!
[0416/092218.828861:ERROR:zygote_host_impl_linux.cc(88)] Running as root without --no-sandbox is not supported. See https://crbug.com/638180.

(node:8191) UnhandledPromiseRejectionWarning: Error: Failed to launch chrome!
[0416/091938.210735:FATAL:zygote_host_impl_linux.cc(124)] No usable sandbox! Update your kernel or see https://chromium.googlesource.com/chromium/src/+/master/docs/linux_suid_sandbox_development.md for more information on developing with the SUID sandbox. If you want to live dangerously and need an immediate workaround, you can try using --no-sandbox.

First and foremost, you should not run as root and you should upgrade your Linux kernel to latest version.

But if you don't want to follow the advice above and just want to disable sandbox, here you go:

Create a puppeteer-config.json file:

{
    "args": ["--no-sandbox"]
}

And when you invoke mmdc:

mmdc -p puppeteer-config.json ...

File: docs/reviewing.md Copy Chapter

Reviewing a PR

Running Percy Visual Inspection tests from a PR from a fork Copy Chapter

In order to run Percy visual inspection tests, a PR from a fork may have to
be brought into the main repo.

This is because uploading to Percy requires a GitHub Secret token, which cannot
be accessed from forks for security reasons.

After you have reviewed the work, and made sure there is no security exploit
(e.g. no echo "$TOKEN"), then you can run the following to get percy working:

git switch -c "<NAME_OF_YOUR_BRANCH>"
git pull "https://github.com/<NAME_OF_YOUR_USERNAME>/mermaid-cli.git" "<NAME_OF_YOUR_BRANCH>"
# Make sure the commit hash matches the commit hash of the PR you reviewed
git log --max-count=1
git push [email protected]:mermaid-js/mermaid-cli.git "<NAME_OF_YOUR_BRANCH>"

After pushing, CI should re-run on that commit, and Percy should show up on the
PR after a few minutes, as long as both branches have the same commit hash.