Cli

Getting Started¶

Diagrams can be defined using the Python DSL or a JSON representation.

Python Example¶

Create a diagram using the Python DSL:

# diagram.py
from c4 import Person, Rel, System, SystemContextDiagram

with SystemContextDiagram() as diagram:
    user = Person("User", "System user")
    backend = System("Backend API", "Main application backend")

    user >> Rel("Uses HTTP API") >> backend

To render the diagram to text (by default, PlantUML source), run:

c4 render diagram.py > diagram.puml

@startuml
' convert it with additional command line argument -DRELATIVE_INCLUDE="relative/absolute" to use locally
!if %variable_exists("RELATIVE_INCLUDE")
    !include %get_variable_value("RELATIVE_INCLUDE")/C4_Context.puml
!else
    !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
!endif

Person(user_a467, "User", "System user")

System(backend_api_8c20, "Backend API", "Main application backend")

Rel(user_a467, backend_api_8c20, "Uses HTTP API")

@enduml

To export the diagram to a rendered artifact (by default, PNG format), run:

c4 export diagram.py > diagram.png

This generates the diagram below:

JSON Support¶

Diagrams can also be defined in JSON format.

The same diagram expressed in JSON:

{
  "type": "SystemContextDiagram",
  "elements": [
    {
      "type": "Person",
      "alias": "user",
      "label": "User",
      "description": "System user"
    },
    {
      "type": "System",
      "alias": "app",
      "label": "Backend API",
      "description": "Main application backend"
    }
  ],
  "relationships": [
    {
      "type": "REL",
      "from": "user",
      "to": "app",
      "label": "Uses HTTP API"
    }
  ]
}

JSON diagrams are treated the same way as Python diagrams:

• c4 render diagram.json — generate textual output (e.g. PlantUML)
• c4 export diagram.json — generate rendered artifacts (e.g. PNG)
• c4 convert diagram.json — convert to another representation (e.g. Python)

To convert a JSON diagram into the Python DSL, run:

c4 convert diagram.json --json-to-py > diagram.py

This generates:

# diagram.py
from c4 import (
    Person,
    Rel,
    System,
    SystemContextDiagram,
)

with SystemContextDiagram():
    user = Person('User', 'System user', alias='user')
    app = System('Backend API', 'Main application backend', alias='app')
    user >> Rel('Uses HTTP API') >> app

CLI Reference¶

c4 render¶

Render a diagram to text output (by default, PlantUML source).

Usage:

c4 render [-h] [-o OUTPUT] \
          [--renderer {plantuml} | --plantuml] \
          [--plantuml-use-new-c4-style] \
          target

Arguments:

Options:

PlantUML Options:

These options apply when using the plantuml renderer.

c4 export¶

Export a diagram to a rendered artifact (e.g., PNG or SVG).

The available formats depend on the selected renderer.

Usage:

c4 export [-h] [-o OUTPUT] [-f {eps,latex,pdf,png,svg,txt,utxt}] \
          [--timeout TIMEOUT] \
          [--renderer {plantuml,mermaid} | --plantuml | --mermaid] \
          [--plantuml-backend {local,remote}] \
          [--plantuml-server-url PLANTUML_SERVER_URL] \
          [--plantuml-bin PLANTUML_BIN | --plantuml-jar PLANTUML_JAR] \
          [--java-bin JAVA_BIN] \
          [--plantuml-skinparam-dpi PLANTUML_SKINPARAM_DPI] \
          [--plantuml-use-new-c4-style] \
          [--plantuml-use-bundled-c4-plantuml] \
          [--mermaid-bin MERMAID_BIN] \
          [--mermaid-scale-factor MERMAID_SCALE_FACTOR] \
          target

Arguments:

Options:

PlantUML Options:

These options apply when using the plantuml renderer.

Mermaid Options:

These options apply when using the mermaid renderer.

c4 convert¶

Convert a diagram from one representation to another.

Usage:

c4 convert [-h] \
           [--json-to-py] \
           [--from {json} | --from-json] \
           [--to {py} | --to-py] \
           [-o OUTPUT] \
           target

Arguments:

Options: