Plantuml Sequence Diagram Commands: a Complete Guide with Examples

If you've ever needed to show how different parts of a system talk to each other how a user's browser sends a login request, how the server checks the database, and how it sends back a response sequence diagrams are the tool for the job. PlantUML lets you create these diagrams using plain text commands instead of dragging boxes around in a drawing tool. Learning the core PlantUML sequence diagram commands means you can version-control your diagrams alongside your code, update them in seconds, and share them without worrying about file formats.

What Exactly Is a PlantUML Sequence Diagram?

PlantUML is an open-source tool that generates UML diagrams from a simple text-based language. A sequence diagram in PlantUML shows the order of interactions between participants usually objects, services, or users over time. You write short commands, and PlantUML renders them into a visual diagram. The official PlantUML sequence diagram documentation covers the full specification, but the most common commands are straightforward once you see them in action.

How Do You Define Participants in a Sequence Diagram?

Every sequence diagram starts with declaring who's involved. PlantUML gives you several keywords for this:

participant – defines a regular participant (e.g., participant Browser)
actor – renders a stick-figure icon, useful for human users (e.g., actor User)
boundary, control, entity, collections – specialized participant shapes for architecture modeling

You can also rename and reorder participants:

participant "Web Server" as WS – gives a long name an alias
The order you declare participants controls their left-to-right position in the diagram

If you're working on sequence diagram code examples for software architecture, you'll see these participant declarations used heavily to map out real system components.

What Are the Basic Message Commands?

Messages are the arrows between participants. The syntax is simple:

A -> B : message – solid arrow (synchronous call)
A --> B : message – dashed arrow (return/response)
A ->> B : message – open arrowhead (async or less common notation)
A -->> B : message – dashed open arrowhead

A quick example:

User -> Server : GET /login

Server --> User : 200 OK

This draws a solid arrow from User to Server labeled "GET /login," then a dashed return arrow labeled "200 OK." For a deeper look at arrow styles and what each one means in UML, check the breakdown of UML sequence diagram message types and notation.

How Do You Add Notes, Delays, and Separators?

PlantUML offers several layout commands that make diagrams easier to read:

note left of A : text or note right of B : text – attaches a note to a participant
note over A,B : text – stretches a note across multiple participants
...some delay text... or just ... – adds a gap to show time passing
== Section Title == – adds a horizontal separator with a label
newpage – starts the diagram on a new page (useful for printing)

How Do You Show Loops, Conditions, and Grouped Interactions?

Real-world interactions involve logic. PlantUML uses grouping blocks to show this:

loop N times – repeats a section (e.g., loop 3 times)
alt success / else failure – shows conditional branches, like if/else
opt optional step – shows an optional interaction
par parallel actions – shows messages happening at the same time
critical must-complete block – highlights a critical section
break exit early – shows an early exit from a group

Each group starts with its keyword and ends with end. Here's a practical example:

alt login succeeds

Server --> Client : 200 OK

else login fails

Server --> Client : 401 Unauthorized

end

Can You Nest These Groups?

Yes. You can put a loop inside an alt, or an opt inside a par. Nesting is useful for modeling complex workflows like retry logic inside a conditional branch. Just make sure each opening keyword has a matching end.

How Do You Control Activation and Deactivation?

Activation bars show when a participant is actively processing a request. The commands are:

activate A – starts the activation bar on participant A
deactivate A – ends the bar

This is especially helpful when modeling call stacks like when a server calls a database, waits for a result, then returns data to the client. The activation bars make it obvious which components are "busy" at each step.

What About Referencing Other Diagrams and Creating Fragments?

PlantUML supports ref over A,B : description to show a reference to another interaction sequence. This keeps your diagrams from getting too crowded. You can also use box to visually group related participants:

box "Backend Services" #LightBlue
participant Auth
participant Database
end box

Common Mistakes When Writing PlantUML Sequence Commands

Forgetting the "end" keyword – Every alt, loop, opt, par, and critical block needs a closing end. Missing one will throw a syntax error or produce a broken diagram.
Declaring participants after using them – If you reference a participant in a message before declaring it, PlantUML may auto-create it in an unexpected order. Declare participants at the top.
Using the wrong arrow dash count – One dash (->) is solid; two dashes (-->) is dashed. Mixing these up changes the message semantics.
Making diagrams too large – A sequence diagram with 40 messages becomes hard to read. Split large flows into separate diagrams or use ref to reference sub-sequences.
Not using aliases for long names – Without aliases, long participant names crowd the diagram. Use participant "Long Service Name" as LSN.

What Useful Commands Do People Often Miss?

A few lesser-known commands can save you time:

autonumber – automatically numbers every message. Great for documentation and when you need to reference a specific step in a review.
hide footbox – removes the small activation boxes at the bottom of lifelines for a cleaner look.
skinparam – lets you customize colors, fonts, arrow styles, and more. For example, skinparam sequenceArrowColor #333.
title My Diagram Title – adds a title at the top of the rendered diagram.
header / footer – adds header and footer text, useful for page numbers or document IDs.

For a quick-reference version of these commands, the Mermaid sequence diagram cheatsheet also covers similar syntax patterns if you switch between tools.

How Do You Get Started Without Overthinking It?

You don't need to memorize every command. Start with the basics participants, arrows, and a few notes then add complexity as your diagram needs grow. Most sequence diagrams use only about eight to ten commands in total.

Here's a practical checklist to follow the next time you create a PlantUML sequence diagram:

List your participants – decide who's involved and declare them at the top with aliases if names are long.
Draw the happy path first – use -> and --> arrows to show the main success flow.
Add error or alternate paths – wrap them in alt/else/end or opt/end blocks.
Insert notes where helpful – explain non-obvious steps with note left or note right.
Turn on autonumber – add autonumber at the top so every step is easy to reference.
Review and split – if the diagram scrolls off the screen, break it into two diagrams or use ref over to reference a sub-sequence.