Skip to content

LikeC4 CLI

NPM VersionNPM Downloads

The likec4 CLI is a tool for various operations and automation tasks, such as:

  • Start a development server to preview diagrams (with hot reload)
  • Build a static website for sharing and embedding diagrams
  • Export views to PNG, JPEG, JSON, Markdown and Draw.io
  • Generate Mermaid, Dot, D2 and PlantUML sources, React components, Web Components and a typed model
  • Validate and format source files (CI-friendly)
  • Apply model diffs and safely delete elements
  • Publish models to LikeC4 Cloud
  • Run the language server and the MCP server

If you’re using it in an npm project, install it as a development dependency:

npm i -D likec4

You can reference it directly in the package.json#scripts object:

{
scripts: {
dev: 'likec4 dev ...',
build: 'likec4 build ...'
}
}

To fetch and execute the package binary without installing it, e.g. to start the dev server:

npx likec4 start

To use it in any project without npx, install it globally:

Terminal window
npm install --global likec4
# Then, you can call `likec4` directly:
likec4 [command]

Almost all commands have a --help option and provide usage examples.

Terminal window
likec4 build -h
likec4 gen react -h

Options available in all commands:

Option Description
--help, -h Show help
--version, -v Show the version of the CLI
--verbose Verbose logging

Most commands take the directory with LikeC4 sources as the last argument ([path]). It defaults to the current directory, or to the LIKEC4_WORKSPACE environment variable.

Prefer long option names in scripts: some short options mean different things in different commands.

Short Long option
-o --output in build and preview
--outdir in export png/jpg/drawio, gen dot/d2/mermaid/plantuml, gen leanix and sync
--outfile in export json and gen react/webcomponent/model
-p --project in all commands that have it, except mcp, where it is --port
-f --filter in export png/jpg
--file in validate
--format in list-icons
-t --title in start and build
--timeout in export png/jpg
-w --webcomponent-prefix in start, build and gen webcomponent
--watch in lsp

The long names differ too: the output of build is --output, the output of the exports is --outdir (export png/jpg also accept --output for compatibility, export drawio does not).

In a folder with LikeC4 sources:

Terminal window
likec4 start
# Aliases:
likec4 serve
likec4 dev

This recursively searches for *.c4 and *.likec4 files in the current folder, parses them, and serves diagrams via a local web server.
Any change in the source files triggers a hot update in the browser immediately.

Option Description
--port Port for the dev server (default: 5173, or PORT env var)
--hmr-port Port for the HMR WebSocket (default: auto-discovered from 24678–24690, or HMR_PORT env var)
--listen, -l IP address to listen on (default: localhost, or 0.0.0.0 inside a container)
--allowed-host Hostname allowed to access the dev server (Vite server.allowedHosts); repeatable. Defaults to allowing all hosts.
--base, --base-url Base URL the app is served from, e.g. “/” or “/pages/”
--use-hash-history Hash-based navigation, e.g. “/#/view” instead of “/view”
--no-react-hmr Disable React HMR (useful for CI or static previews)
--no-build-webcomponent Do not build the web component (built by default)
--webcomponent-prefix, -w Prefix for web components, e.g. “c4” generates <c4-view ../> (default: likec4)
--use-dot, --use-dot-bin Use local Graphviz (dot) binaries instead of bundled WASM; false by default, true when inside container
--public, --public-dir Directory whose files are served as-is (Vite publicDir)
--title, -t Base title of the app pages (default is “LikeC4”)
--theme Default color scheme of the app, light or dark (default: follows system preference)
--customization File with UI customization (experimental)
--app-config Path to the app config; --no-app-config to ignore it (experimental)

CLI can build a website with the diagrams, ready to be deployed or embedded.
When you deployed the website, you can use “Share” button and get a link to a specific diagram.

The resulting website is strictly bound to the given base path (/ by default). A relocatable app can be built with --base "./".

Terminal window
likec4 build -o ./dist
Option Description
--output, -o Output directory (default: dist in the workspace)
--base, --base-url Base URL from which the app is being served, e.g., “/”, “/pages/”, or “./” for a relocatable app
--use-hash-history Hash-based navigation, e.g. “/#/view” instead of “/view”
--use-dot, --use-dot-bin Use local binaries of Graphviz (“dot”) instead of bundled WASM; false by default, true when inside container
--no-build-webcomponent Do not build the web component (built by default)
--webcomponent-prefix, -w Prefix for web components, e.g. “c4” generates <c4-view ../> (default: likec4)
--title, -t Base title of the app pages (default is “LikeC4”)
--output-single-file Generates a single self-contained HTML file
--public, --public-dir Directory whose files are copied into the output as-is (Vite publicDir); preserved with --output-single-file
--theme Default color scheme of the app, light or dark (default: follows system preference)
--customization File with UI customization (experimental)
--app-config Path to the app config; --no-app-config to ignore it (experimental)

