PlantUML Advanced usage Command line

       

Edit in DokuwikiEdit in AsciidocEdit in Markdown

命令行

java -jar plantuml.jar file1 file2 file3

java -jar plantuml.jar "c:/directory1" "c:/directory2"

docker run ghcr.io/plantuml/plantuml

Edit in DokuwikiEdit in AsciidocEdit in Markdown

New command-line interface (beta)

• The new options follow consistent naming and structure.
• The legacy options will still be supported for a transition period, but they will no longer be documented.

plantuml - generate diagrams from plain text

Usage:
  java -jar plantuml.jar [options] [file|dir]...
  java -jar plantuml.jar [options] --gui

Description:
  Process PlantUML sources from files, directories (optionally recursive), or stdin (-pipe).

Wildcards (for files/dirs):
  *   any characters except '/' and '\'
  ?   exactly one character except '/' and '\'
  **  any characters across directories (recursive)
  Tip: quote patterns to avoid shell expansion (e.g., "**/*.puml").

General:
 -h, --help ....................... Show this help
     --help-more .................. Show extended help (advanced options)
     --version .................... Show PlantUML and Java version
     --author ..................... Show information about PlantUML authors
     --gui ........................ Launch the graphical user interface
     --dark-mode .................. Render diagrams in dark mode
 -v, --verbose .................... Enable verbose logging
     --duration ................... Print total processing time
     --progress-bar ............... Show a textual progress bar
     --splash-screen .............. Show splash screen with progress bar
     --check-graphviz ............. Check Graphviz installation
     --http-server[:<port>] ....... Start internal HTTP server for rendering (default port : 4242)

Input & preprocessing:
 -p, --pipe ....................... Read source from stdin, write result to stdout
 -D<var>=<value>,
     --define <VAR>=<value> ....... Define a preprocessing variable (equivalent to '!define <var> <value>')
 -I<file>,
     --include <file> ............. Include external file (as with '!include <file>')
 -P<key>=<value>,
     --pragma <key>=<value> ....... Set pragma (equivalent to '!pragma <key> <value>')
 -S<key>=<value>,
     --skinparam <key>=<value> .... Set skin parameter (equivalent to 'skinparam <key> <value>')
     --theme <name> ............... Apply a theme
     --config <file> .............. Specify configuration file
     --charset <name> ............. Use a specific input charset

Execution control:
     --check-syntax ............... Check diagram syntax without generating images
     --stop-on-error .............. Stop at the first syntax error
     --check-before-run ........... Pre-check syntax of all inputs and stop faster on error
     --no-error-image ............. Do not generate error images for diagrams with syntax errors
     --graphviz-timeout <seconds>   Set Graphviz processing timeout (in seconds)
     --threads <n|auto> ........... Use <n> threads for processing  (auto = available processors)

Metadata & assets:
     --extract-source ............. Extract embedded PlantUML source from PNG or SVG metadata
     --disable-metadata ........... Do not include metadata in generated files
     --skip-fresh ................. Skip PNG/SVG files that are already up-to-date (using metadata)
     --sprite <4|8|16[z]> <file> .. Encode a sprite definition from an image file
     --obfuscate .................. Obfuscate diagram texts for secure sharing
     --encode-url ................. Generate an encoded PlantUML URL from a source file
     --decode-url <string> ........ Decode a PlantUML encoded URL back to its source
     --list-keywords .............. Print the list of PlantUML language keywords
     --dot-path <path-to-dot-exe>   Specify the path to the Graphviz 'dot' executable
     --ftp-server ................. Start a local FTP server for diagram rendering (rarely used)

Output control:
     --output-dir <dir> ........... Generate output files in the specified directory
     --overwrite .................. Allow overwriting of read-only output files
     --exclude <pattern> .......... Exclude input files matching the given pattern

Output format (choose one):
     --format <name>, -f <name> ... Set the output format for generated diagrams
                                    (e.g. png, svg, pdf, eps, latex, txt, utxt)

Available formats:
     --eps ........................ Generate images in EPS format
     --html ....................... Generate HTML files for class diagrams
     --latex ...................... Generate LaTeX/TikZ output
     --latex-nopreamble ........... Generate LaTeX/TikZ output without preamble
     --pdf ........................ Generate PDF images
     --png ........................ Generate PNG images (default)
     --scxml ...................... Generate SCXML files for state diagrams
     --svg ........................ Generate SVG images
     --txt ........................ Generate ASCII art diagrams
     --utxt ....................... Generate ASCII art diagrams using Unicode characters
     --vdx ........................ Generate VDX files
     --xmi ........................ Generate XMI files for class diagrams
     -preproc ..................... Output preprocessor text of diagrams

