Archyl CLI

archyl 把代码仓库与它在 Archyl 中的架构连接起来。在终端里，您可以查找某个文件在 C4 模型中的位置，查看您的分支影响了什么、该通知谁，在编程代理动手改代码之前向它提供简报，并守护它写下的内容。

$ archyl impact

◆ archyl  impact  vs origin/main · 14 changed files

▍ Touched
  ◉ HTTP Handlers    3 files    Archyl / Backend
  ◉ Harness Service  3 files    Archyl / Backend
  ◉ Task Context     1 file     Archyl / Backend

▍ Blast radius
  ◉ Harness Service
  ├── ◉ HTTP Handlers  calls · 1 hop   @platform
  ├── ◉ MCP Server     calls · 1 hop
  ╰── ▣ Frontend       calls · 2 hops  @web

▍ Notify
  @platform · @web · ada@example.com

CLI 以 MIT 许可证开源：github.com/archyl-com/cli。

安装

# Homebrew (macOS, Linux)
brew install archyl-com/tap/archyl

# Install script (macOS, Linux): checks the archive's checksum
curl -fsSL https://raw.githubusercontent.com/archyl-com/cli/main/install.sh | sh

# Go (1.26 or later)
go install github.com/archyl-com/cli/cmd/archyl@latest

您也可以从发布页面下载二进制文件。归档文件附带校验和，使用 cosign 签名，并随附 SBOM。

用 archyl --version 检查安装是否成功。

快速上手

在代码仓库的根目录下：

archyl login          # sign in through your browser
archyl init           # link this repository to its Archyl project
archyl status         # alignment score, your branch, active agents

archyl login 会打开浏览器，通过 OAuth 2.1 和 PKCE 完成登录。会话保存在操作系统的钥匙串中并会自动续期；只有连续一个月未使用后，才需要重新登录。

archyl init 会在仓库根目录写入 .archyl.json，让每条 archyl 命令以及 Guard 钩子都知道这份代码属于哪个项目。如果仓库的远程地址已关联到 Archyl 中的某个项目，就会自动选中该项目；否则需要您从列表中选择。请提交这个文件：它不包含任何密钥，这样您的团队和 CI 就能共享这一关联。

{
  "projectId": "3f2a9c4e-…",
  "projectName": "Checkout",
  "organizationId": "8b1d…",
  "apiUrl": "https://api.archyl.com"
}

运行 archyl init --force 可以把仓库重新关联到另一个项目。

还没有项目？ archyl init --new 无需离开终端就能创建一个：

1. 以仓库名（或 --name）创建项目，放在你选择的团队中（--team，可用名称、slug 或 ID）。
2. 根据 git remote 连接仓库。对于自托管的 remote，用 --provider 指定提供方：github_enterprise、gitlab_private 或 gitea。
3. 在 --branch（默认：remote 的默认分支）上运行 AI 发现，并实时显示进度。
4. 打开对发现结果的评审，然后把结果绘制成 图表。
5. 提议 连接你的编码代理。

不带参数的 archyl init 在没有项目匹配仓库 remote 时也会提议同样的流程。--no-discover 只创建并关联项目，--no-setup 跳过最后一步，--yes 不再询问、全部采用默认值，包括批准发现找到的内容。

archyl init --new
archyl init --new --name "Checkout" --team platform
archyl init --new --yes --json

会话

单独运行 archyl 即可打开一个会话：这是一个提示符界面，您可以用自然语言询问架构问题或输入命令，回答会像其他输出一样直接显示在终端中。

$ archyl

◆ archyl
  Checkout · feature/refunds · alignment 86
  Ask anything about the architecture. / commands · @ files · # elements

› which elements does my branch touch, and who should I tell?
  ⏺ archyl impact
    Touched  ◉ Payments  4 files  in Checkout / API
    … +12 lines

  Your branch changes Payments, which Checkout Web calls and the Refund
  Worker reads. Tell @payments before merging.

