Command lineYou can run PlantUML using the command line. (See running for ways to run PlantUML from various other tools and workflows). The most basic way to run it is:
This will look for @startXYZ into file1 , file2 and file3 . For each diagram, a .png file will be created.
For processing a whole directory, you can use:
This command will search for @startXYZ and @endXYZ into .txt , .tex , .java , .htm , .html , .c , .h , .cpp , .apt , .pu , .puml , .hpp , .hh or .md files of the c:/directory1 and c:/directory2 directories.
Docker images are released as Github Packages and to Docker Hub.
You can also use wildcards :
|
Param name | Short param name | Output format | Comment |
-tpng
|
-png
|
PNG | Default |
-tsvg
|
-svg
|
SVG | Further details can be found here |
-teps
|
-eps
|
EPS | Further details can be found here |
-teps:text
|
-eps:text
|
EPS | This option keeps text as text |
-tpdf
|
-pdf
|
Further details can be found here | |
-tvdx
|
-vdx
|
VDX | Microsoft Visio Document |
-txmi
|
-xmi
|
XMI | Further details can be found here |
-tscxml
|
-scxml
|
SCXML | |
-thtml
|
-html
|
HTML | Alpha feature: do not use |
-ttxt
|
-txt
|
ATXT | ASCII art. Further details can be found here |
-tutxt
|
-utxt
|
UTXT | ASCII art using Unicode characters |
-tlatex
|
-latex
|
LATEX | Further details can be found here |
-tlatex:nopreamble
|
-latex:nopreamble
|
LATEX | Contains no LaTeX preamble creating a document |
-tbraille
|
-braille
|
PNG | Braille image [Ref. QA-4752] |
java -jar plantuml.jar yourdiagram.txt -ttxt
java -jar plantuml.jar -config "./config.cfg" dir1
-nometadata
to disable this functionality (To NOT export metadata in PNG/SVG generated files).-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.-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
Unfortunately this option works only with local files. It doesn't work with
-pipe
so you cannot fetch a URL with eg curl
and feed the PNG to PlantUML.
However, the Plantuml server has a similar feature, where it can get a PNG from a URL and extract its metadata.
-failfast
flag to change this behavior to stop diagram generations as soon as one error occurs. In that case, some diagrams will be generated, and some will not.
There is also a -failfast2
flag that does a first checking pass. If some error is present, no diagram will be generated at all. In case of error, -failfast2
runs even faster than -failfast
, which may be useful for huge project.
-stdrpt
(standard report) option, you can change the format of the error output of your PlantUML scripts.
With this option, a different error output of your diagram is possible:
-stdrpt
: single line-stdrpt:1
: verbose-stdrpt:2
: single linefile1.pu
, where as
is written aass
:
@startuml
participant "Famous Bob" aass Bob
@enduml
java -jar plantuml.jar file1.pu
The error output is:
Error line 2 in file: file1.pu
Some diagram description contains errors
java -jar plantuml.jar -stdrpt file1.pu
The error output is:
file1.pu:2:error:Syntax Error?
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
java -jar plantuml.jar -stdrpt:2 file1.pu
The error output is:
file1.pu:2:error:Syntax Error?
-pipe
option, you can easily use PlantUML in your scripts.
With this option, a diagram description is received through standard input and the PNG file is generated to standard output. No file is written on the local file system.
Example:
cat somefile.puml | java -jar plantuml.jar -pipe > somefile.png
The
-pipemap
option can be used to generate PNG map data (hyperlink rectangles) for use in HTML, eg:
cat somefile.puml | java -jar plantuml.jar -pipemap > somefile.map
The map file looks like this:
<map id="plantuml_map" name="plantuml_map">
<area shape="rect" id="id1" href="http://plantuml.com" title="http://plantuml.com"
alt="" coords="1,8,88,44"/>
</map>
Note: Also take a look at
-pipedelimitor
and -pipeNoStderr
to implement proper multiplexing of several PNG in a stream (in case the puml file contains multiple diagrams), and error handling.
java -jar plantuml.jar -help
This will output:
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.