There is also a supplementary command to preview the build:

Terminal window
likec4 preview -o ./dist
Option Description
--output, -o Output directory of the build
--base, --base-url Base URL the build was made for
--listen, -l IP address to listen on (default: localhost)
--app-config Path to the app config (experimental)

likec4 preview takes the output directory and the base URL from the app config, the same way likec4 build does, so the two commands agree without repeating -o and --base.

For example, this command can be used in CI to compare diagrams with ones from the previous or main build.

likec4 export <format> [path] exports views or the whole model. Formats: png, jpg, json, markdown and drawio.

Terminal window
likec4 export png -o ./assets
likec4 export jpg -o ./assets --quality 90

This command starts local web server and uses Playwright to take screenshots.
If you plan to use it in CI, refer to the Playwright documentation for details or consider LikeC4 GitHub Actions.

Use likec4 export jpg to export JPEG files. It supports the same screenshot options, plus --quality.

Option Description
--outdir, -o Output directory for PNG/JPEG files; if not specified, images are saved next to sources. --output is accepted as alias for compatibility.
--project, -p Select LikeC4 project to export from by name (e.g. “my-project”) or by path
If not specified, exports all
--theme Color scheme to use, “light” (default) or “dark”
--dark Use dark theme, shortcut for --theme=dark
--light Use light theme, shortcut for --theme=light
--use-dot, --use-dot-bin Use local binaries of Graphviz (“dot”) instead of bundled WASM; false by default, true when inside container
--seq, --sequence Use sequence layout for dynamic views
--flat, --flatten Flatten all images in outdir, ignoring source structure
--filter, -f Include views with ids matching given patterns (repeatable)
Multiple patterns are combined with OR
--quality, -q JPEG quality from 1 to 100 (default is 80); only used by likec4 export jpg
--ignore, -i Continue if export fails for some views
--timeout, -t Timeout for Playwright in seconds (default is 15)
--max-attempts Max attempts to export failing view, 1 means no retry (default is 3)
--server-url Use this url instead of starting new likec4 server
--chromium-sandbox Enable Chromium sandbox (see Playwright docs)
--notation Include view notation in exported PNG/JPEG files
--description Include the view title and Markdown description in exported PNG/JPEG files
--customization File with UI customization, not used with --server-url (experimental)
--app-config Path to the app config; --no-app-config to ignore it (experimental)

Export the model (elements, relationships and views) to a JSON file:

Terminal window
likec4 export json -o dump.json
likec4 export json --pretty --skip-layout -p my-project -o ./generated/likec4.json src/likec4
Option Description
path Directory with LikeC4 sources (default: current directory)
--outfile, -o Output file (default: likec4.json in the current directory); .json is appended if missing
--project, -p Select LikeC4 project by name or path; if not set, exports all
--skip-layout Skip layout: views are computed, but have no positions (faster)
--pretty Indented JSON output
--use-dot, --use-dot-bin Use local Graphviz (dot) for layout instead of bundled WASM; false by default, true when inside container

With a single project, the file contains the model of this project; with several projects, an array of models.

Write a README.md into the folder of each project, with every view of the project as a Mermaid diagram. GitHub and GitLab render it, so the architecture is browsable in the repository without a server.

Terminal window
likec4 export markdown
likec4 export markdown -p my-project src/likec4
Option Description
path Directory with LikeC4 sources (default: current directory)
--project, -p Select LikeC4 project by name; if not set, exports all
--force Overwrite an existing README.md that was not generated by this command
--use-dot, --use-dot-bin Use local Graphviz (dot) for layout instead of bundled WASM; false by default, true when inside container

Projects without views are skipped. The project description is taken from metadata.description in the project config.

Export views to Draw.io (.drawio) so you can edit diagrams in Draw.io or reuse them in tools that support the format. One .drawio file is generated per view.

Terminal window
likec4 export drawio
likec4 export drawio -o ./diagrams
likec4 export drawio -o ./diagrams src/
likec4 export drawio --profile leanix -o ./diagrams
Option Description
path Path to project (default: current directory)
--outdir, -o Output directory for .drawio files (default: path)
--all-in-one Write one .drawio file with all views as tabs
--roundtrip Apply layout, stroke colors/widths, and edge waypoints from round-trip comment blocks in .c4 source
--uncompressed Write diagram XML uncompressed (larger file; use if Draw.io fails to open the default compressed export)
--profile Export profile: default (round-trip) or leanix (bridge-managed metadata for LeanIX interoperability). Default: default
--project, -p Select LikeC4 project by name or path; if not set, exports all
--use-dot, --use-dot-bin Use local Graphviz (dot) for layout instead of bundled WASM; false by default, true when inside container

