@adrkit/cli (英语)

Git-native架构决策记录从adrkit工具.

安装和运行

使用零安装运行的包名 。 出版的二进制是 adr,但是一个 赤线 npx adr 解决不相关的 npm 软件包 :

npx @adrkit/cli lint

对于项目使用,添加为dev依赖,并通过脚本引用:

npm install --save-dev @adrkit/cli    # or: bun add --dev @adrkit/cli
npm pkg set scripts.adr=adr
npm run adr -- lint

让你在安装的本地二进制上 而不是什么 npx adr 可能会 从登记册下载.

也可以在全球安装:

npm install -g @adrkit/cli
adr lint

每个安装也提供 adrkit,用于同一二进制的同名化名. 偏爱 adrkit 在CI、Makefiles和代理指令中,因为其名称 明确无误:

adrkit lint

执行 没有 使用情况 npx adrkit 或者说 bunx adrkit。没有未扫描 adrkit ,因此,这些表格将解决与登记册而不是与登记册相抵触的问题 已出版 @adrkit/cli 软件包.

人可读的 CLI 输出为 TTY- 意识:当重定向或重定向时, 它保持 ANSI 无 烟斗,荣誉 NO_COLOR,可以强制使用 --color auto|always|never。 。 。 .

图标

二进制包括:

• new
• lint
• graph
• explain
• check
• queue
• approve
• object
• resolve
• accept
• migrate --from madr
• completion
• evaluate

运行 adr --help 为命令列表, adr help <command> 一个命令的 旗帜,以及 adr --version 以打印已安装的版本.

审查队列和接受

adr queue 列表中 proposed 记录其苏丹解放军状态,最后期限, 批准和反对。 在终端中,它打印一个列表 大小到窗口, ,每个项目以下一个步骤结束:接受的命令,或者原因 尚无法接受。 管道、重定向或捕获输出为 确定性标记报告,不变; --format json 发射 QueueReport 页:1 --format terminal|markdown 明确选择.

adr queue
adr accept 0044 --by @octocat

adr accept 套装 status: accepted, (中文(简体) ), provenance.ratifiedBy,以及 review.decidedAt (现在,UTC,有秒),并且没有改变其他行. 这个 什么都不会犯 它拒绝,并留下 档案未动,当记录是 没有 proposed,有未解决的反对意见,其核准数少于其 review.quorum,或者不会成为有效的公认记录. --by 需要,并且 从未被推断。 退出代码 : 0 已接受, 1 拒绝, 2 使用错误.

记录审查:批准、反对、解决

adr approve 0044 --by @octocat
adr object 0044 --by @hubot --summary "Needs a load test first"
adr resolve 0044 --objection 1 --by @hubot

adr approve 添加 --by 改为 review.approvals。 。 。 . adr object 附录 { by, summary, resolved: false } 改为 review.objections;摘要为一 最多500个字符的行. adr resolve 套装 resolved: true 打开 反对 n (按文件顺序从 1 计算),只有反对者可以 解决它。 每一行为只针对 proposed 记录,没有改变其他行, 不犯任何罪过,而不犯任何罪过, (b) 同一公开反对意见两次,解决已解决的反对意见). --by 实值 需要而且从未被推断,身份 比较不敏感的情况,所以 @Bob 之后 @bob 同一批准,法定人数是不同的人。 退出代码匹配 adr accept数字 : 0 书面或 不变, 1 拒绝, 2 使用错误; --json 所有三个都有. adr queue同意和反对都跟着写 (单位:千美元)ADR-0051 (英语)页:1.

决定图

adr graph 在 stdout 边界选择默认值:交互式终端 获得紧凑状态和关系视图,而管道、方向调整或抓取 子进程继续接收决定性的 Graphviz DOT 。 刻录频道 另一个工具会消耗输出 :

adr graph                                  # terminal view on a TTY; DOT in a pipe
adr graph --focus 0014                     # one ADR and its direct neighborhood
adr graph --kind supersedes                # one relationship kind
adr graph --format mermaid > decisions.mmd
adr graph --format dot | dot -Tsvg > decisions.svg
adr graph --format json > decisions.json

--kind 可重复并接受 supersedes, (中文(简体) ), relatesTo,以及 conflictsWith明确 --format terminal|dot|json|mermaid 总是覆盖 TTY选择. DOT,美人鱼,和JSON 仍然没有ANSI,即使强迫的颜色. 大型零星和有重点的终端视图被限制;使用另一个 --kind 或一个 用于完整边缘集的机器格式.

如果一个或数个实体记录无效, 图表仍然显示完整 将每个有效记录投影,将错误结果写入 stderr,以及 输出 1退出时 0 表示没有错误; 退出 2 现为a 使用或无法获取指令错误.

贝壳完成

adr completion <bash|zsh|fish> 打印决定性的完成脚本到 s. 生成的脚本同时注册 adr 财务报告和审定财务报表 adrkit 贝壳在哪里 格式许可.

