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() as diagram:
    user = Person('User', 'System user', alias='user')
    app = System('Backend API', 'Main application backend', alias='app')
    user >> Rel('Uses HTTP API') >> app

Diagram Targets¶

The render and export commands accept a diagram target. For Python targets, the optional name after : selects a specific diagram object in the file or module. If no name is provided, the CLI auto-detects a diagram only when the target has exactly one module-level diagram.

The convert command currently supports JSON input targets for JSON-to-Python conversion.

Examples¶

Render PlantUML source to stdout:

c4 render diagram.py --plantuml

Render Mermaid source:

c4 render diagram.py --mermaid -o diagram.mmd

Select a named diagram in a Python file:

c4 render diagrams.py:container_diagram -o container.puml

Export SVG with Mermaid:

c4 export diagram.py --mermaid -f svg -o diagram.svg

Export SVG with a remote PlantUML server:

c4 export diagram.py --plantuml -f svg \
  --plantuml-backend remote \
  --plantuml-server-url https://www.plantuml.com/plantuml \
  -o diagram.svg

Export PNG with local PlantUML and the bundled C4-PlantUML files:

c4 export diagram.py --plantuml -f png \
  --plantuml-use-bundled-c4-plantuml true \
  -o diagram.png

Watch Mode¶

The render and export commands can re-run automatically when watched files change. Watch mode is an optional dependency:

pip install "c4-diagrams[watch]"

Watch mode writes on every rerun, so --watch requires -o / --output.

Render PlantUML source whenever the diagram file changes:

c4 render diagram.py --plantuml -o diagram.puml --watch

Export an SVG whenever the diagram file changes:

c4 export diagram.py --mermaid -f svg -o diagram.svg --watch

Use --watch-dir for shared reusable diagram element directories. Without --watch-include, any changed file under that directory triggers a rerun:

c4 export diagram.py -f svg -o diagram.svg --watch --watch-dir shared_package

Use --watch-include to narrow which files under --watch-dir trigger a rerun:

c4 render diagram.py -o diagram.puml --watch \
  --watch-dir shared_package \
  --watch-include "*.py"

The current implementation watches the primary target file and any explicit --watch-dir paths. It does not infer or follow the Python import graph, so helper modules should be covered with --watch-dir and, optionally, --watch-include.

Environment Variables¶

CLI flags take precedence over environment variables.

CLI Reference¶

c4 render¶

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

Usage:

c4 render [-h] [-o OUTPUT] \
          [--renderer {plantuml,mermaid} | --plantuml | --mermaid] \
          [--plantuml-use-new-c4-style] \
          [-w] [--watch-delay WATCH_DELAY] \
          [--watch-dir WATCH_DIR] [--watch-include WATCH_INCLUDE] \
          target

Arguments:

Options:

Watch Options:

These options require the watch extra and apply only to render and export. --watch requires -o / --output.

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 PLANTUML_USE_BUNDLED_C4_PLANTUML] \
          [--mermaid-bin MERMAID_BIN] \
          [--mermaid-scale-factor MERMAID_SCALE_FACTOR] \
          [--mermaid-puppeteer-headless MERMAID_PUPPETEER_HEADLESS | \
           --mermaid-puppeteer-config MERMAID_PUPPETEER_CONFIG] \
          [-w] [--watch-delay WATCH_DELAY] \
          [--watch-dir WATCH_DIR] [--watch-include WATCH_INCLUDE] \
          target

Arguments:

Options:

Watch Options:

These options require the watch extra and apply only to render and export. --watch requires -o / --output.

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: