amcli — Modelos ArchiMate desde la línea de comandos
Un único binario que lee y edita directamente archivos de modelo ArchiMate. Sin GUI, sin JVM, sin servidor.
Nunca leas un archivo .archimate con Read o cat. Pueden ocupar megabytes de XML. Cada pregunta que tengas es un comando amcli, y editar ese XML manualmente corrompe los modelos.
Configuración
Ejecuta esto antes que cualquier otra cosa:
amcli --version
Si imprime una versión, continúa con la siguiente sección. Si no lo hace:
Dondequiera que sh se ejecute — macOS, Linux, WSL, Git Bash — usa el instalador que viene con esta habilidad. Está junto a este archivo, normalmente en ~/.agents/skills/amcli, o ./.agents/skills/amcli para una instalación de proyecto:
AMCLI=$(sh ~/.agents/skills/amcli/scripts/install.sh)
Imprime la ruta absoluta del binario en stdout y nada más. Usa $AMCLI para el resto de la sesión. Un binario recién instalado normalmente no está aún en el PATH del shell actual, por lo que amcli simple seguirá reportando "comando no encontrado" aunque la instalación haya sido exitosa — esa es la forma más común en que esto falla.
PowerShell nativo de Windows, donde no hay sh, usa el de PowerShell en su lugar. Sigue el mismo contrato:
$AMCLI = & ~\.agents\skills\amcli\scripts\install.ps1
Cualquiera de los instaladores no pide nada, nunca se eleva y nunca edita la configuración del shell. Si no hay un binario precompilado que coincida con la plataforma, lo compila con cargo por sí mismo. No los ejecutes desde una URL — ya están en disco.
Encontrar el modelo
amcli encuentra el modelo por sí mismo: -m RUTA, sino $AMCLI_MODEL, sino el *.archimate más cercano subiendo desde el directorio de trabajo. Si se encuentran varios, sale con código 4 y los lista — usa -m.
El bucle principal
Empieza cada pregunta de arquitectura aquí. No abras el código fuente primero.
amcli stats # qué tan grande es esto y de qué tipo
amcli search <término> # encuentra el concepto, obtén su id
amcli get <id-o-nombre> # qué es y todo lo que toca
amcli trace <id-o-nombre> -n 2 # el vecindario
# solo ahora lee el código fuente, y solo los archivos a los que el modelo te apuntó
Las banderas significan una cosa cada una
-t tipo de concepto -r tipo de relación -f carpeta -D dirección(salir|entrar|ambas)
-n profundidad -l límite -m modelo -F formato -o archivo de salida
Los sujetos son posicionales, nunca banderas:
amcli element add ApplicationComponent "Servicio de Reembolso" -f /Application
amcli relation add Serving "Servicio de Reembolso" "Servicio de Pago"
Salida y economía de tokens
La salida predeterminada son registros separados por tabulaciones, uno por línea — barato de leer y fácil para cut -f2. Los conteos y sugerencias van a stderr. Agrega -F json solo cuando necesites estructura anidada, como los IDs de relaciones dentro de get.
amcli query 'layer=Application' --count # pregúntate "cuántos" PRIMERO, siempre
amcli search auth -l 10 --fields id,name # proyecta
amcli list --fields -documentation # o elimina un campo
Nunca ejecutes un list sin filtrar en un modelo desconocido. Ejecuta amcli stats primero.
Direccionamiento de conceptos
id:5dde26f7 un id — siempre inequívoco, siempre prefierelo
"API de Pago" un nombre exacto
ApplicationComponent:"Pago" un nombre calificado por tipo
"*Pago*" un glob
Expresiones de filtro, citadas como un solo argumento:
amcli query 'type=ApplicationComponent and name~pago'
amcli query 'prop:owner=equipo-a and not folder^=/Technology'
amcli query 'layer=Application and deg>10'
amcli query 'out:Access~Cliente' # todo lo que accede a algo que coincide
Operadores: = exacto · ~ contiene · ^= prefijo · =~ regex · != · > < en deg. Campos: id name type layer folder doc deg view prop:KEY in:TipoRel out:TipoRel.
Códigos de salida — ramifica con estos, no analices mensajes
0 ok 2 uso 3 no encontrado 4 ambiguo 5 inválido 6 conflicto
7 io 8 no soportado
En 3, la respuesta lista los nombres más cercanos — reintenta con uno, no ejecutes otra búsqueda. En 4, lista candidatos, cada uno con un selector id: listo para pegar. Nunca evites la ambigüedad adivinando; vuelve a ejecutar con el id.
Preguntas de grafo
amcli path "App Web" "Base de Datos de Clientes" # cómo están conectados estos?
amcli impact id:5dde26f7 -D in # qué se rompe si esto cambia?
amcli neighbors id:5dde26f7 -r Serving # solo relaciones Serving
amcli descendants "Capacidad de Pagos" # el árbol de composición
amcli cycles # ciclos de dependencia
Edición
amcli element add ApplicationComponent "Servicio de Reembolso" --doc "..."
amcli element rename id:c40a19b7 "Servicio de Reembolsos"
amcli relation add Access "Servicio de Reembolsos" "Registro de Reembolso" --access rw
amcli prop set id:c40a19b7 owner equipo-pagos
amcli element delete id:c40a19b7 -y
Cada escritura se verifica primero contra la matriz de relaciones de ArchiMate y se rechaza (código de salida 5) si el estándar lo prohíbe — y el rechazo nombra lo que está permitido entre esos dos tipos, así que léelo en lugar de adivinar de nuevo.
Eliminar se rechaza por defecto cuando arrastraría otras cosas consigo, y el rechazo es el informe de impacto. Agrega -y una vez que lo hayas leído.
Usa --dry-run cuando no estés seguro. Usa --expect-checksum cuando leíste el modelo en un turno anterior y estás escribiendo ahora:
CS=$(amcli info -F json -q | jq -r '.[0].checksum')
amcli element rename id:x "Nuevo" --expect-checksum "$CS" # código de salida 6 si cambió
Para más de dos ediciones, usa un lote atómico en lugar de una secuencia.
amcli apply - <<'EOF'
{"op":"element.add","type":"ApplicationComponent","name":"Servicio de Reembolso","ref":"r","if_absent":true}
{"op":"element.add","type":"DataObject","name":"Registro de Reembolso","ref":"rec","if_absent":true}
{"op":"relation.add","type":"Access","source":"ref:r","target":"ref:rec","access":"rw","if_absent":true}
EOF
ref nombra el resultado de una línea para que una línea posterior pueda apuntar a él antes de que exista su id. if_absent hace que el lote sea seguro de reejecutar. Si alguna línea falla, no se escribe nada y el archivo es idéntico byte a byte.
Antes de finalizar cualquier edición
amcli validate
El código de salida 5 significa que el modelo tiene errores. Cada hallazgo nombra una línea en el archivo y lleva un comando fix. amcli validate --fix aplica solo las reparaciones que son derivadas en lugar de elegidas — objetos de diagrama huérfanos y espejos de vista obsoletos — y nunca elimina el modelado de nadie.
Vistas y diagramas
amcli view list
amcli view auto "Flujo de Reembolso" --from "Servicio de Reembolso" -n 2 --layout layered
amcli view render "Flujo de Reembolso" -o reembolso.svg
amcli export mermaid # un diagrama en línea rápido para el chat
view render dibuja la geometría que el modelo realmente almacena. export mermaid y export dot reorganizan el diseño, por lo que son para una vista rápida, no para reproducir el diagrama de alguien.
Profundizando
| Dónde | Cuándo |
|---|---|
amcli skill commands | necesitas un subcomando o bandera no mostrados arriba — imprime todo el árbol, leído del binario que realmente estás ejecutando, por lo que nunca está desactualizado |
amcli <comando> --help | necesitas las banderas de un comando en detalle |
references/types.md | necesitas un nombre de tipo exacto de ArchiMate 3.2, o qué relaciones son legales entre dos tipos |
references/batch.md | estás escribiendo un lote de más de aproximadamente diez operaciones |