amcli — Modelos ArchiMate a partir da linha de comando
Um único binário que lê e edita arquivos de modelo ArchiMate diretamente. Sem GUI, sem JVM, sem servidor.
Nunca leia um arquivo .archimate com Read ou cat. Eles chegam a megabytes
de XML. Cada pergunta que você tem é um comando amcli, e editar esse XML
manualmente corrompe os modelos.
Configuração
Execute isto antes de qualquer outra coisa:
amcli --version
Se imprimir uma versão, prossiga para a próxima seção. Se não:
Onde sh roda — macOS, Linux, WSL, Git Bash — use o instalador que
veio com esta skill. Ele fica ao lado deste arquivo, que normalmente está em
~/.agents/skills/amcli, ou ./.agents/skills/amcli para uma instalação de
projeto:
AMCLI=$(sh ~/.agents/skills/amcli/scripts/install.sh)
Ele imprime o caminho absoluto do binário no stdout e nada mais. Use
$AMCLI pelo resto da sessão. Um binário recém-instalado geralmente ainda não
está no PATH do shell atual, então amcli simples ainda reportará "comando não
encontrado" mesmo que a instalação tenha sido bem-sucedida — essa é a forma mais
comum de isso dar errado.
PowerShell nativo do Windows, onde não há sh, use o do PowerShell no lugar.
Ele segue o mesmo contrato:
$AMCLI = & ~\.agents\skills\amcli\scripts\install.ps1
Ambos os instaladores não pedem nada, nunca elevam privilégios e nunca editam configurações de shell. Se nenhum binário pré-compilado corresponder à plataforma, eles compilam um com cargo por conta própria. Não pipie nenhum deles a partir de uma URL — eles já estão no disco.
Encontrando o modelo
amcli encontra o modelo sozinho: -m CAMINHO, senão $AMCLI_MODEL, senão o
*.archimate mais próximo subindo a partir do diretório de trabalho. Se vários
forem encontrados, ele sai com código 4 e os lista — use -m.
O loop
Comece toda pergunta de arquitetura aqui. Não abra código-fonte primeiro.
amcli stats # qual o tamanho disso, e de quê
amcli search <termo> # encontre o conceito, pegue seu id
amcli get <id-ou-nome> # o que é, e tudo que ele toca
amcli trace <id-ou-nome> -n 2 # a vizinhança
# só agora leia o código-fonte, e apenas os arquivos que o modelo te apontou
Flags significam uma coisa cada
-t tipo de conceito -r tipo de relacionamento -f pasta -D direção (saída|entrada|ambos)
-n profundidade -l limite -m modelo -F formato -o arquivo de saída
Sujeitos são posicionais, nunca flags:
amcli element add ApplicationComponent "Serviço de Reembolso" -f /Application
amcli relation add Serving "Serviço de Reembolso" "Serviço de Checkout"
Saída e economia de tokens
A saída padrão é registros separados por tabulação, um por linha — baratos de ler e
fáceis de usar com cut -f2. Contagens e dicas vão para stderr. Adicione -F json
apenas quando precisar de estrutura aninhada, como os ids de relacionamento dentro
de get.
amcli query 'layer=Application' --count # pergunte "quantos" PRIMEIRO, sempre
amcli search auth -l 10 --fields id,name # projete para baixo
amcli list --fields -documentation # ou remova um campo
Nunca execute um list sem filtro em um modelo desconhecido. Execute amcli stats
primeiro.
Endereçando conceitos
id:5dde26f7 um id — sempre inequívoco, sempre prefira-o
"Payment API" um nome exato
ApplicationComponent:"Payment" um nome qualificado por tipo
"*Payment*" um glob
Expressões de filtro, citadas como um argumento:
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' # tudo que acessa algo que corresponde
Operadores: = exato · ~ contém · ^= prefixo · =~ regex · != · > <
em deg. Campos: id name type layer folder doc deg view prop:KEY in:RelType out:RelType.
Códigos de saída — ramifique neles, não analise mensagens
0 ok 2 uso 3 não encontrado 4 ambíguo 5 inválido 6 conflito
7 io 8 não suportado
Em 3, a resposta lista os nomes mais próximos — tente novamente com um, não execute
outra busca. Em 4, lista candidatos, cada um com um seletor id: pronto para
colar. Nunca contorne uma ambiguidade adivinhando; execute novamente com o id.
Perguntas de grafo
amcli path "Web App" "Customer Database" # como estão conectados?
amcli impact id:5dde26f7 -D in # o que quebra se isso mudar?
amcli neighbors id:5dde26f7 -r Serving # apenas relacionamentos Serving
amcli descendants "Payments Capability" # a árvore de composição
amcli cycles # ciclos de dependência
Edição
amcli element add ApplicationComponent "Serviço de Reembolso" --doc "…"
amcli element rename id:c40a19b7 "Serviço de Reembolsos"
amcli relation add Access "Serviço de Reembolsos" "Registro de Reembolso" --access rw
amcli prop set id:c40a19b7 owner equipe-pagamentos
amcli element delete id:c40a19b7 -y
Cada escrita é verificada primeiro contra a matriz de relacionamentos do ArchiMate e recusada (código 5) se o padrão a proibir — e a recusa nomeia o que é permitido entre esses dois tipos, então leia ao invés de tentar novamente.
Deletar recusa por padrão quando removeria outras coisas junto, e a
recusa é o relatório de impacto. Adicione -y depois de lê-lo.
Use --dry-run quando estiver em dúvida. Use --expect-checksum quando você
leu o modelo em uma rodada anterior e está escrevendo agora:
CS=$(amcli info -F json -q | jq -r '.[0].checksum')
amcli element rename id:x "Novo" --expect-checksum "$CS" # código 6 se mudou
Para mais de duas edições, use um lote atômico em vez de uma sequência.
amcli apply - <<'EOF'
{"op":"element.add","type":"ApplicationComponent","name":"Serviço 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 nomeia o resultado de uma linha para que uma linha posterior possa apontar
para ele antes de seu id existir. if_absent torna o lote seguro para re-executar.
Se qualquer linha falhar, nada é escrito e o arquivo fica byte-idêntico.
Antes de finalizar qualquer edição
amcli validate
Código 5 significa que o modelo tem erros. Cada achado nomeia uma linha no arquivo
e carrega um comando fix. amcli validate --fix aplica apenas os reparos que
são derivados em vez de escolhidos — objetos de diagrama órfãos e espelhos de
visão obsoletos — e nunca deleta a modelagem de ninguém.
Visões e diagramas
amcli view list
amcli view auto "Fluxo de Reembolso" --from "Serviço de Reembolso" -n 2 --layout layered
amcli view render "Fluxo de Reembolso" -o reembolso.svg
amcli export mermaid # um diagrama rápido inline para chat
view render desenha a geometria que o modelo realmente armazena. export mermaid
e export dot re-organizam o layout, então são para uma olhada rápida, não para
reproduzir o diagrama de alguém.
Aprofundando-se
| Onde | Quando |
|---|---|
amcli skill commands | você precisa de um subcomando ou flag não mostrados acima — ele imprime toda a árvore, lida diretamente do binário que você está executando, então nunca está desatualizado |
amcli <comando> --help | você precisa dos flags de um comando em detalhes |
references/types.md | você precisa do nome exato de um tipo ArchiMate 3.2, ou de quais relacionamentos são legais entre dois tipos |
references/batch.md | você está escrevendo um lote de mais de cerca de dez operações |