DOCSEARCHbyAlgolia
Submit Docs

Structurizr CLI

repository·master·Indexed 20 days ago

https://github.com/structurizr/cli

A command-line tool for interacting with Structurizr, featuring capabilities to export workspaces to formats like PlantUML, Mermaid, and static websites; migrate workspaces from Structurizr Cloud to On-Premises; and manage workspaces via push, pull, lock, and merge commands. It also includes an inspect command for analyzing architectural violations and a list command for viewing model elements. Note: This tool is currently being deprecated in favor of new consolidated tooling.

Tokens
4.9K
Snippets
20
Records
26
Agent score
68%

What's inside structurizr-cli

  1. Migrate from Structurizr CLI to new consolidated tooling

    master
    The Structurizr CLI is no longer receiving updates. Users are advised to migrate to the new consolidated tooling. For details on the new tooling and available commands, refer to the Structurizr vNext documentation and the official commands guide.

  2. Structure of exported workspace data

    master

    When running the cloud-to-onpremises command, the output directory will contain the following structure for each workspace:

    • structurizr.properties: Global configuration for the exported set.
    • structurizr.users: User credentials file.
    • <workspace-id>/:
      • workspace.json: The main workspace definition.
      • workspace.properties: Workspace-specific configuration (API keys, owner, permissions, etc.).
      • branches/ (optional):
        • <branch-name>/workspace.json: The workspace definition for a specific branch.

  3. Migrate workspaces from Structurizr Cloud to On-Premises

    master

    The cloud-to-onpremises command allows you to export your workspaces from the Structurizr Cloud service to a local directory. This is useful for migrating to an On-Premises installation. The command fetches workspace metadata, downloads the workspace JSON (including branches if applicable), and generates necessary configuration files like structurizr.properties, structurizr.users, and workspace.properties to facilitate the migration.

    Important: The specified output directory must not already exist; the command will fail if it does to prevent overwriting data.

    # Example usage (placeholders used)
# Note: The output directory '/path/to/output' must not exist before running this.
structurizr cloud-to-onpremises --apiKey YOUR_API_KEY --username YOUR_USERNAME --output /path/to/output

  4. Export a static website from a workspace

    master

    Using the static format generates a complete, ready-to-host static website.

    Key behaviors of the static export:

    1. It unzips a default static site template into the output directory.
    2. It automatically adds default views and styles if none exist in the workspace.
    3. It applies Graphviz automatic layout locally to ensure diagrams are positioned.
    4. It generates a workspace.js file in the output directory containing the workspace data as a base64 encoded string (const jsonAsString = '...';).
    5. Note: Documentation (textual descriptions) is cleared during this process as it is not supported by the static site generator.
    structurizr-cli export -w my-workspace.dsl -f static -o ./my-static-site

  5. Reference the `inspect` command options

    master

    The following options are available for the inspect command:

    OptionLong FlagRequiredDescription
    -w--workspaceYesPath or URL to the workspace JSON/DSL file
    -i--inspectorNoInspector implementation to use (defaults to com.structurizr.inspection.DefaultInspector)
    -s--severityNoA comma-separated list of the severity level(s) to show

    Severity Levels

    When using the --severity flag, you can specify any of the following levels (case-insensitive):

    • ERROR
    • WARNING
    • INFO
    • IGNORE

    If no severity is specified, the command defaults to showing ERROR, WARNING, INFO, and IGNORE.

    inspect --workspace ./workspace.dsl --severity ERROR,WARNING

  7. Reference: `push` command options

    master

    The following options are available for the push command:

    Long FlagShort FlagDescriptionRequired
    --structurizrApiUrl-urlStructurizr API URL (default: https://api.structurizr.com)No
    --workspaceId-idWorkspace IDYes
    --apiKey-keyWorkspace API keyYes
    --apiSecret-secretWorkspace API secretYes
    --branch-branchBranch nameNo
    --workspace-wPath or URL to the workspace JSON/DSL fileYes
    --passphrase-passphraseClient-side encryption passphraseNo
    --mergeFromRemote-mergeWhether to merge layout information from the remote workspace (default: true)No
    --archive-archiveStores the previous version of the remote workspace (default: true)No
    --debug-debugEnable debug loggingNo

  9. Reference: pull command options

    master

    The following options are available for the pull command. Note that workspaceId, apiKey, and apiSecret are required.

    --structurizrApiUrl <value>    Structurizr API URL (default: https://api.structurizr.com)
--workspaceId <value>           Workspace ID (Required)
--apiKey <value>                Workspace API key (Required)
--apiSecret <value>             Workspace API secret (Required)
--branch <value>                Branch name
--passphrase <value>            Client-side encryption passphrase
--debug                         Enable debug logging

  11. Reference the export command options

    master

    The export command accepts the following options:

    FlagLong OptionDescription
    -w--workspaceRequired. Path or URL to the workspace JSON file or DSL file(s).
    -f--formatRequired. The export format (see supported formats below).
    -o--outputOptional. Path to the output directory. If not provided, it defaults to the parent directory of the workspace file.

    Supported Formats

    Diagram Formats:

    • mermaid: Mermaid diagram definitions.
    • plantuml: Structurizr PlantUML format.
    • plantuml/c4plantuml: C4 PlantUML format.
    • plantuml/structurizr: Structurizr-specific PlantUML subformat.
    • dot: Graphviz DOT format.
    • websequencediagrams: WebSequenceDiagrams format.

    Workspace & Data Formats:

    • json: The workspace exported as JSON.
    • theme: The workspace theme exported as JSON.
    • static: A complete static website export (includes a workspace.js containing base64 encoded JSON).
    • ilograph: Ilograph format.

    PlantUML Color Schemes: For PlantUML formats, you can append color scheme suffixes:

    • plantuml-light (or plantuml/structurizr-light, etc.)
    • plantuml-dark (or plantuml/structurizr-dark, etc.)
    # List of supported format strings for the -f flag:
# mermaid, dot, websequencediagrams, ilograph, json, theme, static, 
# plantuml, plantuml/c4plantuml, plantuml/structurizr