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 키체인에 저장되고 스스로 갱신되므로, 한 달 동안 사용하지 않았을 때만 다시 로그인하면 됩니다.

**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**은 파일 내용을 아키텍처 브리핑과 함께 질문에 첨부합니다. 파일당 최대 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는 웹 앱에서 열고, 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는 웹 앱에서 엽니다. 파이프로 연결하거나 --json을 붙이면 archyl search invoice가 검색 결과를 출력합니다.

show

archyl show <element>는 요소를 경로, 설명, 기술, 관계, 연결된 결정, 영향 범위와 함께 출력합니다. archyl show ADR-12는 결정 기록을 렌더링합니다. 요소는 이름(정확히 일치, 그다음 부분 일치)이나 ID로 찾습니다.

open

archyl open은 프로젝트를 웹 앱에서 엽니다. archyl open "Payments"는 다이어그램에서 요소를 선택하고, archyl open ADR-12는 결정을 펼칩니다. 웹 앱의 주소는 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 디스커버리 할당량을 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는 프로젝트를 한 화면에 담습니다. 모델과 코드의 정렬도, 현재 브랜치, 그리고 지금 이 순간 프로젝트에서 작업 중인 에이전트입니다.

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는 사용자로 인증된 상태에서 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와 마찬가지로 터미널에서는 렌더링된 화면을 보여 주고, 에이전트가 자신의 셸에서 실행하면 간결한 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용 상태 표시줄입니다. 프로젝트, 그 정렬도 점수, 작업 중인 에이전트, 그리고 현재 세션이 하네스 아래에서 실행되는지 여부를 보여 줍니다. archyl setup이 설치하며, 직접 설정하려면 .claude/settings.json에 다음을 추가하세요:

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

runs

archyl runs는 프로젝트의 관리형 에이전트 실행 목록을 보여 주고, 사용자를 기다리는 실행에는 표시를 붙입니다. archyl runs view는 실행 하나를 실시간으로 따라갑니다. 피드에는 에이전트의 메시지, 도구 호출, 변경하는 파일이, 계획에는 각 단계의 진행 상황이, 옆에는 시간, 토큰, 비용이 표시됩니다. 그리고 터미널을 떠나지 않고 바로 조치할 수 있습니다:

같은 동작은 명령으로도 제공되므로 스크립트나 다른 에이전트를 감독하는 에이전트가 쓸 수 있습니다. 실행은 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. 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 로그에 경고를 한 번만 남기고 진단을 표시하지 않습니다. 진단은 키 입력이 아니라 저장을 따라갑니다.

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

같은 명령이 노트북에서도, 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 댓글이 하나만 남습니다. 판정, 파일과 줄 번호가 포함된 위반, 건드린 요소와 그것에 의존하는 것, 함께 알려야 할 담당자가 담깁니다. GitHub에는 pull-requests: write 권한이 있는 GITHUB_TOKEN이 필요하고, GitLab에는 api 범위의 GITLAB_TOKEN이 필요합니다. CI_JOB_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로 끝납니다.
• **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

셸 프롬프트

archyl prompt는 셸 프롬프트에 쓸 수 있도록 프로젝트의 정렬도 점수와 활성 에이전트를 몇 글자로 출력합니다. 네트워크를 기다리는 일은 없습니다. 마지막으로 알려진 상태를 출력하고 10분마다 백그라운드에서 갱신합니다. 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에 파이프로 전달하세요.

셸 자동 완성

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