Structurizr CLI

https://github.com/structurizr/cli
Admin
Structurizr CLI is a command-line interface for managing architecture diagrams, documentation, and...
Tokens:33,082
Snippets:267
Trust Score:9.5
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Usage example for Version (Java)

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/Version.md

Usage example for the Version class: instantiate it and print the build number, build timestamp, and git commit. The VersionCommand uses getBuildNumber() to report the CLI version.

```java
import com.structurizr.cli.util.Version;

Version version = new Version();
System.out.println("Build: " + version.getBuildNumber());
System.out.println("Built: " + version.getBuildTimestamp());
System.out.println("Commit: " + version.getGitCommit());
```

--------------------------------

### Usage example: write export to disk

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/DslWorkspaceExport.md

Shows how to write the export to a file using the file extension from getFileExtension() and the definition from getDefinition().

```java
import com.structurizr.cli.export.DslWorkspaceExport;
import java.nio.file.Files;
import java.nio.file.Path;

DslWorkspaceExport export = new DslWorkspaceExport("workspace { model { } }");
Path out = Path.of("workspace." + export.getFileExtension());
Files.writeString(out, export.getDefinition());
```

--------------------------------

### Usage example for DateUtils

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/DateUtils.md

Demonstrates how to use DateUtils to get the current time, remove milliseconds, and format the result.

```java
import com.structurizr.cli.util.DateUtils;
import java.util.Date;

Date now = DateUtils.getNow();
Date truncated = DateUtils.removeMilliseconds(now);
System.out.println(DateUtils.formatIsoDate(truncated)); // e.g. 2023-12-29T13:33:22Z
```

--------------------------------

### Usage example: create export and print extension and definition

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/DslWorkspaceExport.md

Shows how to instantiate DslWorkspaceExport with a DSL definition and access its file extension and definition.

```java
import com.structurizr.cli.export.DslWorkspaceExport;

DslWorkspaceExport export = new DslWorkspaceExport("workspace { ... }");
System.out.println(export.getFileExtension()); // "dsl"
System.out.println(export.getDefinition());    // workspace { ... }
```

--------------------------------

### Basic CLI invocation via launcher script

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/StructurizrCliApplication.md

Run the CLI with a command and its options using the launcher script. The example shows the 'validate' command with a workspace file.

```bash
# run the CLI with a command and its options
./structurizr.sh validate -workspace workspace.dsl
```

--------------------------------

### getBuildTimestamp method (Java)

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/Version.md

Returns the parsed build.timestamp as a Date, or the JVM start time if unavailable.

```java
public Date getBuildTimestamp()
```

--------------------------------

### Usage example: checking PREVIEW_FEATURES flag

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/Configuration.md

Shows how to conditionally enable preview-only behavior by checking the Configuration.PREVIEW_FEATURES constant. The constant is hard-coded to false, so this branch will not execute unless the value is changed and the project rebuilt.

```java
import com.structurizr.cli.Configuration;

if (Configuration.PREVIEW_FEATURES) {
    // enable preview-only behavior
}
```

--------------------------------

### Usage example: creating and using JsonWorkspaceExport

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/JsonWorkspaceExport.md

Shows how to instantiate JsonWorkspaceExport with a JSON definition and call getFileExtension() and getDefinition().

```java
import com.structurizr.cli.export.JsonWorkspaceExport;

JsonWorkspaceExport export = new JsonWorkspaceExport("{\"id\": 1}");
System.out.println(export.getFileExtension()); // "json"
System.out.println(export.getDefinition());    // {"id": 1}
```

--------------------------------

### Error handling for unknown command

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/StructurizrCliApplication.md

Running an unknown command produces exit code 1 and a usage message. The example shows the command and the resulting error and usage output.

```bash
./structurizr.sh frobnicate -workspace workspace.dsl
# Error: frobnicate not recognised
# Usage: structurizr push|pull|lock|unlock|export|merge|validate|inspect|list|version|help [options]
# (exit code 1)
```

--------------------------------

### CLI export command with theme format

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/JsonWorkspaceThemeExporter.md

Command-line usage of the export command with -format theme, which writes a file named <workspace-name>-theme.json. The example shows the command and the expected output file.

```bash
./structurizr.sh export -workspace workspace.dsl -format theme -output out
# writes out/workspace-theme.json
```

--------------------------------

### Usage example: asserting PREVIEW_FEATURES is false in tests

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/Configuration.md

Demonstrates how to reference the public static final constant from tests to assert the current feature-flag state. The constant is inlined at compile time, so changing it requires a rebuild.

```java
import static org.junit.jupiter.api.Assertions.assertFalse;
import com.structurizr.cli.Configuration;

assertFalse(Configuration.PREVIEW_FEATURES);
```

--------------------------------

### Catch StructurizrCliException in consumer code

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/StructurizrCliException.md

Example of catching StructurizrCliException in consumer code. The catch block prints the exception message and exits with status 1. The comment shows an example message for a missing workspace file.