› /run last

• 自然语言 交给助手处理。它基于架构作答；当答案取决于您的代码或当前正在发生的事情时，它会在这里运行相应的命令——impact、check、brief、show、runs……——并在使用其输出之前逐一显示（⏺）。只读命令会并行运行；会改变内容的命令，例如批准某次运行的计划或记录一条记忆，会先征得您的同意（y/n）。
• / 命令 直接运行：/impact、/review、/brief <files>、/show <element>、/runs、/activity……全屏视图（/map、/search、/run、/agents）会占据整个屏幕，退出后再把屏幕交还给您。/help 列出全部命令。
• @file 会把文件内容连同其架构简报附加到问题中：每个文件最多 400 行或 24 KB；二进制文件和仓库之外的路径会被跳过。#element 将问题指向某个元素。两者在输入时都会自动补全。
• Enter 发送；Shift+Enter（或 Alt+Enter、Ctrl+J）换行，粘贴的文本会保留其换行。
• ↑ ↓ 浏览历史记录，Tab 补全，Esc 停止回答，Ctrl-D 退出。

对话按仓库保存：archyl -c（--continue）重新打开上一次对话，/resume 从列表中选择更早的对话，/new 开始一个新对话。

首次使用时，会话会告诉您还缺少什么：登录（/login）、关联仓库（/init）。包含 AI 聊天的套餐可以使用助手；/ 命令适用于所有套餐。使用 OpenAI 和 Anthropic 模型时，助手以原生工具的方式调用命令；使用其他提供商时则通过文本协议，您感觉不到任何区别。

doctor

archyl doctor 会检查 CLI 依赖的所有内容，并告诉您如何修复有问题的地方：您的版本、配置文件、登录状态、API 延迟、仓库、项目关联、已连接的代理、Guard 钩子和 pre-push 钩子。当有需要修复的问题时，它以退出码 1 退出。

探索架构

activity

archyl activity 把项目上发生的一切汇集到一个事件流中：创建和变更的元素（附带变更的字段）、打开和合并的变更请求、排队中、等待他人处理和已结束的代理运行，以及打开和关闭的工作会话。--follow 会保持打开，并像 tail -f 一样在事件发生时实时输出；加上 --notify 可在代理等待您处理时收到桌面通知。

archyl activity --follow --notify
archyl activity --element "Payments"

map

archyl map 会打开一个全屏的 C4 模型浏览器：系统、容器、组件和代码以树形展示，并显示每个元素的描述、技术、双向关系和影响范围。指定一个元素名称即可直接从它打开：archyl map "Payments"。

按 d 以 图表 显示当前层级。Tab 和 Shift+Tab 选择元素，方向键或 h j k l 滚动，Enter 进入所选元素，Backspace 或 u 返回上一层，o 在 Web 应用中打开，y 复制它的 ID，d 或 Esc 回到树视图。

diagram

archyl diagram 绘制模型的 C4 视图：默认是系统上下文；指定一个系统时绘制它的容器，指定一个容器时绘制它的组件。视图之外的元素以虚线显示，以呈现它们与视图的关系。

archyl diagram
archyl diagram Billing
archyl diagram "Billing API" -o billing-api.png
archyl diagram --format mermaid > context.mmd
archyl diagram Billing --json | jq '.nodes[].name'

在 Kitty、Ghostty、WezTerm 和 iTerm2 中，图表是终端内的图片。在其他终端中，以及输出通过管道时，它用制表符绘制：

 ┌─────────────────┐   ┌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┐   ┌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┐
 │ ▣ Storefront    │   ╎ ◆ Warehouse     ╎   ╎ ◆ Mailgun       ╎
 │ web app · React │   ╎ software system ╎   ╎ software system ╎
 └────────┬────────┘   └╌╌╌╌╌╌╌╌┬╌╌╌╌╌╌╌╌┘   └╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┘
          │                     │
          └───────────────┐     │ updates stock
         places orders ×2 │     │
                          ▼     ▼
                    ┌─────────────────┐
                    │ ▣ Shop API  4 ◉ │
                    │ api · Go        │
                    └─────┬─────┬─────┘
            charges cards │     │ reads from ×2
                          ▼     ▼

