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 でサインインします。セッションは OS のキーチェーンに保存されて自動的に更新されるため、再サインインが必要になるのは 1 か月使わなかった場合だけです。

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。名前、スラッグ、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 はファイルの内容を、そのアーキテクチャのブリーフィングとともに質問に添付します。1 ファイルあたり最大 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 は、プロジェクトで起きていることを 1 つのフィードにまとめます。作成・変更された要素（変更されたフィールド付き）、オープン・マージされた変更リクエスト、キューに入った・誰かの対応を待っている・完了したエージェントの実行、開始・終了した作業セッションが対象です。--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 に表示しながら追跡します。見つかったものはすぐにはモデルに加わらず、レビューを待ちます。ターミナルではディスカバリーの終了時にレビューが自動で開きます。紐づいたリポジトリ 1 つにつき、プランの AI ディスカバリー枠を 1 回分消費します。

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 はプロジェクトを 1 画面にまとめます。モデルとコードの整合度、現在のブランチ、そして今まさにプロジェクトで作業しているエージェントです。

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 はシェル補完のインストールも提案します。--no-completion で省略できます。

既存のファイルは上書きされず、マージされます。

デフォルト（--transport cli）では、各エージェントが archyl mcp を起動し、CLI 自身のセッションで Archyl の MCP サーバーに接続します。archyl login で一度サインインすれば、すべてのエージェントが接続されます。エージェントごとの OAuth フローも、ファイル内のキーも必要ありません。--transport http の場合、設定に含まれるのはサーバーの URL だけで、各エージェントは Archyl 自体を通じてサインインします。どちらの場合も、リポジトリ内のファイルにシークレットは含まれず、安全にコミットできます。

mcp

archyl mcp は、あなたとして認証された状態で、Archyl の MCP ツールを stdio 経由でエージェントに提供します。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 と同様に、ターミナルではリッチに表示され、エージェントがシェルから実行したときはコンパクトな 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 は、プロジェクトで作業中のエージェントをライブで表示します。どのエージェントが、どのタスクで、どの要素に対して、どのファイルを変更したかが分かります。複数のエージェントにリースされている要素にはフラグが付くので、2 つのエージェントが同じコードで衝突することはありません。a を押すと、最近終了したセッションも含めて表示します。パイプ経由または --json 付きでは、セッションを一度だけ出力します。

statusline

archyl statusline は Claude Code 用のステータスラインです。プロジェクト、その整合度スコア、作業中のエージェント、現在のセッションがハーネスの下で実行されているかどうかを表示します。archyl setup がインストールしますが、手動で設定する場合は .claude/settings.json に次のように書きます:

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

runs

archyl runs はプロジェクトのマネージドエージェント実行を一覧表示し、あなたの対応を待っている実行にフラグを付けます。archyl runs view は 1 つの実行をライブで追跡します。フィードにはエージェントのメッセージ、ツール呼び出し、変更するファイルが、計画には各ステップの進捗が、横には経過時間、トークン、コストが表示されます。そしてターミナルを離れずに操作できます:

同じ操作はコマンドとしても用意されており、スクリプトや、エージェントを監督するエージェントから使えます。実行は 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 が関連する要素、意思決定、ルールを選び、2 つのエージェントが衝突しないようにそれらの要素をリースし、ゲート判定付きのブリーフィングを返します。
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 は、ブランチのルール違反の修正をハーネスの下でコーディングエージェントに任せます:

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 ログに警告を 1 回だけ書き込み、診断は表示しません。診断はキー入力ではなく保存に追従します。

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 の違反は警告します。high の違反もブロックするには ARCHYL_GUARD_BLOCK を 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 はセッション ID を引数として、または ARCHYL_SESSION_ID から受け取ります。--decision には ADR に値する選択だけを入れてください。それぞれがメモリとなり、同じ要素に対する将来のセッションで再提示されます。状況に依存する内容はすべて --follow-up に入れます。

チェックと CI

同じコマンドが、手元のノート PC でも、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 は、GitHub の code scanning、Azure DevOps、または任意のセキュリティダッシュボード向けに SARIF 2.1.0 のログを書き出します。