```java
import com.structurizr.cli.AbstractCommand;
import com.structurizr.cli.StructurizrCliException;

public class MyCommand extends AbstractCommand {

    @Override
    public void run(String... args) throws Exception {
        try {
            loadWorkspace("missing.dsl");
        } catch (StructurizrCliException e) {
            // e.getMessage() == "/abs/path/missing.dsl does not exist"
            System.err.println(e.getMessage());
            System.exit(1);
        }
    }
}
```

--------------------------------

### General RuntimeException catch handler

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/StructurizrCliException.md

Because StructurizrCliException extends RuntimeException, it is also caught by generic RuntimeException handlers. This example demonstrates a catch-all for runtime failures.

```java
try {
    loadWorkspace("workspace.dsl");
} catch (RuntimeException e) {
    // catches StructurizrCliException and any other runtime failure
}
```

--------------------------------

### Run the help command

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/commands.md

Executes the `help` command using the Structurizr CLI script. It prints the usage line and exits with code 0.

```bash
./structurizr.sh help
```

--------------------------------

### run(String... args)

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/StructurizrCliApplication.md

Programmatic entry point for the Structurizr CLI. Accepts command name and options as arguments.

```APIDOC
## run(String... args)

### Description
Programmatic entry point for the Structurizr CLI. Accepts command name and options as arguments.

### Method
run

### Signature
`public void run(String... args)`

### Parameters
- **args** (String[]) - Required - Command name followed by options. For example: `"export", "-workspace", "workspace.dsl", "-format", "plantuml", "-output", "diagrams"`

### Usage Example
```java
import com.structurizr.cli.StructurizrCliApplication;

public class Main {
    public static void main(String[] args) {
        // args[0] is the command name, e.g. "export"
        new StructurizrCliApplication().run(
            "export",
            "-workspace", "workspace.dsl",
            "-format", "plantuml",
            "-output", "diagrams"
        );
    }
}
```

### Exit Codes
- **0** - A registered command completed and returned normally
- **1** - No arguments, unknown command, or any exception thrown during command execution

### Error Handling
If an unknown command name is provided, exit code `1` is returned and a usage message is printed.

```bash
./structurizr.sh frobnicate -workspace workspace.dsl
# Error: frobnicate not recognised
# Usage: structurizr push|pull|lock|unlock|export|merge|validate|inspect|list|version|help [options]
# (exit code 1)
```
```

--------------------------------

### Basic programmatic export using JsonWorkspaceThemeExporter

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/JsonWorkspaceThemeExporter.md

Shows how to instantiate JsonWorkspaceThemeExporter and call export on a Workspace, then print the file extension and definition. The workspace is expected to be loaded from DSL or JSON.

```java
import com.structurizr.Workspace;
import com.structurizr.cli.export.JsonWorkspaceThemeExporter;
import com.structurizr.export.WorkspaceExport;

Workspace workspace = ...; // loaded from DSL or JSON
JsonWorkspaceThemeExporter exporter = new JsonWorkspaceThemeExporter();
WorkspaceExport export = exporter.export(workspace);

System.out.println(export.getFileExtension()); // "json"
System.out.println(export.getDefinition());    // theme JSON
```

--------------------------------

### AbstractCommand run method (abstract)

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/AbstractCommand.md

Executes the command. Each concrete command parses its own Apache Commons CLI Options from args and performs its work. Throws Exception on parse errors or I/O failures; many implementations also call System.exit(1) directly.

```java
public abstract void run(String... args) throws Exception
```

--------------------------------

### Run version command

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/commands.md

Invokes the `version` command with no options. Logs the CLI build number, the Structurizr Java version, Java runtime details, and OS details. Always exits with code 0.

```bash
./structurizr.sh version
```

--------------------------------

### structurizr.sh version command (bash)

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/Version.md

Command and sample output for the version command, showing the CLI version reported via getBuildNumber().

```bash
./structurizr.sh version
# structurizr-cli: 2023.12.29.0
# structurizr-java: 5.0.2
# Java: 17.0.x/... (...)
# OS: ...
```

--------------------------------

### Migrate cloud workspaces to on-premises

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/commands.md

Migrates all workspaces from a Structurizr cloud account to an on-premises directory layout. Requires an API key; optionally specify a username and output directory. The command fails if the output directory already exists.

```bash
./structurizr.sh cloud-to-onpremises -key APIKEY -user admin@example.com -o ./onprem-export
```

--------------------------------

### Run list command with workspace file

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/commands.md

Invokes the `list` command with a workspace DSL file. Prints an indented hierarchy of canonical names for people, software systems, containers, components, and deployment nodes. Exits with code 0 on success, 1 on parse or load failure.

```bash
./structurizr.sh list -workspace workspace.dsl
```

--------------------------------

### Constructor with message parameter

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/StructurizrCliException.md

Package-private constructor that takes a message string and delegates it to RuntimeException(String). It is used internally by AbstractCommand.loadWorkspace when throwing the exception. Consumers cannot call this constructor directly.