Statistics:
     --disable-stats .............. Disable statistics collection (default behavior)
     --enable-stats ............... Enable statistics collection
     --export-stats-html .......... Export collected statistics to an HTML report and exit
     --export-stats ............... Export collected statistics to a text report and exit
     --html-stats ................. Output general statistics in HTML format
     --xml-stats .................. Output general statistics in XML format
     --realtime-stats ............. Generate statistics in real time during processing
     --loop-stats ................. Continuously print usage statistics during execution


Examples:
  # Process all .puml recursively
  java -jar plantuml.jar "**/*.puml"

  # Check syntax only (CI)
  java -jar plantuml.jar --check-syntax src/diagrams

  # Read from stdin and write to stdout (SVG)
  cat diagram.puml | java -jar plantuml.jar --svg -pipe > out.svg

  # Encode a sprite from an image
  java -jar plantuml.jar --sprite 16z myicon.png

  # Use a define
  java -jar plantuml.jar -DAUTHOR=John diagram.puml

  # Change output directory
  java -jar plantuml.jar --format svg --output-dir out diagrams/

Exit codes:
  0   Success
  >0  Error (syntax error or processing failure)

See also:
  java -jar plantuml.jar --help-more
  Documentation: https://plantuml.com

Edit in DokuwikiEdit in AsciidocEdit in Markdown

通配符

• 对于单个字符，用 ?
• 对于零个或多个字符, 用 *
• 对于零个或多个字符, (包括 / 或 \), 用一对 **

java -jar plantuml.jar "dummy*/*.cpp"

java -jar plantuml.jar "dummy*/**.cpp"

Edit in DokuwikiEdit in AsciidocEdit in Markdown

排除文件

java -jar plantuml.jar -x "**/common/**" -x "**/test/Test*" "dummy*/**/*.cpp"

Edit in DokuwikiEdit in AsciidocEdit in Markdown

输出目录

java -jar plantuml.jar -o "c:/outputPng" "c:/directory2"

• 绝对路径: 将使用唯一的输出目录，在其中生成所有图像
• 相对路径: 将在文件树中使用多个输出目录。

Edit in DokuwikiEdit in AsciidocEdit in Markdown

Types of Output File

java -jar plantuml.jar yourdiagram.txt --txt

Edit in DokuwikiEdit in AsciidocEdit in Markdown

配置文件

java -jar plantuml.jar -config "./config.cfg" dir1

Edit in DokuwikiEdit in AsciidocEdit in Markdown

Metadata

• It is possible to retrieve this source with the -metadata option. This means that the PNG is almost "editable": you can post it on a corporate wiki where you cannot install plugins, and someone in the future can update the diagram by getting the metadata, editing and re-uploading again. Also, the diagram is stand-alone.
• Conversely, the -checkmetadata option checks whether the target PNG has the same source and if there are no changes, doesn't regenerate the PNG, thus saving all processing time. This allows you to run PlantUML on a whole folder (or tree with the -recursive option) incrementally.

  java -jar plantuml.jar -metadata diagram.png > diagram.puml

Edit in DokuwikiEdit in AsciidocEdit in Markdown

退出代码

Edit in DokuwikiEdit in AsciidocEdit in Markdown

Standard report [stdrpt]

• none: two lines
• -stdrpt: single line
• -stdrpt:1: verbose
• -stdrpt:2: single line

@startuml
participant "Famous Bob" aass Bob
@enduml

Without any option

java -jar plantuml.jar file1.pu

The error output is:

Error line 2 in file: file1.pu
Some diagram description contains errors

-stdrpt option

java -jar plantuml.jar -stdrpt file1.pu

The error output is:

file1.pu:2:error:Syntax Error?

-stdrpt:1 option

java -jar plantuml.jar -stdrpt:1 file1.pu

The error output is:

protocolVersion=1
status=ERROR
lineNumber=2
label=Syntax Error?
Error line 2 in file: file1.pu
Some diagram description contains errors

-stdrpt:2 option (like -stdrpt)

java -jar plantuml.jar -stdrpt:2 file1.pu

The error output is:

file1.pu:2:error:Syntax Error?

Edit in DokuwikiEdit in AsciidocEdit in Markdown

标准输入输出