在 tmux 中显示图片需要 set -g allow-passthrough on，以及支持 iTerm2 图片协议的终端。设置 ARCHYL_IMAGES=0 可始终以文本绘制。

search

archyl search 会搜索您在 Archyl 中能看到的一切：元素、决策、文档、API 契约、事件通道、流程和项目。结果随输入实时更新并附带预览；Enter 显示所选项，ctrl+o 在 Web 应用中打开它。通过管道使用或加上 --json 时，archyl search invoice 会输出匹配结果。

show

archyl show <element> 输出一个元素及其路径、描述、技术、关系、关联的决策和影响范围。archyl show ADR-12 会渲染一条决策记录。元素按名称（先精确匹配，再部分匹配）或 ID 查找。

open

archyl open 会在 Web 应用中打开项目；archyl open "Payments" 会在图中选中一个元素，archyl open ADR-12 会展开一条决策。Web 应用的地址是把 API 主机中的 api. 替换为 app.；如果它在别处，请用 --app-url 登录，或设置 ARCHYL_APP_URL。

ask

archyl ask "<question>" 会就项目的架构向 AI 助手提问。回答在生成的同时以 markdown 渲染。通过管道传入的任何内容都会追加到问题中：

archyl ask "Which services write to the orders database?"
git diff main | archyl ask "Does this break any of our decisions?"

包含 AI 聊天的套餐可以使用该助手。

adr

archyl adr 列出项目的决策。archyl adr new 记录一条新决策：在终端中，会有一个表单询问标题、状态、背景、决策和后果；在脚本中，则以参数形式传入。

archyl adr new "Use slog for structured logging" --status accepted \
  --context "Three logging libraries are in use" --decision "slog everywhere"

discover

archyl discover 在关联到项目的仓库上启动一次 AI 发现并跟踪它，进度输出到 stderr。它发现的内容不会立即加入模型，而是等待评审；在终端中，发现结束时评审界面会自动打开。每个关联的仓库都会占用套餐 AI 发现配额中的一次。

archyl discover
archyl discover --repo acme/payments --branch develop
archyl discover --no-wait --json

archyl discover review 按 C4 层级分组列出发现提出的元素，并在侧边显示所选元素的详情：

在终端之外，它会输出列表；--approve-all 或 --reject-all 一次性处理全部内容，--json 以供脚本使用的格式输出。

架构命令

where

archyl where <path>… 在 C4 模型中定位文件：每个文件所属的元素、负责人以及依赖它的内容。目录会展开为 git 所跟踪的文件。

archyl where internal/billing/invoice.go
archyl where src/checkout/

why

archyl why <file[:line]> 是架构版的 git blame。对于一个文件，它显示文件所属的元素、适用的决策（已接受的排在前面）、负责人、代理和成员记下的相关信息、这些元素最近的模型变更，以及针对该文件的合规规则。加上行号时，它还会找到最后修改该行的提交，并把它与同一时期做出的决策关联起来。

archyl why internal/billing/invoice.go
archyl why internal/billing/invoice.go:42
archyl why --json src/checkout/cart.ts | jq '.decisions[].title'

在终端中，结果以排版后的形式显示；通过管道或由代理运行时，输出精简的 markdown。

impact

archyl impact 会把您的工作区与一个基准分支进行比较，在架构中定位每个变更的文件，并沿着关系查找依赖它的内容，同时列出需要通知的负责人。它涵盖已提交、已暂存、未暂存和未跟踪的变更，因此您甚至可以在提交之前就运行它。

archyl impact --base origin/develop --depth 3
archyl impact --diagram

