# Mermaid.js CLI Usage

Command-line interface for converting Mermaid diagrams to SVG/PNG/PDF.

## Installation

**Global Install:**
```bash
npm install -g @mermaid-js/mermaid-cli
```

**Local Install:**
```bash
npm install @mermaid-js/mermaid-cli
./node_modules/.bin/mmdc -h
```

**No Install (npx):**
```bash
npx -p @mermaid-js/mermaid-cli mmdc -h
```

**Docker:**
```bash
docker pull ghcr.io/mermaid-js/mermaid-cli/mermaid-cli
```

**Requirements:** Node.js ^18.19 || >=20.0

## Basic Commands

**Convert to SVG:**
```bash
mmdc -i input.mmd -o output.svg
```

**Convert to PNG:**
```bash
mmdc -i input.mmd -o output.png
```

**Convert to PDF:**
```bash
mmdc -i input.mmd -o output.pdf
```

Output format determined by file extension.

## CLI Flags

**Core Options:**
- `-i, --input <file>` - Input file (use `-` for stdin)
- `-o, --output <file>` - Output file path
- `-t, --theme <name>` - Theme: default, dark, forest, neutral
- `-b, --background <color>` - Background: transparent, white, #hex
- `--cssFile <file>` - Custom CSS for styling
- `--configFile <file>` - Mermaid configuration file
- `-h, --help` - Show all options

**Example with All Options:**
```bash
mmdc -i diagram.mmd -o output.png \
  -t dark \
  -b transparent \
  --cssFile custom.css \
  --configFile mermaid-config.json
```

## Advanced Usage

**Stdin Piping:**
```bash
cat diagram.mmd | mmdc --input - -o output.svg

# Or inline
cat << EOF | mmdc --input - -o output.svg
graph TD
  A[Start] --> B[End]
EOF
```

**Batch Processing:**
```bash
for file in *.mmd; do
  mmdc -i "$file" -o "${file%.mmd}.svg"
done
```

**Markdown Files:**
Process markdown with embedded diagrams:
```bash
mmdc -i README.template.md -o README.md
```

## Docker Workflows

**Basic Docker Usage:**
```bash
docker run --rm \
  -u $(id -u):$(id -g) \
  -v /path/to/diagrams:/data \
  ghcr.io/mermaid-js/mermaid-cli/mermaid-cli \
  -i diagram.mmd -o output.svg
```

**Mount Working Directory:**
```bash
docker run --rm -v $(pwd):/data \
  ghcr.io/mermaid-js/mermaid-cli/mermaid-cli \
  -i /data/input.mmd -o /data/output.png
```

**Podman (with SELinux):**
```bash
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
```

## Configuration Files

**Mermaid Config (JSON):**
```json
{
  "theme": "dark",
  "look": "handDrawn",
  "fontFamily": "Arial",
  "flowchart": {
    "curve": "basis"
  }
}
```

**Usage:**
```bash
mmdc -i input.mmd --configFile config.json -o output.svg
```

**Custom CSS:**
```css
.node rect {
  fill: #f9f;
  stroke: #333;
}
.edgeLabel {
  background-color: white;
}
```

**Usage:**
```bash
mmdc -i input.mmd --cssFile styles.css -o output.svg
```

## Node.js API

**Programmatic Usage:**
```javascript
import { run } from '@mermaid-js/mermaid-cli';

await run('input.mmd', 'output.svg', {
  theme: 'dark',
  backgroundColor: 'transparent'
});
```

**With Options:**
```javascript
import { run } from '@mermaid-js/mermaid-cli';

await run('diagram.mmd', 'output.png', {
  theme: 'forest',
  backgroundColor: '#ffffff',
  cssFile: 'custom.css',
  configFile: 'config.json'
});
```

## Common Workflows

**Documentation Generation:**
```bash
# Convert all diagrams in docs/
find docs/ -name "*.mmd" -exec sh -c \
  'mmdc -i "$1" -o "${1%.mmd}.svg"' _ {} \;
```

**Styled Output:**
```bash
# Create dark-themed transparent diagrams
mmdc -i architecture.mmd -o arch.png \
  -t dark \
  -b transparent \
  --cssFile animations.css
```

**CI/CD Pipeline:**
```yaml
# GitHub Actions example
- name: Generate Diagrams
  run: |
    npm install -g @mermaid-js/mermaid-cli
    mmdc -i docs/diagram.mmd -o docs/diagram.svg
```

**Accessibility-Enhanced:**
```bash
# Diagrams with accTitle/accDescr preserved
mmdc -i accessible-diagram.mmd -o output.svg
```

## Troubleshooting

**Permission Issues (Docker):**
Use `-u $(id -u):$(id -g)` to match host user permissions.

**Large Diagrams:**
Increase Node.js memory:
```bash
NODE_OPTIONS="--max-old-space-size=4096" mmdc -i large.mmd -o out.svg
```

**Validation:**
Check syntax before rendering:
```bash
mmdc -i diagram.mmd -o /dev/null || echo "Invalid syntax"
```