amcli – ArchiMate-Modelle von der Kommandozeile
Ein einzelnes Binary, das ArchiMate-Modelldateien direkt liest und bearbeitet. Keine GUI, keine JVM, kein Server.
Lesen Sie eine .archimate-Datei niemals mit Read oder cat. Diese werden Megabytes an
XML groß. Jede Frage, die Sie haben, ist ein einziger amcli-Befehl, und das manuelle Bearbeiten
dieser XML-Datei korrumpiert Modelle.
Einrichtung
Führen Sie vor allem anderen dies aus:
amcli --version
Wenn eine Versionsnummer ausgegeben wird, fahren Sie mit dem nächsten Abschnitt fort. Wenn nicht:
Wo immer sh läuft – macOS, Linux, WSL, Git Bash – verwenden Sie das Installationsprogramm,
das mit diesem Skill ausgeliefert wurde. Es befindet sich neben dieser Datei, normalerweise in
~/.agents/skills/amcli oder ./.agents/skills/amcli für eine Projektinstallation:
AMCLI=$(sh ~/.agents/skills/amcli/scripts/install.sh)
Es gibt den absoluten Pfad des Binarys auf stdout aus und sonst nichts. Verwenden Sie
$AMCLI für den Rest der Sitzung. Ein neu installiertes Binary befindet sich normalerweise
noch nicht im aktuellen PATH der Shell, daher wird ein einfacher amcli-Aufruf immer noch
„Befehl nicht gefunden“ melden, obwohl die Installation erfolgreich war – das ist die häufigste
Fehlerquelle.
Natives Windows PowerShell, wo es kein sh gibt, verwenden Sie stattdessen das PowerShell-Skript.
Es folgt dem gleichen Vertrag:
$AMCLI = & ~\.agents\skills\amcli\scripts\install.ps1
Beide Installationsprogramme fragen nach nichts, benötigen nie Administratorrechte und bearbeiten nie eine Shell-Konfiguration. Wenn kein vorkompiliertes Binary für die Plattform existiert, wird es mit cargo selbst gebaut. Leiten Sie keines von einer URL um – sie sind bereits auf der Festplatte.
Das Modell finden
amcli findet das Modell selbstständig: -m PFAD, sonst $AMCLI_MODEL, sonst die
nächstgelegene *.archimate-Datei, die vom Arbeitsverzeichnis aus aufwärts gesucht wird. Wenn
mehrere gefunden werden, wird mit Exit-Code 4 beendet und diese aufgelistet – verwenden Sie -m.
Die Schleife
Beginnen Sie jede Architekturfrage hier. Öffnen Sie nicht zuerst den Quellcode.
amcli stats # Wie groß ist das Ding und aus was besteht es?
amcli search <begriff> # Finden Sie das Konzept, erhalten Sie seine ID
amcli get <id-oder-name> # Was es ist und alles, was es berührt
amcli trace <id-oder-name> -n 2 # Die Nachbarschaft
# Erst jetzt Quellcode lesen, und nur die Dateien, auf die das Modell verweist
Flags bedeuten jeweils eine Sache
-t Konzepttyp -r Beziehungstyp -f Ordner -D Richtung(out|in|both)
-n Tiefe -l Limit -m Modell -F Format -o Ausgabedatei
Subjekte sind Positionsargumente, niemals Flags:
amcli element add ApplicationComponent "Refund Service" -f /Application
amcli relation add Serving "Refund Service" "Checkout Service"
Ausgabe und Token-Effizienz
Die Standardausgabe sind tabulatorgetrennte Datensätze, eine pro Zeile – günstig zu lesen und
einfach mit cut -f2 zu parsen. Zählungen und Hinweise gehen nach stderr. Fügen Sie -F json
nur hinzu, wenn Sie eine verschachtelte Struktur benötigen, z. B. die Beziehungs-IDs innerhalb
von get.
amcli query 'layer=Application' --count # Fragen Sie ZUERST immer „wie viele?“
amcli search auth -l 10 --fields id,name # Projektion nach unten
amcli list --fields -documentation # Oder ein Feld weglassen
Führen Sie niemals eine ungefilterte list auf einem unbekannten Modell aus. Führen Sie zuerst
amcli stats aus.
Konzepte adressieren
id:5dde26f7 Eine ID – immer eindeutig, immer bevorzugen
"Payment API" Ein exakter Name
ApplicationComponent:"Payment" Ein durch Typ qualifizierter Name
"*Payment*" Ein Globus
Filterausdrücke, als ein Argument in Anführungszeichen:
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' # Alles, was auf etwas mit Customer zugreift
Operatoren: = exakt · ~ enthält · ^= Präfix · =~ Regex · != · > <
auf deg. Felder: id name type layer folder doc deg view prop:KEY in:RelType out:RelType.
Exit-Codes – Verzweigen Sie darauf, parsen Sie keine Meldungen
0 ok 2 verwendung 3 nicht gefunden 4 mehrdeutig 5 ungültig 6 konflikt
7 io 8 nicht unterstützt
Bei 3 listet die Antwort die nächstgelegenen Namen auf – wiederholen Sie den Vorgang mit einem
dieser Namen, führen Sie keine weitere Suche durch. Bei 4 listet sie Kandidaten auf, jeder mit
einem bereit zum Einfügen id:-Selektor. Arbeiten Sie niemals eine Mehrdeutigkeit durch Raten
weg; führen Sie den Vorgang mit der ID erneut aus.
Graph-Fragen
amcli path "Web App" "Customer Database" # Wie sind diese verbunden?
amcli impact id:5dde26f7 -D in # Was passiert, wenn sich dies ändert?
amcli neighbors id:5dde26f7 -r Serving # Nur Serving-Beziehungen
amcli descendants "Payments Capability" # Der Kompositionsbaum
amcli cycles # Abhängigkeitszyklen
Bearbeiten
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
Jeder Schreibvorgang wird zuerst gegen die ArchiMate-Beziehungsmatrix geprüft und abgelehnt (Exit 5), wenn der Standard dies verbietet – und die Ablehnung nennt, was erlaubt ist zwischen diesen beiden Typen, also lesen Sie sie, anstatt erneut zu raten.
Löschen wird standardmäßig abgelehnt, wenn dabei andere Dinge mitgenommen würden, und die
Ablehnung ist der Auswirkungsbericht. Fügen Sie -y hinzu, sobald Sie ihn gelesen haben.
Verwenden Sie --dry-run, wenn Sie unsicher sind. Verwenden Sie --expect-checksum, wenn Sie
das Modell bei einem früheren Durchlauf gelesen haben und jetzt schreiben:
CS=$(amcli info -F json -q | jq -r '.[0].checksum')
amcli element rename id:x "New" --expect-checksum "$CS" # Exit 6, wenn es sich geändert hat
Verwenden Sie für mehr als zwei Änderungen einen atomaren Batch anstelle einer Sequenz.
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 benennt das Ergebnis einer Zeile, sodass eine spätere Zeile darauf verweisen kann, bevor
dessen ID existiert. if_absent macht den Batch sicher für die wiederholte Ausführung. Wenn
irgendeine Zeile fehlschlägt, wird nichts geschrieben und die Datei ist byte-identisch.
Bevor Sie eine Bearbeitung abschließen
amcli validate
Exit 5 bedeutet, dass das Modell Fehler enthält. Jeder Befund nennt eine Zeile in der Datei und
enthält einen fix-Befehl. amcli validate --fix wendet nur die Reparaturen an, die abgeleitet
statt gewählt sind – verwaiste Diagrammobjekte und veraltete View-Spiegel – und löscht niemals
jemandes Modellierung.
Ansichten und Diagramme
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 # Ein kurzes Inline-Diagramm für den Chat
view render zeichnet die Geometrie, die das Modell tatsächlich speichert. export mermaid
und export dot layouten neu, daher sind sie für einen schnellen Blick gedacht, nicht zum
Reproduzieren eines fremden Diagramms.
Tiefergehend
| Wohin | Wann |
|---|---|
amcli skill commands | Sie benötigen einen Unterbefehl oder ein Flag, das oben nicht gezeigt wird – es gibt den gesamten Baum aus, aus dem Binary, das Sie tatsächlich ausführen, ist also nie veraltet |
amcli <befehl> --help | Sie benötigen die Flags eines Befehls im Detail |
references/types.md | Sie benötigen einen exakten ArchiMate 3.2-Typnamen oder wissen, welche Beziehungen zwischen zwei Typen zulässig sind |
references/batch.md | Sie schreiben einen Batch mit mehr als etwa zehn Operationen |