每个文件只计入最具体的匹配：映射到某个组件的文件，不会把它所在的整个容器也牵连进来。

status

archyl status 把项目浓缩在一屏之内：模型与代码的对齐度、您当前的分支，以及此刻正在该项目上工作的代理。

context

archyl context 以针对编程代理优化的 markdown 输出项目的架构：系统、容器、组件、关系、决策和规则。可以通过管道传递，也可以写入您的代理会读取的文件。

archyl context > ARCHITECTURE.md
archyl context -o .archyl/context.md

编程代理

CLI 是让编程代理置于 Archyl Harness 之下的最快方式。

setup

archyl setup

archyl setup 会配置 Claude Code、Cursor、VS Code 和 Codex，让它们以 coding 工具配置文件使用 Archyl 的 MCP 服务器，安装 Guard 钩子，并教会代理使用 CLI。可以用 --agent（可重复：claude-code、cursor、vscode、codex）限定范围；用 --no-guard、--no-instructions 或 --no-statusline 跳过其中某些部分。

archyl setup 还会提议安装 Shell 自动补全；--no-completion 可跳过。

已有文件会被合并，而不是覆盖。

默认情况下（--transport cli），每个代理都会启动 archyl mcp，它使用 CLI 自身的会话连接 Archyl 的 MCP 服务器：只需用 archyl login 登录一次，所有代理就都已连接，无需为每个代理走 OAuth 流程，也无需在文件中存放密钥。使用 --transport http 时，配置中只包含服务器 URL，每个代理都通过 Archyl 本身登录。无论哪种方式，仓库中的文件都不含任何机密，可以放心提交。

mcp

archyl mcp 以您的身份通过 stdio 向代理提供 Archyl 的 MCP 工具。archyl setup 会配置它；如需为任意 MCP 客户端手动配置：

{ "mcpServers": { "archyl": { "command": "archyl", "args": ["mcp"] } } }

它使用 coding 工具配置文件；--tools full 会开放全部工具。

CLI 区块是位于 <!-- archyl:start --> 与 <!-- archyl:end --> 标记之间的一小段内容，告诉代理何时运行哪些 archyl 命令：进行非琐碎的变更之前运行 plan，编辑文件之前运行 brief，收尾之前运行 check 和 radar check，用 remember 和 recall 记录与查找代码无法体现的内容。再次运行 setup 会刷新该区块，文件的其余部分保持不变。Claude Code 中已设置的状态栏永远不会被替换。

plan

archyl plan "<task>" 返回一份基于架构的实施计划：各个步骤、每一步涉及的元素、需要遵守的决策和规则，以及之前的会话积累的经验。

archyl plan "Add partial refunds to the payments flow"

brief

archyl brief <files> 告诉您或代理在编辑这些文件之前需要了解什么：它们所属的元素、这些元素使用的内容以及依赖它们的内容、适用于它们或其父元素的决策、负责人，以及 Archyl 记住的关于它们的内容。不指定路径时，它涵盖分支变更的所有文件。

与 plan、recall 和 context 一样，它在终端中渲染显示；当代理从自己的 shell 中运行它时，则输出紧凑的 markdown，这样代理读到的是结构，而不是转义码。

remember 与 recall

archyl remember 把一条代码无法体现的事实记录在它所涉及的元素上；之后在该元素上的每个工作会话都会在简报中收到它。archyl recall 按主题、元素或类型查找 Archyl 记住的内容。

archyl remember "Refund amounts are in minor units; never use floats" \
  --element "Payments" --kind pitfall
archyl recall refunds
archyl recall --element "Payments" --kind convention

当 CLI 在 Claude Code、Codex 或 Cursor 中运行时，记忆会归属于写下它的代理；设置 ARCHYL_AGENT 可以自行指定名称。

agents