```java
StructurizrCliException(String message)
```

--------------------------------

### AbstractCommand loadWorkspace method

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/AbstractCommand.md

Loads a workspace from a JSON or DSL source, which may be a local file path or an http:// or https:// URL. This is the single loading path used by every command. Throws StructurizrCliException for file issues or missing workspace definition, and Exception for scope validation or parse errors.

```java
protected Workspace loadWorkspace(String workspacePathAsString) throws Exception
```

--------------------------------

### Basic programmatic export usage

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/JsonWorkspaceExporter.md

Shows how to instantiate JsonWorkspaceExporter and export a workspace programmatically. The resulting WorkspaceExport provides the file extension 'json' and the pretty-printed JSON definition.

```java
import com.structurizr.Workspace;
import com.structurizr.cli.export.JsonWorkspaceExporter;
import com.structurizr.export.WorkspaceExport;

Workspace workspace = ...; // loaded from DSL or JSON
JsonWorkspaceExporter exporter = new JsonWorkspaceExporter();
WorkspaceExport export = exporter.export(workspace);

System.out.println(export.getFileExtension()); // "json"
System.out.println(export.getDefinition());    // pretty-printed JSON
```

--------------------------------

### StructurizrCliApplication class declaration

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/StructurizrCliApplication.md

Shows the class declaration with command constants and the static COMMANDS map. The static initializer (not shown) configures Log4j2 and populates the map with one instance per command.

```java
public class StructurizrCliApplication {
    private static final Log log;
    private static final String PUSH_COMMAND = "push";
    private static final String PULL_COMMAND = "pull";
    private static final String CLOUD_TO_ONPREMISES_COMMAND = "cloud-to-onpremises";
    private static final String LOCK_COMMAND = "lock";
    private static final String UNLOCK_COMMAND = "unlock";
    private static final String EXPORT_COMMAND = "export";
    private static final String MERGE_COMMAND = "merge";
    private static final String VALIDATE_COMMAND = "validate";
    private static final String INSPECT_COMMAND = "inspect";
    private static final String LIST_COMMAND = "list";
    private static final String VERSION_COMMAND = "version";
    private static final String HELP_COMMAND = "help";
    private static final Map<String,AbstractCommand> COMMANDS = new HashMap<>();
    // static initializer: configures Log4j2 console appender, then
    // COMMANDS.put(...) for each of the 12 commands
}
```

--------------------------------

### Validate workspace with Structurizr CLI

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/commands.md

Runs the validate command on a workspace DSL file. Loads the workspace, round-trips it through JSON serialization/deserialization, and verifies all themes are accessible over HTTP. Exits with code 0 on success, 1 on any failure.

```bash
./structurizr.sh validate -workspace workspace.dsl
```

--------------------------------

### Version class declaration (Java)

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/Version.md

Shows the Version class declaration with its static fields and static initializer that loads build.properties. The static initializer parses build.timestamp using SimpleDateFormat; on failure, defaults are kept: version="", buildTimestamp=new Date(), gitCommit=null.

```java
public class Version {

    private static final String BUILD_VERSION_KEY = "build.number";
    private static final String BUILD_TIMESTAMP_KEY = "build.timestamp";
    private static final String GIT_COMMIT_KEY = "git.commit";

    private static String version = "";
    private static Date buildTimestamp = new Date();
    private static String gitCommit;

    static {
        // loads build.properties from the classpath; on failure prints the
        // stack trace and keeps the defaults above
    }
}
```

--------------------------------

### export(Workspace workspace)

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/JsonWorkspaceThemeExporter.md

Serializes the workspace's theme to JSON and returns a WorkspaceExport. It calls ThemeUtils.toJson(workspace) and wraps the result in a JsonWorkspaceExport. Throws RuntimeException if serialization fails.

```APIDOC
## export(Workspace workspace)

### Description
Serializes the workspace's theme to JSON and returns a WorkspaceExport. It calls ThemeUtils.toJson(workspace) and wraps the result in a JsonWorkspaceExport. Unlike JsonWorkspaceExporter, it does not serialize the model or views — only the theme.

### Method
`export`

### Signature
```java
public WorkspaceExport export(Workspace workspace)
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `workspace` | `Workspace` | yes | — | The workspace whose theme is serialized |

### Returns
`WorkspaceExport` — a `JsonWorkspaceExport` whose definition is the theme JSON and whose file extension is `json`.

### Throws
`RuntimeException` — wraps any exception from `ThemeUtils.toJson`.