adr completion bash > ~/.local/share/bash-completion/completions/adr
cp ~/.local/share/bash-completion/completions/adr ~/.local/share/bash-completion/completions/adrkit
adr completion zsh > ~/.zsh/completions/_adr
cp ~/.zsh/completions/_adr ~/.zsh/completions/_adrkit
adr completion fish > ~/.config/fish/completions/adr.fish
cp ~/.config/fish/completions/adr.fish ~/.config/fish/completions/adrkit.fish

如果您更喜欢连锁,请将两个鱼入点指向同一个生成的文件:

ln -sf ~/.config/fish/completions/adr.fish ~/.config/fish/completions/adrkit.fish

入境 @adr 标记

adr explain <path> 财务报告和审定财务报表 adr check <files...> a. 两项决定的解决 前进方向 记录中声明它所管理的路径 affects; 来源 文件可以使用注释标记声明它所居住的决定 :

// @adr 0012
export function syncOnce() { /* ... */ }

$ adr explain src/services/sync/retry.ts
Decisions governing src/services/sync/retry.ts:
  0009  [accepted] Resolve affects deterministically
    via path: src/services/sync/**
  0012  [accepted] Bind catalog entities to owned paths
    declared by src/services/sync/retry.ts:1 (@adr 0012)

标记扫描有意缩小:

• 只有第一个 8192 字节 将文件考虑
• 扫描停止在该窗口内最后一行
• 最多为第一次 每个档案64份申报 保留
• 标记必须是专用评论行的第一个内容
• 栅栏码块内的行被忽略
• 标记下的文件( r).md, (中文(简体) ), .mdx, (中文(简体) ), .markdown)仅接受 <!-- 财务报告和审定财务报表 {/*

没有东西被写回记录.

被替换、拒绝或贬值的记录名称的标记仍然可以解决 向历史记录提供咨询意见 stale-marker 警告 警告他们 对a 替换链条,警告在可以时将终端的活继者命名 已经解决了 绝对不会沉默地取代它 警告不影响 退出代码.

下 --as-of,该日期生效的记录的标记不是 僵化——当时是准确的申报. 现在的警告是 不变.

时间旅行: adr explain --as-of

adr explain <path> --as-of <date|ref> 解答决定支配路径 过去的日期。 每张唱片都有 date,并使用替换的记录名称 后继器,所以一个有效时间窗口可以不修改方案而产生: 它打开 记录本身 date 并关闭它的近代.

$ adr explain src/auth/session.ts --as-of 2026-03-01
As of 2026-03-01
Note: matchers and @adr markers are read from today’s corpus and working tree; only standing is re-dated.
Decisions governing src/auth/session.ts as of 2026-03-01:
  0007  [superseded] Use JWT sessions (superseded by 0019)
    in force 2026-01-15 → 2026-06-01 (closed by 0019)
    via path: src/auth/**
Not yet recorded as of 2026-03-01:
  0019  [accepted] Use opaque server sessions
    recorded 2026-06-01

括号内是记录的状态 现在; 窗口下方为 怎么会这样? 两者都是真的,读者都需要两者兼有。 标题下的说明 因为证据线via path:, (中文(简体) ), declared by …读取自 今天的案卷和档案是一回事 --as-of 没有 重新约会.

• 该值为日期第一,为git ref第二. YYYY-MM-DD 或 ISO 标准 有明确时区的日期时间读作日期;任何其他问题都解决 与 git rev-parse --verify <ref>^{commit} 当前目录中的日期 承诺 罪犯 约会。 名为标签 2026-03-01 因此改为: 日期,而不是那个标签.
• 视窗半开. 接班人有自己的起步日,所以正好一个 超会话链式记录在任何特定日期生效.
• deprecated 报告为 undetermined,没有猜测. 计划 允许 supersededBy 仅在 superseded,所以一个贬值的记录没有 日期 它停止统治。 诚实的回答是这样的: rejected 记录 每一天都是历史,因为它对无生效.
• --as-of 重新约会 永远不要工作树. 达到的决定 路径仍然从今天的记录和今天的文件内容读取。 阅读 过去裁判时的文件内容是更大的合同,没有尝试.
• 这是添加剂. 没有旗帜,产出不变. 带着它, --json 收益a asOf 块和当前值 governing, (中文(简体) ), activeProposals,以及 history 密钥保持其意义 (单位:千美元)ADR-0039 (英语)) (中文(简体) ).

单位 --json,模式匹配显示在 firedMatchers 并提交声明 declaredBy。 。 。 . explain --json 包括单个文件 markers 块加 scannedBytes, (中文(简体) ), fileBytes,准确保留/允许的申报数. check --json 包含a markerScan 报告与状态计数; 准确 无法使用、截断和跳过路径; 并汇总申报数 .

多文件扫描封顶于 3 000道正常化 与 16个同时存在 读取,最多保留第一个 10 000份申报 在代码单位路径中 然后是源指令。 跳过路径并声明每次崩溃都会溢出到一个 有限度的警告;它们和标记要求都不能改变退出代码.

见 命令参考。 。 。 .

公布的无害环境管理CLI在22号节点或较新的节点上运行;开发在Arkit 仓库使用 Bun.

另见 @adrkit/mcp,本地只读模式上下文 协议服务器将同一实体暴露于编码代理.

联合国 https://adrkit.dev (中文(简体) )

许可证: Apache-2.0