Quick Start

Check Environment

We can perform a environment check using the following command:

plantumlcli -c

In plantumlcli, the available environments can be categorized into local environments and remote environments, as follows:

• Local Environments: Environments based on Java (both Oracle JDK and OpenJDK are supported) and the local plantuml.jar package. UML diagram generation is achieved by invoking the java -jar plantuml.jar command.

• Remote Environments: Environments based on the plantuml-server and the official PlantUML website. UML images are obtained by accessing their APIs, and the images are generated remotely and loaded into the local environment.

In the current environment, we are only connected to a docker-based plantuml-server. The inspection results are as follows:

Local plantuml not detected or has problem.
Error : ValueError('Plantuml jar file not given.')
Remote plantuml detected.
PlantUML Server Version 1202306
Remote host : http://localhost:18080
Connection time : 0.020s

Export Diagrams From Code

Here is one example plantuml code in file common.puml.

@startuml
hide empty description

state "Idle" as idle
state "Ringing" as ringing
state "Dialing" as dialing
state "Calling" as calling

[*] -> idle : power on
idle -> [*] : power off

idle -> ringing : incoming call
ringing -> calling : pick up

idle -> dialing : outgoing call
dialing -> calling : be answered
dialing -> idle : nobody

calling -down-> idle : hang up
@enduml

Export to ASCII Arts

Some very simple UML diagrams can be viewed directly in the command line using ASCII art. For example, the following code for helloworld.puml:

@startuml
Bob -> Alice : hello
@enduml

Enter the following command:

plantumlcli -T helloworld.puml

You will see:

helloworld.puml: 
     ┌───┐          ┌─────┐
     │Bob│          │Alice│
     └─┬─┘          └──┬──┘
       │    hello      │   
       │──────────────>│   
     ┌─┴─┐          ┌──┴──┐
     │Bob│          │Alice│
     └───┘          └─────┘

Export to PNG Image

Convert the code to PNG image with the following command

plantumlcli -t png -o common.dat.png common.puml

And this is the common.dat.png:

Export to SVG Image

Convert the code to SVG image with the following command

plantumlcli -t svg -o common.dat.svg common.puml

And this is the common.dat.svg:

Export to EPS Image

Convert the code to EPS image with the following command

plantumlcli -t eps -o common.dat.eps common.puml

And this is the common.dat.eps.

Warning

The EPS format has been deprecated and is no longer widely supported in many applications, so it is not recommended to continue using it. If you need to use vector graphics in LaTeX, it is recommended to use the PDF format. If you need to import vector graphics into Microsoft Office software, it is recommended to use the SVG format.

Export to PDF Image

Convert the code to PDF image with the following command

plantumlcli -t pdf -o common.dat.pdf common.puml

And this is the common.dat.pdf.

Note

If you need to convert it to PDF format, you will need to install plantumlcli[pdf] like this:

pip install plantumlcli[pdf]

More Details

You can see the help information with

plantumlcli --help

And this is the help information for plantumlcli

Usage: plantumlcli [OPTIONS] [SOURCES]...

Options:
  -v, --version                   Show package's version information.
  -j, --java TEXT                 Path of java executable file (will load from
                                  environment when not given).  [default:
                                  (java from ${PATH})]
  -p, --plantuml TEXT             Path of plantuml jar file (will load from
                                  ${PLANTUML_JAR} when not given).
  -r, --remote-host TEXT          Remote host of the online plantuml editor
                                  (will load from ${PLANTUML_HOST} when not
                                  given).  [default:
                                  http://www.plantuml.com/plantuml]
  -L, --use-local                 Use local plantuml only.
  -R, --use-remote                Use remote plantuml only.
  -c, --check                     Check usable plantuml.
  -u, --url                       Print url of remote plantuml resource
                                  (ignore -L and -R).
  --homepage-url                  Print url of remote plantuml editor (ignore
                                  -L, -R and -u).
  -t, --type [TXT|PNG|SVG|EPS|PDF]
                                  Type of plantuml resource. (Attention that
                                  the PDF format is only natively supported by
                                  few versions of plantuml-server. Please
                                  install 'plantumlcli[pdf]' and Cairo
                                  environment to make sure the export to PDF
                                  can be processed.)  [default: PNG]
  -T, --text                      Display text uml graph by stdout (ignore
                                  -t).
  -o, --output TEXT               Paths of output files (relative path
                                  supported, based on output dir in -O).
  -O, --output-dir DIRECTORY      Base path for outputting files.  [default:
                                  (current path)]
  -n, --concurrency INTEGER       Concurrency when running plantuml.
                                  [default: 2]
  -h, --help                      Show this message and exit.