### Example
```java
import com.structurizr.Workspace;
import com.structurizr.cli.export.JsonWorkspaceThemeExporter;
import com.structurizr.export.WorkspaceExport;

Workspace workspace = ...; // loaded from DSL or JSON
JsonWorkspaceThemeExporter exporter = new JsonWorkspaceThemeExporter();
WorkspaceExport export = exporter.export(workspace);

System.out.println(export.getFileExtension()); // "json"
System.out.println(export.getDefinition());    // theme JSON
```
```

--------------------------------

### Basic diagram export (PlantUML)

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/ExportCommand.md

Exports a workspace to PlantUML format, writing diagram files to the specified output directory. The output includes .puml files with -key and frame variants.

```bash
./structurizr.sh export -workspace workspace.dsl -format plantuml -output diagrams
# writes diagrams/structurizr-<id>-<viewKey>.puml (+ -key and frame variants)
```

--------------------------------

### Configuration class declaration with PREVIEW_FEATURES constant

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/Configuration.md

The entire Configuration class, containing the public static final boolean PREVIEW_FEATURES set to false. This is the only class in the project dedicated to configuration state.

```java
public class Configuration {

	public static final boolean PREVIEW_FEATURES = false;

}
```

--------------------------------

### Push workspace to Structurizr API

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/commands.md

Pushes a local workspace to the Structurizr API. Requires workspace ID, API key, and API secret. Optional flags include branch, merge, and archive.

```bash
./structurizr.sh push -id 1234 -key KEY -secret SECRET -workspace workspace.dsl -branch main -merge true -archive true
```

--------------------------------

### Error handling for unknown export format

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/ExportCommand.md

Running the export command with an unknown format produces no files but does not throw an exception. The output shows the workspace being exported and a message about the unknown format.

```bash
./structurizr.sh export -workspace workspace.dsl -format bogus -output out
# Exporting workspace from workspace.dsl
#  - unknown export format: bogus
#  - finished
```

--------------------------------

### Merge layout information into workspace

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/commands.md

Runs the merge command with the required options: workspace file, layout file, and output file. The optional -view flag restricts merging to a specific view. On success, the merged workspace is written as JSON to the output file.

```bash
./structurizr.sh merge -workspace workspace.dsl -layout layout.json -view SystemLandscape -o merged.json
```

--------------------------------

### Programmatic use of ExportCommand in Java

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/ExportCommand.md

Instantiates ExportCommand directly and runs it with arguments for workspace, output, and format. This mirrors how the test suite invokes the command.

```java
import com.structurizr.cli.export.ExportCommand;

public class ExportRunner {
    public static void main(String[] args) throws Exception {
        new ExportCommand().run(
            "export",
            "-workspace", "workspace.dsl",
            "-output", "out",
            "-format", "mermaid"
        );
    }
}
```

--------------------------------

### Pull workspace from Structurizr API

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/commands.md

Downloads a workspace from the Structurizr API and saves it as JSON. Requires workspace ID, API key, and API secret. Optionally specify a branch; the output file includes the branch name when provided.

```bash
./structurizr.sh pull -id 1234 -key KEY -secret SECRET -branch main
# writes structurizr-1234-main-workspace.json
```

--------------------------------

### Subclass AbstractCommand to create a custom command

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/AbstractCommand.md

Shows the minimal structure for a custom command that extends AbstractCommand, overriding run() and using the shared loadWorkspace() and addDefaultViewsAndStyles() methods. This is how ValidateCommand is implemented.

```java
import com.structurizr.Workspace;
import com.structurizr.cli.AbstractCommand;

public class MyCommand extends AbstractCommand {

    @Override
    public void run(String... args) throws Exception {
        // parse options, then reuse the shared loading pipeline
        Workspace workspace = loadWorkspace("workspace.dsl");
        addDefaultViewsAndStyles(workspace);
        // ... do something with the workspace
    }
}
```

--------------------------------

### AbstractCommand addDefaultViewsAndStyles method

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/AbstractCommand.md

Adds default views and styles to a workspace if none are defined. Logs messages when creating default views or when no styles/themes are defined.

```java
protected void addDefaultViewsAndStyles(Workspace workspace)
```

--------------------------------

### Inspect workspace with Structurizr CLI

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/commands.md

Runs the inspect command on a workspace DSL file, showing violations of the specified severities. The inspector defaults to com.structurizr.inspection.DefaultInspector. Exit code equals the number of violations displayed, or 1 on parse/load failure.

```bash
./structurizr.sh inspect -workspace workspace.dsl -severity ERROR,WARNING
```

--------------------------------

### export(Workspace workspace)

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/JsonWorkspaceExporter.md

Serializes the given workspace to JSON and returns a WorkspaceExport containing the pretty-printed JSON definition. Throws a RuntimeException if serialization fails.

```APIDOC
## export(Workspace workspace)

### Description
Serializes the workspace to JSON. The serialization includes the full workspace: model, views, and documentation. The result is a `JsonWorkspaceExport` with pretty-printed JSON and file extension `json`.

### Method
`export`

### Signature
```java
public WorkspaceExport export(Workspace workspace)
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `workspace` | `Workspace` | yes | — | The workspace to serialize |

### Returns
`WorkspaceExport` — a `JsonWorkspaceExport` whose definition is the pretty-printed JSON and whose file extension is `json`.

### Throws
`RuntimeException` — wraps any exception from `WorkspaceUtils.toJson` (e.g. serialization failures).

### Example
```java
import com.structurizr.Workspace;
import com.structurizr.cli.export.JsonWorkspaceExporter;
import com.structurizr.export.WorkspaceExport;