archyl agents 实时显示正在该项目上工作的代理：哪个代理、在做什么任务、在哪些元素上、改动了哪些文件。被多个代理租用的元素会被标记出来，以免两个代理在同一段代码上发生冲突。按 a 可包含最近结束的会话。通过管道使用或加上 --json 时，它会一次性输出会话列表。

statusline

archyl statusline 是 Claude Code 的状态栏：显示项目、它的对齐度分数、正在工作的代理，以及当前会话是否在 harness 之下运行。archyl setup 会安装它；如需手动配置，在 .claude/settings.json 中：

{ "statusLine": { "type": "command", "command": "archyl statusline" } }

runs

archyl runs 列出项目的托管代理运行，并标记出等待您处理的运行。archyl runs view 实时跟进其中一个运行：事件流中显示代理的消息、工具调用和它修改的文件，计划中显示每个步骤的进度，侧栏显示耗时、token 数和费用。您无需离开终端即可对它进行操作：

同样的操作也以命令形式提供，供脚本以及监督其他代理的代理使用。运行通过其 ID 的前几个字符或 last 指定：

archyl runs start "Add partial refunds" --profile backend-fixer
archyl runs view last
archyl runs answer 3f2a9c4e "Keep the v1 endpoint"
archyl runs approve 3f2a9c4e
archyl runs request-changes 3f2a9c4e "Split the migration from the API change"
archyl runs steer 3f2a9c4e "Use the ledger service, not the orders table"
archyl runs continue 3f2a9c4e "Add tests for the edge cases"
archyl runs cancel 3f2a9c4e

托管代理运行在包含该功能的套餐中可用。

wrap

archyl wrap -- claude                                   # asks what the task is
archyl wrap --task "Add PDF export to invoices" -- claude
archyl wrap --agent codex --exclusive -- codex "fix the flaky checkout test"

archyl wrap 可以让任何代理在工作会话中运行：

1. 它为任务开启一个会话。Archyl 挑选相关的元素、决策和规则，为这些元素持有租约以免两个代理发生冲突，并返回一份附带 gate 判定的简报。
2. Claude Code 会把简报作为追加的系统提示词接收。每个代理都能在环境变量中找到 ARCHYL_SESSION_ID 和 ARCHYL_BRIEFING_FILE。
3. 在代理工作期间，会话通过每 10 分钟一次的心跳保持存活，Guard 钩子会把每个被编辑的文件归属到该会话。
4. 代理退出时，wrap 会报告变更的文件，关闭会话，并提议打开一份架构变更请求草稿，由人来评审模型该如何跟上。

如果无法连接 Archyl，wrap 会发出警告，但仍然运行代理。

fix

archyl fix
archyl fix --severity high --agent codex
archyl fix --print | pbcopy
archyl fix -- claude --model opus

archyl fix 让编码代理在 harness 下修复分支上的规则违规：

1. 像 archyl check 一样在分支上运行合规检查，并让你选择要修复的违规。
2. 打开一个工作会话，把每条违规连同其规则、严重级别、位置和建议交给代理，同时附上文件所属元素的简报和适用的决策。
3. 代理退出后，再次运行检查并显示剩余的问题，例如“3 violations → 0”。

不会提交任何内容：用 git diff 审查改动。代理是 Claude Code 和 Codex 中最先找到的已安装者，或由 --agent 指定。-- 之后可以改为运行任意命令，它从 ARCHYL_FIX_TASK_FILE 指向的文件中读取任务。

lsp

archyl lsp 是一个基于 stdio 的 Language Server，适用于任何带 LSP 客户端的编辑器。它与语言自身的服务器并行运行：

它使用 CLI 的会话（archyl login 或 ARCHYL_API_KEY）以及仓库的 .archyl.json。无法连接 Archyl 时，它只在编辑器的 LSP 日志中写一条警告，不显示诊断。诊断跟随保存，而不是按键。

Neovim 0.11 及以上：

vim.lsp.config("archyl", {
  cmd = { "archyl", "lsp" },
  root_markers = { ".archyl.json", ".git" },
  filetypes = { "go", "typescript", "python", "java", "rust" },
})
vim.lsp.enable("archyl")

