amcli — 아키메이트 모델을 명령줄에서 다루기
아키메이트 모델 파일을 직접 읽고 편집하는 단일 바이너리입니다. GUI, JVM, 서버가 필요하지 않습니다.
절대 .archimate 파일을 Read나 cat으로 읽지 마세요. 수 메가바이트의 XML입니다. 모든 질문은 amcli 명령 하나로 해결되며, XML을 수동으로 편집하면 모델이 손상됩니다.
설정
가장 먼저 다음을 실행하세요:
amcli --version
버전이 출력되면 다음 섹션으로 넘어가세요. 출력되지 않으면:
sh가 실행되는 모든 환경 — macOS, Linux, WSL, Git Bash — 이 스킬과 함께 제공된 설치 스크립트를 사용하세요. 이 스크립트는 이 파일 옆에 위치하며, 일반적으로 ~/.agents/skills/amcli 또는 프로젝트 설치 시 ./.agents/skills/amcli에 있습니다:
AMCLI=$(sh ~/.agents/skills/amcli/scripts/install.sh)
표준 출력에 바이너리의 절대 경로를 출력하며 다른 내용은 출력하지 않습니다. 세션의 나머지 부분에서는 $AMCLI를 사용하세요. 새로 설치된 바이너리는 일반적으로 현재 셸의 PATH에 없으므로 amcli를 바로 입력하면 설치가 성공했음에도 "command not found"가 표시됩니다 — 이것이 가장 흔히 발생하는 문제입니다.
네이티브 Windows PowerShell에서는 sh가 없으므로 PowerShell용 스크립트를 사용하세요. 같은 규칙을 따릅니다:
$AMCLI = & ~\.agents\skills\amcli\scripts\install.ps1
어느 설치 스크립트도 아무것도 요구하지 않으며, 권한을 상승시키지 않으며, 셸 설정을 변경하지 않습니다. 플랫폼에 맞는 미리 빌드된 바이너리가 없으면 자체적으로 cargo를 사용해 빌드합니다. URL에서 파이프로 설치하지 마세요 — 이미 디스크에 있습니다.
모델 찾기
amcli는 자동으로 모델을 찾습니다: -m PATH, 또는 $AMCLI_MODEL, 또는 작업 디렉토리에서 상위로 올라가며 가장 가까운 *.archimate 파일을 찾습니다. 여러 개가 발견되면 종료 코드 4와 함께 목록을 출력하므로 -m으로 지정하세요.
기본 루프
모든 아키텍처 질문은 여기서 시작하세요. 먼저 소스 코드를 열지 마세요.
amcli stats # 모델의 크기와 구성은?
amcli search <term> # 개념을 찾아 ID를 얻음
amcli get <id-or-name> # 개념의 정체와 연결된 모든 것
amcli trace <id-or-name> -n 2 # 주변 개념 탐색
# 이제서야 소스 코드를 읽되, 모델이 가리킨 파일만 읽으세요
플래그는 각각 하나의 의미만 가집니다
-t 개념 타입 -r 관계 타입 -f 폴더 -D 방향(out|in|both)
-n 깊이 -l 제한 개수 -m 모델 -F 형식 -o 출력 파일
주제는 위치 인자로, 플래그가 아닙니다:
amcli element add ApplicationComponent "Refund Service" -f /Application
amcli relation add Serving "Refund Service" "Checkout Service"
출력과 토큰 경제
기본 출력은 한 줄에 하나의 탭으로 구분된 레코드입니다 — 읽기에 부담이 없고 cut -f2로 쉽게 처리할 수 있습니다. 개수와 힌트는 stderr로 출력됩니다. 중첩 구조(예: get 내부의 관계 ID)가 필요할 때만 -F json을 추가하세요.
amcli query 'layer=Application' --count # 먼저 "몇 개인지" 물어보세요, 항상
amcli search auth -l 10 --fields id,name # 필드 제한
amcli list --fields -documentation # 또는 필드 제외
익숙하지 않은 모델에서 필터 없는 list를 절대 실행하지 마세요. 먼저 amcli stats를 실행하세요.
개념 지정
id:5dde26f7 ID — 항상 명확하며, 항상 우선 사용
"Payment API" 정확한 이름
ApplicationComponent:"Payment" 타입으로 한정된 이름
"*Payment*" 글롭(glob)
필터 표현식은 하나의 인자로 따옴표로 묶습니다:
amcli query 'type=ApplicationComponent and name~payment'
amcli query 'prop:owner=team-a and not folder^=/Technology'
amcli query 'layer=Application and deg>10'
amcli query 'out:Access~Customer' # Customer와 일치하는 것에 접근하는 모든 것
연산자: = 정확히 일치 · ~ 포함 · ^= 접두사 · =~ 정규식 · != · > <
deg에 사용. 필드: id name type layer folder doc deg view prop:KEY in:관계타입 out:관계타입.
종료 코드 — 메시지를 파싱하지 말고 이 값으로 분기하세요
0 성공 2 사용법 오류 3 찾을 수 없음 4 모호함 5 잘못된 입력 6 충돌
7 입출력 오류 8 지원되지 않음
3의 경우 응답에 가장 가까운 이름들이 나열됩니다 — 그중 하나로 다시 시도하고, 다른 검색을 실행하지 마세요. 4의 경우 후보 목록과 각각에 붙여넣기 가능한 id: 선택자가 함께 출력됩니다. 모호함을 추측으로 해결하지 말고 ID로 다시 실행하세요.
그래프 질문
amcli path "Web App" "Customer Database" # 이 둘은 어떻게 연결되어 있나?
amcli impact id:5dde26f7 -D in # 이게 변경되면 무엇이 깨지나?
amcli neighbors id:5dde26f7 -r Serving # Serving 관계만 표시
amcli descendants "Payments Capability" # 구성 트리
amcli cycles # 의존성 사이클
편집
amcli element add ApplicationComponent "Refund Service" --doc "…"
amcli element rename id:c40a19b7 "Refunds Service"
amcli relation add Access "Refunds Service" "Refund Record" --access rw
amcli prop set id:c40a19b7 owner team-payments
amcli element delete id:c40a19b7 -y
모든 쓰기 작업은 먼저 아키메이트 관계 매트릭스에 대해 검사되며, 표준에서 금지하는 경우 거부(종료 코드 5)됩니다 — 그리고 거부 메시지는 해당 두 타입 간에 허용되는 관계를 알려주므로, 다시 추측하지 말고 읽으세요.
삭제는 기본적으로 다른 요소를 함께 삭제할 때 거부하며, 거부 메시지는 영향 보고서입니다. 읽은 후 -y를 추가하세요.
확실하지 않을 때는 --dry-run을 사용하세요. 이전 턴에 모델을 읽었고 지금 쓰는 경우 --expect-checksum을 사용하세요:
CS=$(amcli info -F json -q | jq -r '.[0].checksum')
amcli element rename id:x "New" --expect-checksum "$CS" # 변경되었으면 종료 코드 6
두 번 이상의 편집은 순차적인 명령 대신 하나의 원자적 배치를 사용하세요.
amcli apply - <<'EOF'
{"op":"element.add","type":"ApplicationComponent","name":"Refund Service","ref":"r","if_absent":true}
{"op":"element.add","type":"DataObject","name":"Refund Record","ref":"rec","if_absent":true}
{"op":"relation.add","type":"Access","source":"ref:r","target":"ref:rec","access":"rw","if_absent":true}
EOF
ref는 한 줄의 결과에 이름을 붙여 이후 줄에서 ID가 존재하기 전에 참조할 수 있게 합니다. if_absent는 배치를 재실행해도 안전하게 만듭니다. 어떤 줄이 실패하면 아무것도 쓰이지 않으며 파일은 바이트 단위로 동일합니다.
편집을 마치기 전에
amcli validate
종료 코드 5는 모델에 오류가 있음을 의미합니다. 각 오류는 파일 내 줄 번호와 fix 명령을 함께 제공합니다. amcli validate --fix는 유도 가능한 수리(고아가 된 다이어그램 객체와 오래된 뷰 미러)만 적용하며, 누군가의 모델링을 삭제하지 않습니다.
뷰와 다이어그램
amcli view list
amcli view auto "Refund Flow" --from "Refund Service" -n 2 --layout layered
amcli view render "Refund Flow" -o refund.svg
amcli export mermaid # 채팅용 빠른 인라인 다이어그램
view render는 모델이 실제로 저장하는 도형을 그립니다. export mermaid와 export dot는 레이아웃을 다시 계산하므로, 빠른 확인용이지 누군가의 다이어그램을 재현하기 위한 것이 아닙니다.
더 깊이 들어가기
| 상황 | 사용할 명령어 |
|---|---|
| 위에 없는 하위 명령어나 플래그가 필요할 때 | amcli skill commands — 현재 실행 중인 바이너리에서 전체 트리를 출력하므로 항상 최신 상태입니다 |
| 특정 명령어의 플래그 세부 정보가 필요할 때 | amcli <명령어> --help |
| 정확한 아키메이트 3.2 타입 이름 또는 두 타입 간 합법적인 관계가 필요할 때 | references/types.md |
| 약 10개 이상의 작업을 배치로 작성할 때 | references/batch.md |