Workspace workspace = ...; // loaded from DSL or JSON
JsonWorkspaceExporter exporter = new JsonWorkspaceExporter();
WorkspaceExport export = exporter.export(workspace);

System.out.println(export.getFileExtension()); // "json"
System.out.println(export.getDefinition());    // pretty-printed JSON
```

### Error Handling
Serialization failures surface as `RuntimeException` wrapping the underlying cause:
```java
import com.structurizr.cli.export.JsonWorkspaceExporter;

JsonWorkspaceExporter exporter = new JsonWorkspaceExporter();
try {
    exporter.export(workspace);
} catch (RuntimeException e) {
    // wraps the underlying serialization exception
    System.err.println("Export failed: " + e.getCause());
}
```
```

--------------------------------

### AbstractCommand constructor

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/AbstractCommand.md

Protected no-argument constructor; subclasses call it implicitly. The class cannot be instantiated directly.

```java
protected AbstractCommand()
```

--------------------------------

### AbstractCommand class declaration

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/AbstractCommand.md

Abstract base class for all CLI commands. Declares the plugins directory name and HTTP OK status constants, a protected constructor, and the abstract run method that each command implements.

```java
public abstract class AbstractCommand {

    private static final String PLUGINS_DIRECTORY_NAME = "plugins";
    private static final int HTTP_OK_STATUS = 200;

    protected AbstractCommand() {
    }

    public abstract void run(String... args) throws Exception;
}
```

--------------------------------

### getNow method signature

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/DateUtils.md

Returns the current time in UTC.

```java
public static Date getNow()
```

--------------------------------

### AbstractCommand getAgent method

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/AbstractCommand.md

Returns the user-agent string sent to the Structurizr API, e.g. structurizr-cli/1.0.0. Used by PushCommand, PullCommand, CloudToOnPremisesCommand, LockCommand, and UnlockCommand via WorkspaceApiClient.setAgent(...).

```java
String getAgent() {
    return "structurizr-cli/" + getClass().getPackage().getImplementationVersion();
}
```

--------------------------------

### CLI export command with json format

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/JsonWorkspaceExporter.md

Command-line usage of the export command with the json format, which writes the output to <workspace-name>.json in the specified output directory.

```bash
./structurizr.sh export -workspace workspace.dsl -format json -output out
# writes out/workspace.json
```

--------------------------------

### push

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/commands.md

Pushes a local workspace (JSON or DSL) to the Structurizr API, optionally merging layout from the remote workspace and archiving the previous remote version.

```APIDOC
## push

### Description
Pushes a local workspace (JSON or DSL) to the Structurizr API, optionally merging layout from the remote workspace and archiving the previous remote version.

### Method
CLI command

### Endpoint
`structurizr push [options]`

### Parameters
#### Options
- `-url` / `-structurizrApiUrl` (String) - Optional - Structurizr API URL. Default: `https://api.structurizr.com`
- `-id` / `-workspaceId` (long) - Required - Workspace ID
- `-key` / `-apiKey` (String) - Required - Workspace API key
- `-secret` / `-apiSecret` (String) - Required - Workspace API secret
- `-branch` / `-branch` (String) - Optional - Branch name
- `-w` / `-workspace` (String) - Optional* - Path or URL to the workspace JSON/DSL file (*exits with code 1 if empty)
- `-passphrase` / `-passphrase` (String) - Optional - Client-side encryption passphrase
- `-merge` / `-mergeFromRemote` (boolean) - Optional - Whether to merge layout information from the remote workspace. Default: `true`
- `-archive` / `-archive` (boolean) - Optional - Stores the previous version of the remote workspace. Default: `true`
- `-debug` / `-debug` (flag) - Optional - Enable debug logging. Default: `false`

### Request Example
```bash
./structurizr.sh push -id 1234 -key KEY -secret SECRET -workspace workspace.dsl -branch main -merge true -archive true
```

### Response
#### Exit Codes
- `0` - Success
- `1` - Parse error, missing `-workspace`, or non-existent workspace path

### Behavior
Builds a `WorkspaceApiClient(apiUrl, apiKey, apiSecret)`, sets branch, agent, and (if `-passphrase` given) an `AesEncryptionStrategy(passphrase)`. If `-archive` is true, the archive location is set to the parent directory of the workspace file. Loads the workspace via `loadWorkspace`, calls `addDefaultViewsAndStyles`, sets `mergeFromRemote`, then `client.putWorkspace(workspaceId, workspace)`.
```

--------------------------------

### getDefinition() (Inherited)

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/DslWorkspaceExport.md

Returns the DSL definition string passed to the constructor. This method is inherited from the WorkspaceExport base class.

```APIDOC
## Method: getDefinition() (Inherited)

### Description
Returns the DSL definition string that was provided when this export was created.

