amcli — Les modèles ArchiMate en ligne de commande
Un binaire unique qui lit et édite directement les fichiers de modèles ArchiMate. Pas d'interface graphique, pas de JVM, pas de serveur.
Ne lisez ou n'utilisez jamais cat sur un fichier .archimate. Ils atteignent des mégaoctets de XML. Chaque question que vous vous posez est résolue par une commande amcli, et éditer ce XML à la main corrompt les modèles.
Installation
Exécutez ceci avant toute chose :
amcli --version
Si une version s'affiche, passez à la section suivante. Sinon :
Partout où sh est disponible — macOS, Linux, WSL, Git Bash — utilisez le programme d'installation fourni avec cette compétence. Il se trouve à côté de ce fichier, normalement dans ~/.agents/skills/amcli, ou ./.agents/skills/amcli pour une installation de projet :
AMCLI=$(sh ~/.agents/skills/amcli/scripts/install.sh)
Il affiche le chemin absolu du binaire sur stdout et rien d'autre. Utilisez $AMCLI pour le reste de la session. Un binaire fraîchement installé n'est généralement pas encore dans le PATH du shell courant, donc un simple amcli signalera toujours « commande introuvable » même si l'installation a réussi — c'est la façon la plus courante que cela échoue.
PowerShell natif Windows, où sh n'existe pas, utilisez plutôt le script PowerShell. Il respecte le même contrat :
$AMCLI = & ~\.agents\skills\amcli\scripts\install.ps1
Les deux programmes d'installation ne demandent rien, ne s'élèvent jamais en privilèges et ne modifient jamais la configuration du shell. Si aucun binaire précompilé ne correspond à la plateforme, ils le compilent eux-mêmes avec cargo. Ne les téléchargez pas depuis une URL — ils sont déjà sur le disque.
Trouver le modèle
amcli trouve le modèle tout seul : -m CHEMIN, sinon $AMCLI_MODEL, sinon le *.archimate le plus proche en remontant depuis le répertoire de travail. Si plusieurs sont trouvés, il quitte avec le code 4 et les liste — utilisez -m.
La boucle
Commencez chaque question d'architecture ici. N'ouvrez pas le code source en premier.
amcli stats # quelle est la taille et la composition
amcli search <terme> # trouver le concept, obtenir son id
amcli get <id-ou-nom> # ce que c'est, et tout ce qu'il touche
amcli trace <id-ou-nom> -n 2 # le voisinage
# seulement maintenant lisez le code source, et uniquement les fichiers pointés par le modèle
Les options ne font qu'une chose chacune
-t type de concept -r type de relation -f dossier -D direction (out|in|both)
-n profondeur -l limite -m modèle -F format -o fichier de sortie
Les sujets sont positionnels, jamais des options :
amcli element add ApplicationComponent "Service Remboursement" -f /Application
amcli relation add Serving "Service Remboursement" "Service Paiement"
Sortie et économie de tokens
La sortie par défaut est des enregistrements séparés par des tabulations, un par ligne — peu coûteux à lire et faciles à découper avec cut -f2. Les compteurs et les astuces vont sur stderr. Ajoutez -F json uniquement lorsque vous avez besoin d'une structure imbriquée, comme les identifiants de relations dans get.
amcli query 'layer=Application' --count # demandez « combien » EN PREMIER, toujours
amcli search auth -l 10 --fields id,name # projetez vers le bas
amcli list --fields -documentation # ou retirez un champ
Ne lancez jamais un list non filtré sur un modèle inconnu. Exécutez d'abord amcli stats.
Adresser les concepts
id:5dde26f7 un id — toujours sans ambiguïté, toujours à préférer
"API Paiement" un nom exact
ApplicationComponent:"Paiement" un nom qualifié par le type
"*Paiement*" un glob
Expressions de filtre, citées comme un seul argument :
amcli query 'type=ApplicationComponent and name~paiement'
amcli query 'prop:owner=team-a and not folder^=/Technology'
amcli query 'layer=Application and deg>10'
amcli query 'out:Access~Client' # tout ce qui accède à quelque chose qui correspond
Opérateurs : = exact · ~ contient · ^= préfixe · =~ regex · != · > <
sur deg. Champs : id name type layer folder doc deg view prop:KEY in:TypeRelation out:TypeRelation.
Codes de sortie — basez-vous sur eux, ne parsez pas les messages
0 ok 2 usage 3 non trouvé 4 ambigu 5 invalide 6 conflit
7 io 8 non supporté
Sur 3, la réponse liste les noms les plus proches — réessayez avec l'un d'eux, ne relancez pas une autre recherche. Sur 4, elle liste les candidats, chacun avec un sélecteur id: prêt à être collé. Ne contournez jamais une ambiguïté en devinant ; relancez avec l'id.
Questions de graphe
amcli path "Application Web" "Base de données Clients" # comment sont-ils connectés ?
amcli impact id:5dde26f7 -D in # que se casse-t-il si cela change ?
amcli neighbors id:5dde26f7 -r Serving # uniquement les relations de type Serving
amcli descendants "Capacité Paiements" # l'arbre de composition
amcli cycles # cycles de dépendances
Édition
amcli element add ApplicationComponent "Service Remboursement" --doc "…"
amcli element rename id:c40a19b7 "Services Remboursement"
amcli relation add Access "Services Remboursement" "Enregistrement Remboursement" --access rw
amcli prop set id:c40a19b7 owner team-paiements
amcli element delete id:c40a19b7 -y
Chaque écriture est d'abord vérifiée par rapport à la matrice de relations ArchiMate et refusée (code 5) si la norme l'interdit — et le refus nomme ce qui est autorisé entre ces deux types, alors lisez-le plutôt que de deviner à nouveau.
La suppression refuse par défaut quand elle entraînerait la suppression d'autres éléments, et le refus est le rapport d'impact. Ajoutez -y une fois que vous l'avez lu.
Utilisez --dry-run en cas de doute. Utilisez --expect-checksum lorsque vous avez lu le modèle lors d'un tour précédent et que vous écrivez maintenant :
CS=$(amcli info -F json -q | jq -r '.[0].checksum')
amcli element rename id:x "Nouveau" --expect-checksum "$CS" # code 6 s'il a bougé
Pour plus de deux modifications, utilisez un lot atomique plutôt qu'une séquence.
amcli apply - <<'EOF'
{"op":"element.add","type":"ApplicationComponent","name":"Service Remboursement","ref":"r","if_absent":true}
{"op":"element.add","type":"DataObject","name":"Enregistrement Remboursement","ref":"rec","if_absent":true}
{"op":"relation.add","type":"Access","source":"ref:r","target":"ref:rec","access":"rw","if_absent":true}
EOF
ref nomme le résultat d'une ligne pour qu'une ligne suivante puisse y faire référence avant que son id n'existe. if_absent rend le lot sûr à réexécuter. Si une ligne échoue, rien n'est écrit et le fichier est byte-identique.
Avant de terminer une édition
amcli validate
Le code 5 signifie que le modèle contient des erreurs. Chaque résultat nomme une ligne dans le fichier et porte une commande fix. amcli validate --fix applique uniquement les réparations qui sont dérivées plutôt que choisies — les objets de diagramme orphelins et les miroirs de vue obsolètes — et ne supprime jamais la modélisation de personne.
Vues et diagrammes
amcli view list
amcli view auto "Flux Remboursement" --from "Service Remboursement" -n 2 --layout layered
amcli view render "Flux Remboursement" -o remboursement.svg
amcli export mermaid # un diagramme inline rapide pour le chat
view render dessine la géométrie que le modèle stocke réellement. export mermaid et export dot réorganisent la mise en page, ils sont donc pour un aperçu rapide, pas pour reproduire le diagramme de quelqu'un.
Aller plus loin
| Où | Quand |
|---|---|
amcli skill commands | vous avez besoin d'une sous-commande ou d'une option non montrée ci-dessus — il imprime tout l'arbre, lu depuis le binaire que vous exécutez actuellement, donc il n'est jamais obsolète |
amcli <commande> --help | vous avez besoin des options d'une commande en détail |
references/types.md | vous avez besoin d'un nom de type ArchiMate 3.2 exact, ou de savoir quelles relations sont légales entre deux types |
references/batch.md | vous écrivez un lot de plus d'une dizaine d'opérations environ |