likec4 gen <generator> [path] generates source files from the model. The command has two aliases, likec4 generate and likec4 codegen.

Terminal window
likec4 gen mermaid
likec4 gen mmd # alias
likec4 gen dot
likec4 gen d2
likec4 gen plantuml
likec4 gen puml # alias
likec4 gen mermaid -o ./diagrams src/likec4

One file is generated per view, keeping the folder structure of the sources.

Option Description
path Directory with LikeC4 sources (default: current directory)
--outdir, -o Output directory (default: path, next to sources)
--use-dot, --use-dot-bin Use local Graphviz (dot) for layout instead of bundled WASM; false by default, true when inside container

Together with Export to Draw.io, this allows teams to reuse diagrams in Mermaid, Dot, D2, PlantUML, or Draw.io.

Command Output
likec4 gen react -o likec4.jsx React components to render views
likec4 gen webcomponent -o likec4.js Web Components (aliases wc, webcomp)
likec4 gen model -o likec4-model.ts Typed LikeC4Model (alias ts)
likec4 gen <name> Output of a custom generator from the project config

react, webcomponent and model take --outfile, -o (also --output), --project, -p and --use-dot; see likec4 gen <generator> -h for the rest.

likec4 gen views-data (alias views) is deprecated, use likec4 gen model instead.

Terminal window
likec4 validate
# Fail on any warning (e.g. in CI)
likec4 validate --max-warnings 0
# Structured output, only for the given files
likec4 validate --json --file src/model.c4

This command checks for:

  • Syntax and semantic errors
  • Layout drift (outdated manual layout)

Warnings are printed, but do not fail validation unless --max-warnings is given. If any errors are found, or there are more warnings than --max-warnings allows, the command exits with a non-zero return code.

Option Description
path Path to workspace (default: current directory)
--project, -p Project to validate layout drifts of (in a multi-project workspace)
--file, -f Only report errors and warnings from these files (repeatable)
--no-layout Skip layout drift validation
--max-warnings Fail when there are more warnings than this number, 0 fails on any warning (default: unlimited)
--json Output as JSON: valid, errors, warnings, maxWarnings and stats with error and warning counts

Format .c4 source files in place:

Terminal window
# Format all files in current workspace
likec4 format
# Alias
likec4 fmt
# Format a specific workspace directory
likec4 format ./my-project
# Format only specific project(s) in a multi-project workspace
likec4 format --project alpha --project beta
# Format specific files
likec4 format --files src/model.c4 --files src/views.c4
# Check mode (CI-friendly, exits with code 1 if any file needs formatting)
likec4 format --check
Option Description
path Path to workspace (default: current directory; falls back to LIKEC4_WORKSPACE env)
--project, -p Format only specific project(s) by name (repeatable)
--files Format only specific files (repeatable)
--check Check if files are formatted without writing changes

List, apply or discard model diffs:

Terminal window
# List diffs and the views they change
likec4 diff list
# Print the changes of each file, without writing them
likec4 diff apply rfc1 --dry-run
# Apply a diff to the model
likec4 diff apply rfc1
# Delete a diff without changing the model
likec4 diff discard rfc1
Option Description
[path] Directory with LikeC4 sources (default: current directory)
--project, -p Select the project by name or path (multi-project workspace)
--json list only: print the diffs as JSON
--dry-run apply and discard only: print the changes of each file, and overlaps with diffs
--accept-overlaps apply only: apply a diff that overlaps with other diffs, once their owners agreed

A diff with errors is not applied, and a diff that overlaps with other diffs is applied only with --accept-overlaps.

In a workspace with several projects, list shows the diffs of all projects, and apply and discard use the project that has the diff. Use --project if several projects have a diff with this name. With --json, the output has only JSON; logs go to stderr.

Remove an element and everything that references it (see safe delete):

Terminal window
# Report what the removal takes with it
likec4 safe-delete cloud.legacy --dry-run
# Remove the element
likec4 safe-delete cloud.legacy
Option Description
[path] Directory with LikeC4 sources (default: current directory)
--project, -p Select the project by name or path (multi-project workspace)
--dry-run Only report the impact, do not change files
--orphans Also remove elements left without relationships
--scoped-views Also remove views scoped to removed elements
--dynamic-steps Also remove dynamic view steps with removed elements
--json Print the dry-run report as JSON

In a workspace with several projects, the command uses the project that has the element. Use --project if several projects have an element with this name.