### Returns
- **String** - The DSL definition string.

### Example
```java
DslWorkspaceExport export = new DslWorkspaceExport("workspace { ... }");
System.out.println(export.getDefinition()); // "workspace { ... }"
```
```

--------------------------------

### Programmatic invocation of StructurizrCliApplication

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/StructurizrCliApplication.md

Equivalent to the shell form, this Java code invokes the CLI programmatically. The first argument is the command name, followed by command-specific options.

```java
import com.structurizr.cli.StructurizrCliApplication;

public class Main {
    public static void main(String[] args) {
        // args[0] is the command name, e.g. "export"
        new StructurizrCliApplication().run(
            "export",
            "-workspace", "workspace.dsl",
            "-format", "plantuml",
            "-output", "diagrams"
        );
    }
}
```

--------------------------------

### DslWorkspaceExport(String definition)

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/DslWorkspaceExport.md

Constructs a new DslWorkspaceExport with the given DSL definition string. The definition is delegated to the parent WorkspaceExport constructor.

```APIDOC
## Constructor: DslWorkspaceExport(String definition)

### Description
Creates a new DslWorkspaceExport instance with the specified DSL definition string.

### Parameters
- **definition** (String) - Required - The DSL definition string.

### Example
```java
DslWorkspaceExport export = new DslWorkspaceExport("workspace { ... }");
```
```

--------------------------------

### Error handling for JsonWorkspaceThemeExporter

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/JsonWorkspaceThemeExporter.md

Shows how to catch a RuntimeException thrown by the export method and print the underlying cause. Failures from ThemeUtils.toJson are wrapped in a RuntimeException.

```java
import com.structurizr.cli.export.JsonWorkspaceThemeExporter;

try {
    new JsonWorkspaceThemeExporter().export(workspace);
} catch (RuntimeException e) {
    System.err.println("Theme export failed: " + e.getCause());
}
```

--------------------------------

### Catch StructurizrCliException in Java

Source: https://github.com/structurizr/cli/blob/master/_autodocs/errors.md

Shows how to catch the custom exception and print its message. The exception is thrown when the workspace path does not exist or is not a JSON/DSL file, or when the DSL produces no workspace.

```java
import com.structurizr.cli.StructurizrCliException;

try {
    loadWorkspace("workspace.dsl");
} catch (StructurizrCliException e) {
    System.err.println(e.getMessage());
}
```

--------------------------------

### getBuildNumber method (Java)

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/Version.md

Returns the build.number property value as a String, or "" if unavailable.

```java
public String getBuildNumber()
```

--------------------------------

### getFileExtension method signature

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/DslWorkspaceExport.md

Overridden getFileExtension() method signature. Returns always "dsl".

```java
@Override
public String getFileExtension()
```

--------------------------------

### merge

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/commands.md

Merges layout information from one workspace into another and writes the result as JSON. The target workspace is specified with -workspace, the source layout with -layout, and the output file with -output. Optionally, a specific view can be targeted with -view.

```APIDOC
## merge

### Description
Merges layout information from one workspace into another and writes the result as JSON. The target workspace is specified with -workspace, the source layout with -layout, and the output file with -output. Optionally, a specific view can be targeted with -view.

### Method
CLI command

### Endpoint
`merge`

### Parameters
#### Options
- `-workspace` (String) - Required - Path or URL to the workspace JSON/DSL file (target, without layout)
- `-view` (String) - Optional - Key of the view to merge layout information for
- `-layout` (String) - Required - Path or URL to the workspace JSON file that includes layout information (source)
- `-output` (String) - Required - Path and name of an output file

### Behavior
- Without `-view`: copies layout information from the source workspace's views to the target workspace's views, and copies configuration from the source to the target.
- With `-view`: looks up the view by key in both workspaces. If missing in either, logs an error and exits with code 1. If either view is not a ModelView, logs an error and exits with code 1. Otherwise, copies layout information from the source view to the target view.
- Writes the merged workspace to the output file as JSON.

### Exit Codes
- `0` on success
- `1` on parse error or view lookup failure

### Example
```bash
./structurizr.sh merge -workspace workspace.dsl -layout layout.json -view SystemLandscape -o merged.json
```
```

--------------------------------

### formatIsoDate method signature

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/DateUtils.md

Formats a date using the ISO_DATE_TIME_FORMAT in UTC, returning an empty string if the date is null.

```java
public static String formatIsoDate(Date d)
```

--------------------------------

### export method signature

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/JsonWorkspaceThemeExporter.md

The method signature for the export method, which serializes the workspace's theme to JSON.

```java
@Override
public WorkspaceExport export(Workspace workspace)
```

--------------------------------

### Unlock workspace using structurizr.sh

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/commands.md

Unlocks a previously locked workspace. Requires workspace ID, API key, and API secret. Exit code 0 if unlocked, 1 if not unlocked or on parse error.

```bash
./structurizr.sh unlock -id 1234 -key KEY -secret SECRET
```

--------------------------------

### Handle loadWorkspace errors with StructurizrCliException

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/AbstractCommand.md

Demonstrates catching StructurizrCliException thrown by loadWorkspace when the file is missing or scope violations occur. The exception message includes the absolute path, e.g., "/abs/path/does-not-exist.dsl does not exist".

```java
import com.structurizr.cli.AbstractCommand;
import com.structurizr.cli.StructurizrCliException;