type somefile.txt | java -jar plantuml.jar -pipe > somefile.png

Edit in DokuwikiEdit in AsciidocEdit in Markdown

帮助

java -jar plantuml.jar -help

Usage: java -jar plantuml.jar [options] -gui
        (to execute the GUI)
    or java -jar plantuml.jar [options] [file/dir] [file/dir] [file/dir]
        (to process files or directories)

You can use the following wildcards in files/dirs:
        *       means any characters but '\'
        ?       one and only one character but '\'
        **      means any characters (used to recurse through directories)

where options include:
    -darkmode           To use dark mode for diagrams
    -gui                To run the graphical user interface
    -tpng               To generate images using PNG format (default)
    -tsvg               To generate images using SVG format
    -teps               To generate images using EPS format
    -tpdf               To generate images using PDF format
    -tvdx               To generate images using VDX format
    -txmi               To generate XMI file for class diagram
    -tscxml             To generate SCXML file for state diagram
    -thtml              To generate HTML file for class diagram
    -ttxt               To generate images with ASCII art
    -tutxt              To generate images with ASCII art using Unicode characters
    -tlatex             To generate images using LaTeX/Tikz format
    -tlatex:nopreamble  To generate images using LaTeX/Tikz format without preamble
    -o[utput] "dir"     To generate images in the specified directory
    -DVAR1=value        To set a preprocessing variable as if '!define VAR1 value' were used
    -Sparam1=value      To set a skin parameter as if 'skinparam param1 value' were used
    -Ppragma1=value     To set pragma as if '!pragma pragma1 value' were used
    -I\path\to\file     To include file as if '!include file' were used
    -I\path\to\*.puml   To include files with pattern
    -theme xxx          To use a specific theme
    -charset xxx        To use a specific charset (default is windows-1251)
    -e[x]clude pattern  To exclude files that match the provided pattern
    -metadata           To retrieve PlantUML sources from PNG images
    -nometadata         To NOT export metadata in PNG/SVG generated files
    -checkmetadata              Skip PNG files that don't need to be regenerated
    -version            To display information about PlantUML and Java versions
    -v[erbose]          To have log information
    -quiet              To NOT print error message into the console
    -debugsvek          To generate intermediate svek files
    -h[elp]             To display this help message
    -testdot            To test the installation of graphviz
    -graphvizdot "exe"  To specify dot executable
    -p[ipe]             To use stdin for PlantUML source and stdout for PNG/SVG/EPS generation
    -encodesprite 4|8|16[z] "file"      To encode a sprite at gray level (z for compression) from an image
    -computeurl|-encodeurl      To compute the encoded URL of a PlantUML source file
    -decodeurl          To retrieve the PlantUML source from an encoded URL
    -syntax             To report any syntax error from standard input without generating images
    -language           To print the list of PlantUML keywords
    -checkonly          To check the syntax of files without generating images
    -failfast           To stop processing as soon as a syntax error in diagram occurs
    -failfast2          To do a first syntax check before processing files, to fail even faster
    -noerror            To skip images when error in diagrams
    -duration           To print the duration of complete diagrams processing
    -nbthread N         To use (N) threads for processing
    -nbthread auto      To use 4 threads for processing
    -timeout N          Processing timeout in (N) seconds. Defaults to 15 minutes (900 seconds).
    -author[s]          To print information about PlantUML authors
    -overwrite          To allow to overwrite read only files
    -printfonts         To print fonts available on your system
    -enablestats        To enable statistics computation
    -disablestats       To disable statistics computation (default)
    -htmlstats          To output general statistics in file plantuml-stats.html
    -xmlstats           To output general statistics in file plantuml-stats.xml
    -realtimestats      To generate statistics on the fly rather than at the end
    -loopstats          To continuously print statistics about usage
    -splash             To display a splash screen with some progress bar
    -progress           To display a textual progress bar in console
    -pipeimageindex N   To generate the Nth image with pipe option
    -stdlib             To print standard library info
    -extractstdlib      To extract PlantUML Standard Library into stdlib folder
    -filedir xxx        To behave as if the PlantUML source is in this dir (only affects '-pipe' and PicoWeb 'POST /render')
    -filename "example.puml"    To override %filename% variable
    -preproc            To output preprocessor text of diagrams
    -cypher             To cypher texts of diagrams so that you can share them
    -picoweb            To start internal HTTP Server. See https://plantuml.com/picoweb

If needed, you can setup the environment variable GRAPHVIZ_DOT.