Getting started with the Structurizr CLI
Tags: architecture, productivity
Published: 2020-07-06 14:26:06

---
title: Getting started with the Structurizr CLI
published: true
description: 
tags: #architecture #productivity
series: Software architecture diagrams as text
//cover_image: 
---

In [the previous post](https://dev.to/simonbrown/getting-started-with-the-structurizr-dsl-34dh), 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](https://github.com/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](https://github.com/structurizr/cli/releases) (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
```

And for Windows:

```
structurizr
```

If successful, you should see something like this:

```
Structurizr CLI v1.3.0
Usage: structurizr push|pull|export [options]
```

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
        }
    }

}
```

## 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
```

And on Windows:

```
structurizr export -workspace getting-started.dsl -format plantuml
```

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
```

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
```

If you copy/paste this into the [online PlantUML server](http://www.plantuml.com/plantuml/uml/ZP5DQzj048Rl-oi6vz8UuagBavXWYtpGtW85j_GGvx3sZkGbkpjcTeJZblpthYohk265IY0jxxupptpS934iRV0Vd9qlg9QTOLpias0uxt_t50LVvACI9nvXy41_2-V3uUXJAZsxk3Li0lnI06bZBErSRA0sFc5M33FjlcJtmlr4A8iiMQnDw-LRZh_rhea1ey0wVv0Lm8xDzeUpiW5TTEvWNXum9TDWdo6BhshZB48IP2JPRr49RK48LYH20QnZN8kZU59TfvZOU9pDogew57jdriyDKnljFNbYE2kc4tsrKW1TlKUjFZoTczWY3yuB_VdYKhs-3z3_0fJbvNHb_mjmDvbE9razXdD41jsr_eS3e_dyUq9UnbdAaxakY-hnAtAY-3Jxr2dLCYxZBRJP0rH3s4CQrfaEMnoFe9-6IL3-dVZDuayPRwvEOG_l8tIFqAg4yUFPLT6zJ-CAD5p3ABUGHke6ess3_mq0), you should see a diagram like this:

 ![PlantUML diagram](https://dev-to-uploads.s3.amazonaws.com/i/y8nle1mgusvshclx57h4.png)

## 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](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiZ3JhcGggVEJcbiAgbGlua1N0eWxlIGRlZmF1bHQgZmlsbDojZmZmZmZmXG4gIDFbXCI8ZGl2IHN0eWxlPSdmb250LXdlaWdodDogYm9sZCc-VXNlcjwvZGl2PjxkaXYgc3R5bGU9J2ZvbnQtc2l6ZTogNzAlOyBtYXJnaW4tdG9wOiAwcHgnPltQZXJzb25dPC9kaXY-PGRpdiBzdHlsZT0nZm9udC1zaXplOiA4MCU7IG1hcmdpbi10b3A6MTBweCc-QSB1c2VyIG9mIG15IHNvZnR3YXJlIHN5c3RlbS48L2Rpdj5cIl1cbiAgc3R5bGUgMSBmaWxsOiMwODQyN2Isc3Ryb2tlOiMwNTJlNTYsY29sb3I6I2ZmZmZmZlxuICAyKFwiPGRpdiBzdHlsZT0nZm9udC13ZWlnaHQ6IGJvbGQnPlNvZnR3YXJlIFN5c3RlbTwvZGl2PjxkaXYgc3R5bGU9J2ZvbnQtc2l6ZTogNzAlOyBtYXJnaW4tdG9wOiAwcHgnPltTb2Z0d2FyZSBTeXN0ZW1dPC9kaXY-PGRpdiBzdHlsZT0nZm9udC1zaXplOiA4MCU7IG1hcmdpbi10b3A6MTBweCc-TXkgc29mdHdhcmUgc3lzdGVtLjwvZGl2PlwiKVxuICBzdHlsZSAyIGZpbGw6IzExNjhiZCxzdHJva2U6IzBiNDg4NCxjb2xvcjojZmZmZmZmXG4gIDEtLiBcIjxkaXY-VXNlczwvZGl2PjxkaXYgc3R5bGU9J2ZvbnQtc2l6ZTogNzAlJz48L2Rpdj5cIiAuLT4yXG4iLCJtZXJtYWlkIjp7InRoZW1lIjoiZGVmYXVsdCIsInNlY3VyaXR5TGV2ZWwiOiJsb29zZSJ9fQ) to get a diagram as follows:

 ![Mermaid diagram](https://dev-to-uploads.s3.amazonaws.com/i/41cw6a46oekfb7s3g49l.png)

## Creating a Structurizr diagram

The CLI can also be used to push the software architecture model to the [Structurizr cloud service](https://structurizr.com). If you'd like to try this, follow [Structurizr - Getting started](https://structurizr.com/help/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](https://structurizr.com/help/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
```

And Windows:

```
structurizr push -id WORKSPACE_ID -key KEY -secret SECRET -workspace getting-started.dsl
```

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

![Structurizr diagram](https://dev-to-uploads.s3.amazonaws.com/i/7xr71p95hp0inv2cg3jo.png)

## Summary

This blog post introduced the [Structurizr CLI](https://github.com/structurizr/cli), which can be used to create software architecture diagrams in different formats when used in conjunction with the [Structurizr DSL](https://github.com/structurizr/dsl).