amcli — コマンドラインでArchiMateモデルを操作 は何をしますか？
ArchiMateモデルファイルを直接読み取り・編集する単一バイナリです。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 パス、次に $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"
出力とトークン節約
デフォルトの出力はタブ区切りレコードで、1行に1レコード — 読むのに安価で cut -f2 で簡単に処理できます。カウントやヒントは標準エラー出力に出力されます。ネストされた構造（例：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*" グロブ
フィルター式は、1つの引数として引用符で囲みます：
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:RelType out:RelType。
終了コード — これらで分岐し、メッセージをパースしない
0 ok 2 使い方エラー 3 見つからない 4 曖昧 5 無効 6 競合
7 io 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
すべての書き込みは最初にArchiMateリレーションシップ行列でチェックされ、標準で禁止されている場合は拒否（終了コード5）されます — そして拒否メッセージはその2つのタイプ間で許可されているものを示すので、推測せずにそれを読んでください。
削除は、他のものを巻き込む場合、デフォルトで拒否され、その拒否が影響レポートとなります。それを読んだら -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
2つ以上の編集を行う場合は、逐次ではなく1つのアトミックなバッチとして実行してください。
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 |
| 正確なArchiMate 3.2タイプ名、または2つのタイプ間で許可されているリレーションシップが必要な場合 | references/types.md |
| 10操作程度以上のバッチを書いている場合 | references/batch.md |