public class MyCommand extends AbstractCommand {

    @Override
    public void run(String... args) throws Exception {
        try {
            loadWorkspace("does-not-exist.dsl");
        } catch (StructurizrCliException e) {
            // e.getMessage() == "/abs/path/does-not-exist.dsl does not exist"
            System.err.println("Cannot load workspace: " + e.getMessage());
            System.exit(1);
        }
    }
}
```

--------------------------------

### getFileExtension()

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/DslWorkspaceExport.md

Returns the file extension for this export type, which is always 'dsl'.

```APIDOC
## Method: getFileExtension()

### Description
Returns the file extension associated with this export type.

### Returns
- **String** - Always returns "dsl".

### Example
```java
DslWorkspaceExport export = new DslWorkspaceExport("workspace { ... }");
System.out.println(export.getFileExtension()); // "dsl"
```
```

--------------------------------

### DateUtils class declaration

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/DateUtils.md

Shows the public class declaration with its constants and method signatures. The class is in the com.structurizr.cli.util package.

```java
public class DateUtils {

    public static final String UTC_TIME_ZONE = "UTC";
    public static final String ISO_DATE_TIME_FORMAT = "yyyy-MM-dd'T'HH:mm:ss'Z'";

    public static Calendar getCalendar() { ... }
    public static Date getNow() { ... }
    public static Date removeMilliseconds(Date date) { ... }
    public static String formatIsoDate(Date d) { ... }
}
```

--------------------------------

### DslWorkspaceExport constructor signature

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/DslWorkspaceExport.md

Constructor signature for DslWorkspaceExport. Takes a definition string and delegates to WorkspaceExport(String).

```java
public DslWorkspaceExport(String definition)
```

--------------------------------

### getGitCommit method (Java)

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/Version.md

Returns the git.commit property value as a String, or null if unavailable.

```java
public String getGitCommit()
```

--------------------------------

### JsonWorkspaceExport(String definition)

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/JsonWorkspaceExport.md

Constructs a new JsonWorkspaceExport with the given JSON definition string. The definition is delegated to the parent WorkspaceExport constructor.

```APIDOC
## JsonWorkspaceExport(String definition)

### Description
Constructs a new JsonWorkspaceExport with the given JSON definition string. The definition is delegated to the parent WorkspaceExport constructor.

### Constructor
`public JsonWorkspaceExport(String definition)`

### Parameters
- **definition** (String) - Required - The JSON definition string.

### Source
`JsonWorkspaceExport.java:7`

```

--------------------------------

### DslWorkspaceExport class declaration

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/DslWorkspaceExport.md

Defines the DslWorkspaceExport class extending WorkspaceExport. Constructor delegates to super with the definition string. Overrides getFileExtension() to return "dsl".

```java
public class DslWorkspaceExport extends WorkspaceExport {

    public DslWorkspaceExport(String definition) {
        super(definition);
    }

    @Override
    public String getFileExtension() {
        return "dsl";
    }

}
```

--------------------------------

### Error handling for serialization failures

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/JsonWorkspaceExporter.md

Shows how to catch a RuntimeException thrown by the export method, which wraps the underlying serialization exception. The cause can be retrieved via getCause().

```java
import com.structurizr.cli.export.JsonWorkspaceExporter;

JsonWorkspaceExporter exporter = new JsonWorkspaceExporter();
try {
    exporter.export(workspace);
} catch (RuntimeException e) {
    // wraps the underlying serialization exception
    System.err.println("Export failed: " + e.getCause());
}
```

--------------------------------

### getCalendar method signature

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/DateUtils.md

Returns a Calendar instance in the UTC time zone.

```java
public static Calendar getCalendar()
```

--------------------------------

### getFileExtension()

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/JsonWorkspaceExport.md

Returns the file extension for this export type, which is always "json". This method overrides the base class method.

```APIDOC
## getFileExtension()

### Description
Returns the file extension for this export type, which is always "json". This method overrides the base class method.

### Method
`public String getFileExtension()`

### Returns
- **String** - Always `"json"`.

### Source
`JsonWorkspaceExport.java:12`

```

--------------------------------

### unlock

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/commands.md

Unlocks a previously locked workspace. This command requires the workspace ID, API key, and API secret to authenticate with the Structurizr API.

```APIDOC
## UNLOCK [command]

### Description
Unlocks a previously locked workspace.

### Method
Command

### Endpoint
unlock

### Parameters
#### Options
- `-url` (String) - Optional - Structurizr API URL (default: `https://api.structurizr.com`)
- `-id` (long) - Required - Workspace ID
- `-key` (String) - Required - Workspace API key
- `-secret` (String) - Required - Workspace API secret

