DEV Community

Simon Brown
Simon Brown

Posted on

Getting started with the Structurizr CLI

In the previous post, we saw a quick introduction to the Structurizr DSL - an open source project that defines a diagramming tool agnostic way to model software architecture. This post will introduce the Structurizr CLI, another open source project that will take that DSL format, and help you render some diagrams.

Installing the CLI

The CLI is a small Spring Boot application, packaged as a ZIP file. To install it, download a release (v1.3.0 at this time), and unzip it into a directory of your choice. In order to run the CLI, you'll also need Java installed, and available on your command prompt.

Using the CLI

To use the CLI, open a terminal window, and change directory to the unzipped release folder. To test that everything is working, run the following command. For macOS/Linux:

./structurizr.sh
Enter fullscreen mode Exit fullscreen mode

And for Windows:

structurizr
Enter fullscreen mode Exit fullscreen mode

If successful, you should see something like this:

Structurizr CLI v1.3.0
Usage: structurizr push|pull|export [options]
Enter fullscreen mode Exit fullscreen mode

Before we look at some of the possible commands, let's create a DSL file to work with. Create a new text file in the same folder as the Structurizr CLI, named getting-started.dsl, with the following content.

workspace {

    model {
        user = person "User" "A user of my software system."
        softwareSystem = softwareSystem "Software System" "My software system."

        user -> softwareSystem "Uses"
    }

    views {
        systemContext softwareSystem {
            include *
            autoLayout
        }
    }

}
Enter fullscreen mode Exit fullscreen mode

Creating a PlantUML diagram

Now that we have a software architecture model, let's create a PlantUML diagram. On macOS/Linux:

./structurizr.sh export -workspace getting-started.dsl -format plantuml
Enter fullscreen mode Exit fullscreen mode

And on Windows:

structurizr export -workspace getting-started.dsl -format plantuml
Enter fullscreen mode Exit fullscreen mode

If successful, you should see output like the following:

Exporting workspace from getting-started.dsl
 - loading workspace from DSL
 - no styles or themes defined; creating default styles
 - writing .../structurizr-SoftwareSystem-SystemContext.puml
 - finished
Enter fullscreen mode Exit fullscreen mode

That .puml file is a PlantUML definition, and should look like this:

@startuml(id=SoftwareSystem-SystemContext)
title Software System - System Context

skinparam {
  shadowing false
  arrowFontSize 10
  defaultTextAlignment center
  wrapWidth 200
  maxMessageSize 100
}
hide stereotype
top to bottom direction
skinparam rectangle<<1>> {
  BackgroundColor #08427b
  FontColor #ffffff
  BorderColor #052E56
}
skinparam rectangle<<2>> {
  BackgroundColor #1168bd
  FontColor #ffffff
  BorderColor #0B4884
  roundCorner 20
}
rectangle "==User\n<size:10>[Person]</size>\n\nA user of my software system." <<1>> as 1
rectangle "==Software System\n<size:10>[Software System]</size>\n\nMy software system." <<2>> as 2
1 .[#707070].> 2 : "Uses"
@enduml
Enter fullscreen mode Exit fullscreen mode

If you copy/paste this into the online PlantUML server, you should see a diagram like this:

PlantUML diagram

Creating a Mermaid diagram

If we change the -format CLI option from plantuml to mermaid, we'll get a .mmd file created instead, the contents of which we can then copy/paste into the online Mermaid editor to get a diagram as follows:

Mermaid diagram

Creating a Structurizr diagram

The CLI can also be used to push the software architecture model to the Structurizr cloud service. If you'd like to try this, follow Structurizr - Getting started to sign up for a free Structurizr account, and create a workspace. You'll need your workspace ID, API key and secret, all of which can be found on your dashboard (see Structurizr - Workspaces for information about finding these).

With the CLI, you can use the push command as follows. For macOS/Linux:

./structurizr.sh push -id WORKSPACE_ID -key KEY -secret SECRET -workspace getting-started.dsl
Enter fullscreen mode Exit fullscreen mode

And Windows:

structurizr push -id WORKSPACE_ID -key KEY -secret SECRET -workspace getting-started.dsl
Enter fullscreen mode Exit fullscreen mode

When you open the diagram editor/viewer, you should see a diagram like this:

Structurizr diagram

Summary

This blog post introduced the Structurizr CLI, which can be used to create software architecture diagrams in different formats when used in conjunction with the Structurizr DSL.

Top comments (3)

Collapse
 
lktslionel profile image
Lionel T.

Great article!

It will be great to have guidelines on how to organize and compose diagrams in a folder. So that, we can import individual xxx.dslfiles in a main one, and then generate a diagram per view of the system (Context, Container, Component, ...)

Not to forget an example to show how to export a diagram that uses themes.

Thanks for sharing these great articles.
Take care

Collapse
 
marnutux profile image
Minor Arrieta Rojas
Collapse
 
lktslionel profile image
Lionel T.

Thanks for sharing. I use `includeˋ already but I need real world examples and guidelines of how to organize those files.