LikeC4 CLI
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
Install
Section titled “Install”Local installation
Section titled “Local installation”If you’re using it in an npm project, install it as a development dependency:
npm i -D likec4pnpm add -D likec4yarn add -D likec4bun add -d likec4You can reference it directly in the package.json#scripts object:
{ scripts: { dev: 'likec4 dev ...', build: 'likec4 build ...' }}Run without installing
Section titled “Run without installing”To fetch and execute the package binary without installing it, e.g. to start the dev server:
npx likec4 startpnpx likec4 startyarn dlx likec4 startbunx likec4 startGlobal installation
Section titled “Global installation”To use it in any project without npx, install it globally:
npm install --global likec4
# Then, you can call `likec4` directly:likec4 [command]Almost all commands have a --help option and provide usage examples.
likec4 build -hlikec4 gen react -hOptions 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.
Short options
Section titled “Short options”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).
Preview and build
Section titled “Preview and build”Preview diagrams
Section titled “Preview diagrams”In a folder with LikeC4 sources:
likec4 start# Aliases:likec4 servelikec4 devThis 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) |
Build static website
Section titled “Build static website”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 "./".
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:
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.
Export
Section titled “Export”likec4 export <format> [path] exports views or the whole model.
Formats: png, jpg, json, markdown and drawio.
Export to PNG and JPEG
Section titled “Export to PNG and JPEG”likec4 export png -o ./assetslikec4 export jpg -o ./assets --quality 90This 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 to JSON
Section titled “Export to JSON”Export the model (elements, relationships and views) to a JSON file:
likec4 export json -o dump.jsonlikec4 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.
Export to Markdown
Section titled “Export to Markdown”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.
likec4 export markdownlikec4 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 to Draw.io
Section titled “Export to Draw.io”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.
likec4 export drawiolikec4 export drawio -o ./diagramslikec4 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 |
Generate (likec4 gen)
Section titled “Generate (likec4 gen)”likec4 gen <generator> [path] generates source files from the model.
The command has two aliases, likec4 generate and likec4 codegen.
Generate Mermaid, Dot, D2, PlantUml
Section titled “Generate Mermaid, Dot, D2, PlantUml”likec4 gen mermaidlikec4 gen mmd # aliaslikec4 gen dotlikec4 gen d2likec4 gen plantumllikec4 gen puml # alias
likec4 gen mermaid -o ./diagrams src/likec4One 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.
Generate components and model
Section titled “Generate components and model”| 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.
Validate and format
Section titled “Validate and format”Validate
Section titled “Validate”likec4 validate
# Fail on any warning (e.g. in CI)likec4 validate --max-warnings 0
# Structured output, only for the given fileslikec4 validate --json --file src/model.c4This 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
Section titled “Format”Format .c4 source files in place:
# Format all files in current workspacelikec4 format# Aliaslikec4 fmt
# Format a specific workspace directorylikec4 format ./my-project
# Format only specific project(s) in a multi-project workspacelikec4 format --project alpha --project beta
# Format specific fileslikec4 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 |
Edit the model
Section titled “Edit the model”Model diffs
Section titled “Model diffs”List, apply or discard model diffs:
# List diffs and the views they changelikec4 diff list# Print the changes of each file, without writing themlikec4 diff apply rfc1 --dry-run# Apply a diff to the modellikec4 diff apply rfc1# Delete a diff without changing the modellikec4 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.
Safe delete
Section titled “Safe delete”Remove an element and everything that references it (see safe delete):
# Report what the removal takes with itlikec4 safe-delete cloud.legacy --dry-run# Remove the elementlikec4 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).
Publish to LikeC4 Cloud
Section titled “Publish to LikeC4 Cloud”Upload the layouted models to LikeC4 Cloud, as a snapshot of the current commit:
# Publish all projects from the current directorylikec4 publish --token <token># Publish a single projectlikec4 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 }}LeanIX bridge
Section titled “LeanIX bridge”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.
Other commands
Section titled “Other commands”Language Server (LSP)
Section titled “Language Server (LSP)”Start the LikeC4 language server for use with editors that support the Language Server Protocol:
likec4 lsp --stdiolikec4 lsp --node-ipclikec4 lsp --socket 3000likec4 lsp --pipe /tmp/likec4.pipeOne 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 |
MCP server
Section titled “MCP server”Start the LikeC4 MCP server for AI agents:
# stdio transport (default)likec4 mcp# Streamable HTTP transport on port 33335likec4 mcp --http ./src# Streamable HTTP transport on port 1234likec4 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 icons
Section titled “List icons”List the bundled icons:
likec4 list-iconslikec4 list-icons --group awslikec4 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 |
Shell completion
Section titled “Shell completion”Print a completion script for bash or zsh, and add it to the shell profile:
likec4 completion >> ~/.bashrc# orlikec4 completion >> ~/.zshrcCheck for updates
Section titled “Check for updates”likec4 check-updatePrints whether a newer version of likec4 is available on npm.