Helix，在 languages.toml 中：

[language-server.archyl]
command = "archyl"
args = ["lsp"]

[[language]]
name = "go"
language-servers = ["gopls", "archyl"]

VS Code 通过 Generic LSP Client 扩展接入，Zed 通过一个小型开发扩展接入。各编辑器的配置见 docs/lsp.md。

guard

archyl guard 是 archyl setup 所安装的 Claude Code PreToolUse 钩子。它从 stdin 读取钩子负载，对编辑后的文件运行项目的合规规则，并给出决定：critical 级别的违规会拦截编辑，high 级别的违规会发出警告。将 ARCHYL_GUARD_BLOCK 设为 high 可同时拦截 high 级别的违规，设为 off 则只发出警告。

当代理编辑依赖清单（go.mod、package.json、pom.xml…）时，Guard 还会将其与技术雷达对照检查，拦截雷达中标记为暂缓的依赖，并给出其备注建议的替代方案。原本就已存在的暂缓依赖不会拦截编辑。

Guard 始终采用 fail-open：没有凭据、没有网络或遇到未知工具时都会放行编辑，因此它永远不会破坏您的工作流。

session

archyl session 提供对工作会话协议的底层访问，适用于自行驱动该协议的脚本或代理。大多数情况下，archyl wrap 会替您完成这一切。

archyl session start --task "Migrate invoices to the new ledger" --exclusive
archyl session heartbeat <session-id>
archyl session finish --summary "Ledger migration done" \
  --decision "Invoices are written through the ledger service only" \
  --follow-up "Backfill invoices older than 2024" \
  --change-request
archyl session list --all
archyl session cancel <session-id>

finish 从参数或 ARCHYL_SESSION_ID 中获取会话 ID。--decision 中只放值得写成 ADR 的选择：每一条都会成为记忆，在之后涉及相同元素的会话中重新呈现。所有情境性的内容都放进 --follow-up。

检查与 CI

同样的命令可以在您的笔记本电脑上、git 钩子中以及任何 CI 中运行。在 CI 中，它们会从环境中获取基准分支、提交和报告格式：可识别 GitHub Actions、GitLab CI、Bitbucket Pipelines 和 Azure Pipelines。

check

archyl check 会对与基准分支存在差异的每个文件运行项目的合规规则，当某个违规达到 --fail-on 时以退出码 1 退出。

$ archyl check

CRITICAL Forbidden pattern found: fmt.Println (use slog)  No printing in services
   ╭─ internal/billing/invoice.go:42
 42 │ 	fmt.Println("total", total)
   ╰─ → Remove usage of the forbidden pattern: fmt.Println (use slog)

✗ 1 violation in 3 changed files · 1 critical

使用 --format auto 时，输出会随 CI 而变化：

--format sarif 会写出一份 SARIF 2.1.0 日志，供 GitHub code scanning、Azure DevOps 或任何安全仪表板使用。

CI 中的检出通常是浅克隆。请拉取完整历史，确保基准分支存在，否则 check 会停止并提示您。

# GitHub Actions
- uses: actions/checkout@v4
  with:
    fetch-depth: 0
- run: archyl check
  env:
    ARCHYL_API_KEY: ${{ secrets.ARCHYL_API_KEY }}

# GitLab CI
archyl:
  variables:
    GIT_DEPTH: 0
  script:
    - archyl check
  artifacts:
    reports:
      codequality: gl-code-quality-report.json

review

archyl review 是在打开拉取请求之前运行的一道检查。它汇总您的分支引入的规则违规、分支涉及的元素及依赖它们的内容、需要通知的人，以及当前的对齐度分数。当某个违规达到 --fail-on（默认 high）时以退出码 1 退出。