CI のチェックアウトは shallow であることがよくあります。ベースブランチが存在するように履歴を取得してください。そうしないと 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 のコメントは常に 1 つだけです。内容は判定、ファイルと行付きの違反、触れた要素とそれに依存するもの、巻き込むべきオーナーです。GitHub では pull-requests: write 権限を持つ GITHUB_TOKEN が必要です。GitLab では CI_JOB_TOKEN ではコメントできないため、api スコープを持つ GITLAB_TOKEN が必要です。

コメントには影響範囲が Mermaid のフローチャートとして含まれ、GitHub と GitLab で描画されます。archyl review --diagram は同じフローチャートをローカルに出力するので、説明文やドキュメントに貼り付けられます。

GitHub で最も手早く設定するには、CLI をインストールしてコマンドを実行する Archyl アクションを使います:

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

CLI をインストールするだけで、後続のステップで呼び出したい場合は command を空のままにしてください。

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 は拒否されます。archyl が PATH にない場合、オフラインの場合、サインアウトしている場合は push がそのまま通ります。一度だけスキップするには git push --no-verify を使います。フックは core.hooksPath に従い、archyl が書いたものではない pre-push フックは、--force を渡さない限り置き換えられません。

drift

archyl drift は、ドキュメント化されたモデルがコードとどれだけ一致しているかを示します。100 は、ドキュメント化されたすべての要素がコード内で見つかったことを意味します。--compute は接続されたリポジトリを先に再解析し、結果を待ちます。--fail-under を付けると品質ゲートになります。

archyl drift --compute --fail-under 80

dsl

archyl dsl は、architecture-as-code ファイルとプロジェクトのモデルを同期させます。--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 はサーバー上でのドライランで、何も書き込みません。push によって追加される（+）または変更される（~）要素とリレーションシップを C4 レベルごとにまとめ、Archyl にしかないもの（−）も示します。--exit-code を付けると、差分が 1 つでもあれば終了コード 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

アカウントとプロファイル

プロファイルとは、独自の認証情報を持つ 1 つの Archyl ホストと組織の組み合わせです。名前を付けてサインインすると作成でき、これはセルフホストの Archyl に接続する方法でもあります:

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

シェルプロンプト

archyl prompt は、プロジェクトの整合度スコアとアクティブなエージェントを、シェルプロンプト用に数文字で出力します。ネットワークを待つことはありません。最後に分かっている状態を出力し、10 分ごとにバックグラウンドで更新します。Starship の場合:

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

モデルキャッシュ (model cache)

map、show、open、要素の補完、セッションの # 候補は、モデルのローカルコピーから応答するため、すぐに起動します。コピーはプロファイル、ホスト、組織、アイデンティティ、プロジェクトごとに 1 つずつ、ユーザーのキャッシュディレクトリに置かれ、本人だけが読み取れます。作成から 30 秒未満のコピーは API を呼ばずに使われます。それより古いコピーは更新され、API の応答に 1.5 秒以上かかる場合はコピーから応答し、その旨を stderr に表示します。dsl push やディスカバリーの承認など、モデルを変更するコマンドはコピーを破棄します。

1 つのコマンドだけキャッシュを使わないなら --no-cache を、常に使わないなら ARCHYL_NO_CACHE=1 を指定します。archyl login と archyl logout はそのプロファイルのコピーを消去します。手動で消去するには archyl cache clear を使います。

アップデート

新しいリリースが出ていると、CLI はコマンドの終了後に一度だけそれを知らせます。チェックはバックグラウンドで 1 日に最大 1 回実行され、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 にパイプで渡します。

シェル補完

archyl completion install は、シェルが読み込む場所に補完スクリプトを書き込みます: 自分が所有する zsh の fpath 内のディレクトリ（または ~/.zfunc）、~/.config/fish/completions、~/.local/share/bash-completion/completions。もう一度実行するとスクリプトを更新します。シェルの起動ファイルを変更するのは、必要な場合（自分の fpath ディレクトリがない zsh、PowerShell）に同意したときだけです。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