LikeC4 CLI 完整命令参考从校验、导出到代码生成与 MCP 集成【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4likec4是一个以 npm 包形式分发的命令行工具用于在本地处理 LikeC4 架构模型校验语法与布局漂移、启动带热更新的预览服务器、导出 PNG/JSON/DrawIO 等格式并通过gencodegen生成 TypeScript 模型、React 组件、Web Component 以及 Mermaid、PlantUML、D2、Graphviz 等图表文件还可以直接以 MCP 模式接入 AI 工具链。本文以仓库中 CLI 参考文档 为主线结合 CLI 源码 逐条讲解每个命令的正确用法、常见误区与底层实现帮助你在实际项目中一次写对命令、快速排错。前置准备包管理与版本要求likec4是独立分发的 npm 包见 packages/likec4/package.json当前仓库版本为 1.59.3它通过bin字段./bin/likec4.mjs暴露likec4可执行命令要求 Node.js22.22.3。使用时有以下几点需要注意用工作区的包管理器运行示例中使用bunx仅为演示实际应优先使用工作区自己的包管理器bun、pnpm、npm均可。非 npm 项目的回退链如果工作区不是 npm 项目按bunx可用时→pnpx可用时→npx的顺序选择运行器。版本下限如果工作区已将likec4列为依赖先检查package.json中的版本确保至少为1.53.0否则建议固定版本运行例如bunx likec41.53.0 ...避免不同版本间的行为差异。完整帮助CLI 文档只列出核心命令与参数完整用法请随时使用likec4 help和likec4 command --help查询。从源码看CLI 基于yargs构建在 packages/likec4/src/cli/index.ts#L60-L124 中依次注册了serve、build、gen、export、format、preview、publish、sync、validate、list-icons、mcp、lsp、check-update等命令并统一提供全局选项--log-level、--verbose、--color支持FORCE_COLOR/NO_COLOR环境变量、--help、--version。所有命令失败时都会以退出码 1 结束见 index.ts#L131-L140因此可以在 CI 中直接以退出码判断成功与否。高频命令速查与常见错误下表整理了对日常高频任务的推荐写法来自原文档可直接复制使用任务正确命令校验文件bunx likec4 validate --json --no-layout --file file [project-dir]启动开发服务器bunx likec4 serve [project-dir]导出 PNGbunx likec4 export png -o ./images [project-dir]构建静态站点bunx likec4 build -o ./dist [project-dir]列出图标bunx likec4 list-icons或bunx likec4 list-icons --group tech注意export png的-o同时支持--outdir写法但不支持--out-dir带连字符的拼写是无效 flag。常见错误对照务必避开错误写法失败原因正确写法bunx likec4 check ...命令不存在bunx likec4 validate ...bunx likec4 lint ...命令不存在bunx likec4 validate ...bunx likec4 verify ...命令不存在bunx likec4 validate ...bunx likec4 export png --out-dir ./images未知 flag--out-dir-o ./images或--outdir ./images之所以经常有人写check/lint/verify是因为很多工具链用这些词表校验而 LikeC4 的校验统一收敛在validate命令上。从 validate/index.ts 的实现看validate实际会做两类检查一类是语法与语义错误来自languageServices.getErrors()包含消息、文件路径、行号和 range另一类是布局漂移layout drift需要布局引擎参与并可通过--json输出结构化结果、-f/--file过滤仅报告指定文件、--no-layout跳过布局检查。serve别名start、dev启动本地预览服务器支持热重载live reload默认端口5173。bunx likec4 serve [project-dir] bunx likec4 serve --port 3000 [project-dir]启动后控制台会打印访问 URL直接在浏览器中打开即可预览全部图表要定位到某个具体视图在 URL 后追加路径/view/view-id。底层实现上serve通过 serve/serve.ts 基于 Vite 构建开发服务器会以watch模式初始化语言服务fromWorkspace(path, { watch: enableHMR })按需启用 Web Component 构建与 HMR端口通过--port指定默认 5173也支持--listen默认127.0.0.1、--base、--use-hash-history、--hmr-port等参数。开发模式下NODE_ENV会被显式设置为development并在服务就绪后打印所有可访问的 Server URLs。build别名bundle构建可部署的静态站点bunx likec4 build -o ./dist [project-dir]该命令会把整个工作区含所有视图、图标资源打包成纯静态产物输出到-o指定的目录适合托管到任意静态站点服务。对于需要交互编辑场景仓库中还有preview本地预览已构建产物与publish打包发布等命令可通过likec4 help查看。export导出多种格式export format [path]在源码中注册了png、jpg、json、drawio、markdown五个子命令见 export/index.ts。导出 PNG依赖 Playwright# 基础导出输出到 ./images bunx likec4 export png -o ./images [project-dir] # 深色主题 扁平目录 仅导出 overview* 视图 bunx likec4 export png --theme dark --flat -f overview* -o ./images [project-dir]export png可用参数--outdir-o输出目录不指定时PNG 会保存到源文件旁边保持源目录结构。--themelight|dark默认light另有快捷开关--dark/--light。--flat--flatten将所有图片扁平化到输出目录忽略源目录结构。--filter-f按视图 id 的 glob 模式过滤多个模式取 OR。--seq--sequence动态视图dynamic views使用时序图布局。--timeout-tPlaywright 超时秒默认15。--max-attempts失败视图的最大重试次数默认3。--ignore-i部分视图导出失败时继续不中断整体导出。--notation/--description在导出图片中附带视图图例说明/视图描述。--server-url复用已运行的 LikeC4 服务器地址而不是新启动一个。--chromium-sandbox是否启用 Chromium 沙箱默认关闭详见 Playwright 文档。实现上PNG 导出流程export/png/handler.ts会初始化工作区语言服务 → 若未指定--server-url则启动临时 Vite 预览服务器 → 对每个项目多项目时按项目分流 URL 与输出目录取出视图列表用picomatch按-f过滤 → 启动 headless ChromiumdeviceScaleFactor: 2、按主题设置colorScheme对每个视图逐个截图写入输出目录。--filter的匹配基于视图 id而非文件名这一点在写 glob 时要留意。导出 JSON 模型bunx likec4 export json -o model.json --pretty --skip-layout [project-dir]参数--outfile-o默认likec4.json、--pretty缩进格式化输出、--skip-layout跳过布局计算只产出 compute-only 模型速度更快。对应实现见 export/json/handler.ts默认调用languageServices.layoutedModel(id)生成带布局的模型数据--skip-layout时改用computedModel(id)输出文件若缺.json扩展名会自动补上多项目时会生成数组结构单项目则直接输出模型对象。该 JSON 是ComputedLikeC4ModelData/LayoutedLikeC4ModelData的序列化结果可被likec4/core等工具消费。导出 DrawIObunx likec4 export drawio --all-in-one -o ./diagrams [project-dir]参数--outdir-o、--all-in-one所有视图合并到一个文件、--roundtrip、--uncompressed、--profiledefault|leanix。LeanIX 桥接与 Draw.ioLeanIX profile当任务明确是LeanIX 资产盘点inventory、桥接产物bridge artifacts或需要稳定 bridge 管理 id 的 Draw.io 导出时使用以下命令仅做泛泛的 DSL 编辑不需要它们任务命令生成 manifest LeanIX dry-run 报告bunx likec4 gen leanix dry-run -o out/bridge [project-dir]同步工作流先审阅再应用bunx likec4 sync leanix --dry-run -o out/bridge [project-dir]/bunx likec4 sync leanix --apply -o out/bridge [project-dir]导出带likec4Id、bridgeManaged等属性的 Draw.iobunx likec4 export drawio --profile leanix -o ./diagrams [project-dir]完整的边界说明、round-trip往返导入导出注意事项以及 MCP 与 bridge 的职责划分参见 skills/likec4-dsl/references/bridge-leanix-drawio.md。codegen别名gen、generate从模型生成代码产物# TypeScript 模型类型化包含全部视图与元素 bunx likec4 gen model -o likec4-model.ts [project-dir] # React 组件 bunx likec4 gen react -o dist/likec4-views.mjs [project-dir] # Web Component JS 包 bunx likec4 gen webcomponent -o likec4.js -w c4 [project-dir] # 图表格式文件 bunx likec4 gen mermaid -o ./out # .mmd 文件 bunx likec4 gen plantuml -o ./out # .puml 文件 bunx likec4 gen d2 -o ./out # .d2 文件 bunx likec4 gen dot -o ./out # .dot 文件Graphviz共享参数--outfile/--outdir-o、--project-p、--use-dot。从 codegen/index.ts 的注册信息可以补充更多细节gen react输出渲染 LikeC4 视图的 React 组件文件.jsx/.mjs/.js。gen webcomponent别名wc、webcomp输出自定义元素 JS可通过--webcomponent-prefix自定义元素前缀对应示例中的-w c4。gen model别名ts生成类型化的LikeC4Model.ts支持--skip-layout跳过布局加速生成。gen leanix包含dry-run、inventory、reconcile三个子命令——dry-run生成 manifest.json、leanix-dry-run.json、report.jsoninventory只读拉取 LeanIX 资产快照需要LEANIX_API_TOKEN环境变量写入 leanix-inventory-snapshot.jsonreconcile将 manifest 与快照对账输出 reconciliation-report.json。默认输出目录为out/bridge。还支持gen mermaid|plantuml|d2|dot等文本图表格式以及通过custom运行 LikeC4 配置中定义的自定义生成器。仓库中对应生成器的具体实现分布在 packages/generators/src如mmd/、puml/、d2/、drawio/、react/、views-data-ts/等目录想要理解输出细节可以继续深入。mcp以 MCP 协议接入 AI 工具LikeC4 原生支持 Model Context Protocol让 AI 助手可以直接读取、解析、查询架构模型bunx likec4 mcp [workspace] # stdio 传输默认 bunx likec4 mcp --http [workspace] # HTTP 传输端口 33335 bunx likec4 mcp -p 1234 [workspace] # HTTP 传输自定义端口选项--stdio默认、--http、--port-p默认33335、--use-dot。从 mcp/index.ts 的实现看HTTP 模式会调用startLikeC4MCP({ workspacePath, mcp: { port }, watch: true })服务地址为http://localhost:port/mcp对应的mcpServers配置片段likec4条目指向该 URL会直接打印在控制台可粘贴到支持 MCP 的客户端stdio 模式则通过mcp: stdio启动日志重定向到 stderr 以保证 stdout 纯净。watch: true意味着模型变化时 MCP 工具能感知最新状态。list-icons快速查看内置图标列出全部内置图标速度快无需初始化工作区bunx likec4 list-icons # 全部图标每行一个 group:name bunx likec4 list-icons --format json # 按分组输出 JSON 对象 bunx likec4 list-icons --group aws # 只列 AWS 图标 bunx likec4 list-icons --group tech -f json # tech 分组图标JSON 格式选项--format-ftext默认或json、--group-g取值aws、azure、gcp、tech、bootstrap。图标分组规模来自仓库内置图标库 packages/icons可作为参考aws约 307 个azure约 614 个gcp约 216 个tech约 2000 个bootstrap约 2051 个实现上list-icons/index.ts命令直接读取语言服务的iconRegistry与iconGroupstext 模式逐行输出group:namejson 模式则输出{ group: [names...] }结构。图标命名可直接用于 DSL 中icon: aws:lambda之类的引用。format原地格式化源文件bunx likec4 format [workspace]对工作区内所有 LikeC4 源文件.c4执行原地格式化规范化缩进与排版适合提交前统一风格。完整参数可用likec4 format --help查看。实战建议小结校验进 CI用likec4 validate --json --no-layout获得机器可读结果配合退出码0/1做门禁需要校验布局漂移时去掉--no-layout但会显著增加耗时。导出按需过滤PNG 导出量大时先用-f过滤视图 id或配合--flat扁平输出、--seq处理动态视图注意-f匹配的是视图 id。多项目工作区validate、export、gen都支持--project/-p指定项目多项目导出 PNG 时会按项目分子目录。AI 集成首选mcp需要让 Agent 读取模型时用likec4 mcp --http起 HTTP 服务并把mcpServers配置交给客户端比直接解析文件更省事。不存在的命令不要试check/lint/verify均未注册统一使用validateflag 拼写以--outdir为准--out-dir会直接报 Unknown flag。【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考