加上 --comment 时，评审结果会发布到拉取请求或合并请求上，并在之后每次 push 时原地更新，使该请求始终只有一条 Archyl 评论：判定结果、附带文件和行号的违规、涉及的元素及依赖它们的内容，以及需要知会的负责人。GitHub 需要具有 pull-requests: write 权限的 GITHUB_TOKEN；GitLab 需要具有 api 作用域的 GITLAB_TOKEN，因为 CI_JOB_TOKEN 无法发表评论。

评论中包含以 Mermaid 流程图呈现的影响范围，GitHub 和 GitLab 都会渲染它。archyl review --diagram 在本地输出同一张流程图，可以粘贴到描述或文档中。

在 GitHub 上最快的设置方式是使用 Archyl action，它会安装 CLI 并运行一条命令：

name: Architecture
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  archyl:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: archyl-com/cli@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          command: review --comment

将 command 留空，则只安装 CLI，供后续步骤调用。

hooks

archyl hooks install                   # blocks critical violations on git push
archyl hooks install --fail-on high
archyl hooks uninstall

archyl hooks install 会添加一个运行 archyl check --fail-open 的 git pre-push 钩子。带来等于或高于 --fail-on（默认 critical）级别违规的 push 会被拒绝；如果 PATH 中没有 archyl、处于离线状态或未登录，push 会照常通过。如需跳过一次，使用 git push --no-verify。该钩子遵循 core.hooksPath，并且除非传入 --force，否则绝不会替换不是由 archyl 写入的 pre-push 钩子。

drift

archyl drift 显示文档化的模型与代码的吻合程度：100 表示每个文档化的元素都在代码中找到了。--compute 会先重新分析已连接的仓库并等待结果；--fail-under 则把它变成一道质量门禁。

archyl drift --compute --fail-under 80

dsl

archyl dsl 让架构即代码文件与项目的模型保持同步。除非传入 --file，每个子命令都作用于仓库根目录下的 archyl.yaml。

archyl dsl pull                 # write the project's model to archyl.yaml
archyl dsl diff                 # what pushing the file would change
archyl dsl diff --exit-code     # in CI: fail when the file and the model differ
archyl dsl push                 # import the file into the project

• pull 导出模型（元素、关系、技术、决策、文档、契约、环境和发布）。覆盖文件前会先询问，除非传入 --yes；--file - 则改为直接输出。
• diff 在服务器上执行一次试运行，不写入任何内容：按 C4 层级分组列出推送会新增（+）或修改（~）的元素和关系，以及仅存在于 Archyl 中的内容（−）。--exit-code 在存在任何差异时以退出码 1 退出。
• push 创建新的元素和关系，并按名称匹配更新已有的内容。它从不删除：仅存在于 Archyl 中的内容会保留。在终端中，它会先显示差异并询问；--yes 跳过询问。

$ archyl dsl diff

▍ Containers
  + Refund Worker
  ~ Payments API
      description  "Card payments" → "Card and wallet payments"
  − Legacy Billing  only in Archyl, push keeps it

  archyl.yaml vs the model: 1 to add · 1 to change · 1 only in Archyl

archyl sync [file] 等同于 archyl dsl push。

release

archyl release 记录一次发布，用于将架构变更与实际交付的内容关联起来，并为 DORA 指标提供数据。版本默认取 CI 中正在构建的标签，其次取 HEAD 上的标签；链接默认指向 CI 运行。

archyl release v2.4.0 --environment production

radar

archyl radar 按治理环（采用、试验、评估、暂缓）展示组织的技术，以及每项技术在架构中的使用程度。archyl radar check 会读取仓库的依赖清单，将每个依赖与雷达匹配，若有依赖处于暂缓状态则以退出码 1 退出，CI 输出与 archyl check 相同。

$ archyl radar check

  HOLD    github.com/sirupsen/logrus 1.9.3  go.mod
          → Use log/slog from the standard library
  ASSESS  go.uber.org/zap 1.27.0  go.mod