Both commands exit with code 1 if the diff or the element does not exist, if the edit is refused, or if errors are left: in the changed files, or new errors in other files (for example, in other diffs).

Upload the layouted models to LikeC4 Cloud, as a snapshot of the current commit:

Terminal window
# Publish all projects from the current directory
likec4 publish --token <token>
# Publish a single project
likec4 publish -p my-project ./src/likec4
# Publish without a git repository (both flags are required then)
likec4 publish --origin acme/architecture --sha $GIT_SHA
Option Description
path Directory with LikeC4 sources (default: current directory)
--token Publish token (default: LIKEC4_PUBLISH_TOKEN env var)
--url Cloud base URL (default: LIKEC4_CLOUD_URL env var, then https://likec4.app)
--project, -p Publish a single project by name or path; if not set, publishes all
--origin Repository as owner/repo (default: from the git remote origin)
--sha Commit sha (default: git HEAD)
--branch Branch (default: from CI environment variables, then from git)
--tag Tag (default: from CI environment variables, then git tag --points-at HEAD)
--force Publish even if the model has validation errors or an icon file cannot be read
--use-dot, --use-dot-bin Use local Graphviz (dot) for layout instead of bundled WASM; false by default, true when inside container

A snapshot is keyed by commit: publishing the same commit again overwrites its snapshot. Projects accumulate into a snapshot: publishing one project does not remove the others.

In GitHub Actions, branch and tag are read from the workflow environment:

- uses: actions/checkout@v7
- run: npx likec4 publish
env:
LIKEC4_PUBLISH_TOKEN: ${{ secrets.LIKEC4_PUBLISH_TOKEN }}

Commands of the LeanIX bridge map the LikeC4 model to LeanIX fact sheets and relations. LikeC4 remains the source of truth. All commands write their artifacts to --outdir, -o (default: out/bridge in the current directory).

Command Description
likec4 gen leanix dry-run Write manifest.json, leanix-dry-run.json and report.json; does not call LeanIX
likec4 gen leanix inventory Read the LeanIX inventory and write leanix-inventory-snapshot.json; --likec4-id-attribute sets the LeanIX attribute that holds LikeC4 ids
likec4 gen leanix reconcile Match manifest.json with leanix-inventory-snapshot.json and write reconciliation-report.json
likec4 sync leanix --dry-run Write the dry-run artifacts, and sync-plan.json when LEANIX_API_TOKEN is set (default mode)
likec4 sync leanix --apply Write the artifacts, then create and update fact sheets and relations in LeanIX, and store LeanIX ids in the manifest

Commands that call LeanIX need LEANIX_API_TOKEN; LEANIX_BASE_URL sets the instance (default: https://app.leanix.net). dry-run, reconcile and sync also take --project, -p and --use-dot.

To export diagrams with LeanIX metadata, see Draw.io — Export profiles.

Start the LikeC4 language server for use with editors that support the Language Server Protocol:

Terminal window
likec4 lsp --stdio
likec4 lsp --node-ipc
likec4 lsp --socket 3000
likec4 lsp --pipe /tmp/likec4.pipe

One of the transport options (--stdio, --node-ipc, --socket, --pipe) is required.

Option Description
--stdio Use stdio transport
--node-ipc Use node-ipc transport
--socket <port> Use socket transport on specified port
--pipe <name> Use pipe transport with specified pipe name
--watch, -w Enable built-in watcher (disabled by default)
--no-manual-layouts Disable manual layouts (enabled by default)
--use-dot, --use-dot-bin Use local Graphviz (dot) for layout instead of bundled WASM; false by default, true when inside container

Start the LikeC4 MCP server for AI agents:

Terminal window
# stdio transport (default)
likec4 mcp
# Streamable HTTP transport on port 33335
likec4 mcp --http ./src
# Streamable HTTP transport on port 1234
likec4 mcp --port 1234
Option Description
--stdio Use stdio transport (default)
--http Use streamable HTTP transport on port 33335
--port, -p Use streamable HTTP transport on this port
--use-dot, --use-dot-bin Use local Graphviz (dot) for layout instead of bundled WASM; false by default, true when inside container

List the bundled icons:

Terminal window
likec4 list-icons
likec4 list-icons --group aws
likec4 list-icons --format json
Option Description
--group, -g Only icons of this group: aws, azure, gcp, md, tech or bootstrap
--format, -f text (default, one group:name per line) or json

Print a completion script for bash or zsh, and add it to the shell profile:

Terminal window
likec4 completion >> ~/.bashrc
# or
likec4 completion >> ~/.zshrc
Terminal window
likec4 check-update

Prints whether a newer version of likec4 is available on npm.