### Request Example
```bash
./structurizr.sh unlock -id 1234 -key KEY -secret SECRET
```

### Response
#### Success Response
- Exit code `0` if the workspace was unlocked
- Exit code `1` if not unlocked or on parse error

#### Response Example
Logs the boolean result of `client.unlockWorkspace(workspaceId)`
```

--------------------------------

### Lock workspace using structurizr.sh

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/commands.md

Locks a workspace so it cannot be modified. Requires workspace ID, API key, and API secret. Exit code 0 if locked, 1 if not locked or on parse error.

```bash
./structurizr.sh lock -id 1234 -key KEY -secret SECRET
```

--------------------------------

### lock

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/commands.md

Locks a workspace so it cannot be modified. This command requires the workspace ID, API key, and API secret to authenticate with the Structurizr API.

```APIDOC
## LOCK [command]

### Description
Locks a workspace so it cannot be modified.

### Method
Command

### Endpoint
lock

### Parameters
#### Options
- `-url` (String) - Optional - Structurizr API URL (default: `https://api.structurizr.com`)
- `-id` (long) - Required - Workspace ID
- `-key` (String) - Required - Workspace API key
- `-secret` (String) - Required - Workspace API secret

### Request Example
```bash
./structurizr.sh lock -id 1234 -key KEY -secret SECRET
```

### Response
#### Success Response
- Exit code `0` if the workspace was locked
- Exit code `1` if not locked or on parse error

#### Response Example
Logs the boolean result of `client.lockWorkspace(workspaceId)`
```

--------------------------------

### JsonWorkspaceThemeExporter class declaration

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/JsonWorkspaceThemeExporter.md

The full class implementation of JsonWorkspaceThemeExporter, implementing WorkspaceExporter. The export method calls ThemeUtils.toJson(workspace) and wraps the result in a JsonWorkspaceExport, throwing a RuntimeException on any exception.

```java
public class JsonWorkspaceThemeExporter implements WorkspaceExporter {

    @Override
    public WorkspaceExport export(Workspace workspace) {
        try {
            return new JsonWorkspaceExport(ThemeUtils.toJson(workspace));
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

}
```

--------------------------------

### StructurizrCliException class declaration

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/StructurizrCliException.md

The complete class declaration for the CLI's custom runtime exception. Note that the constructor is package-private, so only code inside com.structurizr.cli can instantiate this exception; consumer code can only catch it.

```java
public class StructurizrCliException extends RuntimeException {

    StructurizrCliException(String message) {
        super(message);
    }

}
```

--------------------------------

### JsonWorkspaceExport constructor signature

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/JsonWorkspaceExport.md

The constructor signature for JsonWorkspaceExport, which takes a definition string and delegates to the superclass constructor.

```java
public JsonWorkspaceExport(String definition)
```

--------------------------------

### WorkspaceExporter interface definition

Source: https://github.com/structurizr/cli/blob/master/_autodocs/types.md

Defines the WorkspaceExporter interface with a single method export that takes a Workspace and returns a WorkspaceExport. Implemented by various exporters.

```java
public interface WorkspaceExporter {
    WorkspaceExport export(Workspace workspace);
}
```

--------------------------------

### JsonWorkspaceExporter class declaration

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/JsonWorkspaceExporter.md

The full class implementation of JsonWorkspaceExporter, implementing WorkspaceExporter. The export method calls WorkspaceUtils.toJson(workspace, true) and wraps the result in a JsonWorkspaceExport, throwing a RuntimeException on failure.

```java
public class JsonWorkspaceExporter implements WorkspaceExporter {

    @Override
    public WorkspaceExport export(Workspace workspace) {
        try {
            return new JsonWorkspaceExport(WorkspaceUtils.toJson(workspace, true));
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

}
```

--------------------------------

### JsonWorkspaceExport class declaration

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/JsonWorkspaceExport.md

The full class declaration for JsonWorkspaceExport, extending WorkspaceExport and overriding getFileExtension() to return "json".

```java
public class JsonWorkspaceExport extends WorkspaceExport {

    public JsonWorkspaceExport(String definition) {
        super(definition);
    }

    @Override
    public String getFileExtension() {
        return "json";
    }

}
```

--------------------------------

### DiagramExporter interface definition

Source: https://github.com/structurizr/cli/blob/master/_autodocs/types.md

Defines the DiagramExporter interface with a single export method that takes a Workspace and returns a collection of Diagram objects. Used by ExportCommand.run to write per-view files, legends, and frames.

```java
public interface DiagramExporter {
    Collection<Diagram> export(Workspace workspace);
}
```

--------------------------------

### removeMilliseconds method signature

Source: https://github.com/structurizr/cli/blob/master/_autodocs/api-reference/DateUtils.md

Truncates the milliseconds from a given date.

```java
public static Date removeMilliseconds(Date date)
```
Tokens:
Raw