✗ 1 dependency on hold · 4 dependencies in 1 manifest · 1 adopt · 0 trial · 1 assess · 1 hold · 1 unclassified

cr

archyl cr 列出项目的架构变更请求（通常由代理在工作会话结束时打开），让您无需离开终端即可评审。

archyl cr                                   # list
archyl cr show 12                           # the request and its changes
archyl cr approve 12
archyl cr request-changes 12 -m "Keep the ledger behind the Payments API"
archyl cr open 12                           # in the web app

账户与配置文件

一个配置文件对应一个拥有独立凭据的 Archyl 主机和组织。带上名称登录即可创建，这也是连接自托管 Archyl 的方式：

archyl login --host https://archyl.example.com --profile work
archyl profile use work

Shell 提示符

archyl prompt 用几个字符输出项目的对齐度分数和活跃代理，供您的 shell 提示符使用。它从不等待网络：它输出最后已知的状态，并每十分钟在后台刷新一次。使用 Starship 时：

[custom.archyl]
command = "archyl prompt"
when = "test -f .archyl.json"
format = "[$output]($style) "
style = "purple"

模型缓存 (model cache)

map、show、open、元素补全以及会话中的 # 建议都基于模型的本地副本作答，因此会立即启动。每个配置文件、主机、组织、身份和项目各有一份副本，存放在您的用户缓存目录中，仅您可读。生成不到 30 秒的副本会直接使用，不调用 API；更旧的副本会被刷新，而当 API 响应超过 1.5 秒时，命令会基于副本作答，并在 stderr 中说明。会修改模型的命令，例如 dsl push 或批准发现结果，会丢弃副本。

用 --no-cache 可让单条命令跳过缓存，用 ARCHYL_NO_CACHE=1 则在所有地方跳过。archyl login 和 archyl logout 会清除该配置文件的副本；archyl cache clear 可手动清除。

更新

有新版本发布时，CLI 会在命令结束后提示一次。该检查在后台运行，每天最多一次，在 CI 或脚本中从不运行；设置 ARCHYL_NO_UPDATE_NOTIFIER 可将其关闭。

archyl upgrade 按你安装 CLI 的方式更新它：Homebrew 用 brew upgrade，从源码构建用 go install 命令，其他情况则原地更新：下载适用于你平台的发布归档，用该版本的 checksums.txt 校验（cosign 在 PATH 中时还会校验其 cosign 签名），然后替换正在运行的二进制文件。--check 只报告是否有更新的版本发布。

archyl upgrade
archyl upgrade --check

全局参数

状态消息和加载动画输出到 stderr，结果输出到 stdout，因此管道只会接收到结果：

archyl where --json . | jq '.files[].elements[0].name'
archyl impact --json | jq '.impact.notify'

CI 与脚本

无需登录：在 Profile → API Keys 中创建一个 API 密钥，并将其设置到环境变量中。

export ARCHYL_API_KEY=arch_…
export ARCHYL_PROJECT_ID=…       # or commit .archyl.json
archyl impact --json | jq '.impact.notify'
archyl dsl diff --exit-code      # fails when archyl.yaml and the model differ

如果想把 API 密钥存储为凭据，请通过管道将它传给 archyl login --with-token。

Shell 自动补全

archyl completion install 把补全脚本写到 Shell 加载它的位置：你拥有的 zsh fpath 目录（或 ~/.zfunc）、~/.config/fish/completions 或 ~/.local/share/bash-completion/completions。再次运行会更新脚本。只有在必要时（zsh 没有属于你的 fpath 目录、PowerShell）且你同意的情况下，才会修改 Shell 的启动文件。archyl setup 也会提议安装。

archyl completion install
archyl completion install --shell fish

自己写入脚本：

archyl completion zsh > "${fpath[1]}/_archyl"
archyl completion bash > /etc/bash_completion.d/archyl
archyl completion fish > ~/.config/fish/completions/archyl.fish