Archyl CLI

archyl conecta um repositório à sua arquitetura no Archyl. Do seu terminal, você descobre onde um arquivo fica no modelo C4, vê o que sua branch afeta e quem avisar, prepara um briefing para os agentes de programação antes que toquem no código e vigia o que eles escrevem.

$ archyl impact

◆ archyl  impact  vs origin/main · 14 changed files

▍ Touched
  ◉ HTTP Handlers    3 files    Archyl / Backend
  ◉ Harness Service  3 files    Archyl / Backend
  ◉ Task Context     1 file     Archyl / Backend

▍ Blast radius
  ◉ Harness Service
  ├── ◉ HTTP Handlers  calls · 1 hop   @platform
  ├── ◉ MCP Server     calls · 1 hop
  ╰── ▣ Frontend       calls · 2 hops  @web

▍ Notify
  @platform · @web · ada@example.com

A CLI é open source sob a licença MIT: github.com/archyl-com/cli.

Instalação

# Homebrew (macOS, Linux)
brew install archyl-com/tap/archyl

# Install script (macOS, Linux): checks the archive's checksum
curl -fsSL https://raw.githubusercontent.com/archyl-com/cli/main/install.sh | sh

# Go (1.26 or later)
go install github.com/archyl-com/cli/cmd/archyl@latest

Você também pode baixar um binário na página de releases. Os arquivos têm checksum, são assinados com cosign e vêm acompanhados de um SBOM.

Verifique a instalação com archyl --version.

Primeiros passos

Na raiz do seu repositório:

archyl login          # sign in through your browser
archyl init           # link this repository to its Archyl project
archyl status         # alignment score, your branch, active agents

archyl login abre seu navegador e faz o login com OAuth 2.1 e PKCE. A sessão é guardada no chaveiro do sistema operacional e se renova sozinha; você só precisa entrar de novo depois de um mês sem uso.

archyl init grava .archyl.json na raiz do repositório, para que todo comando archyl, e o hook Guard, saiba a qual projeto esse código pertence. Quando o remote do repositório está conectado a um projeto no Archyl, esse projeto é escolhido para você; caso contrário, você o seleciona em uma lista. Faça commit do arquivo: ele não contém nenhum segredo, e assim seu time e sua CI compartilham o vínculo.

{
  "projectId": "3f2a9c4e-…",
  "projectName": "Checkout",
  "organizationId": "8b1d…",
  "apiUrl": "https://api.archyl.com"
}

Execute archyl init --force para vincular um repositório a outro projeto.

Ainda não tem um projeto? archyl init --new cria um sem sair do terminal:

1. Cria o projeto, com o nome do repositório (ou --name), na equipe que você escolher (--team, por nome, slug ou ID).
2. Conecta o repositório a partir do seu remote git. Para um remote auto-hospedado, informe o provedor com --provider: github_enterprise, gitlab_private ou gitea.
3. Inicia uma descoberta com IA em --branch (padrão: a branch padrão do remote) e mostra o progresso ao vivo.
4. Abre a revisão do que a descoberta encontrou e depois desenha o resultado como um diagrama.
5. Oferece conectar seus agentes de programação.

archyl init sozinho oferece o mesmo quando nenhum projeto corresponde ao remote do repositório. --no-discover apenas cria e vincula o projeto, --no-setup pula a última etapa e --yes aceita todos os padrões sem perguntar, inclusive aprovando o que a descoberta encontrar.

archyl init --new
archyl init --new --name "Checkout" --team platform
archyl init --new --yes --json

A sessão

Execute archyl sozinho para abrir uma sessão: um prompt onde você pergunta sobre a arquitetura em linguagem natural ou digita comandos, com as respostas aparecendo no seu terminal como qualquer outra saída.

$ archyl

◆ archyl
  Checkout · feature/refunds · alignment 86
  Ask anything about the architecture. / commands · @ files · # elements

› which elements does my branch touch, and who should I tell?
  ⏺ archyl impact
    Touched  ◉ Payments  4 files  in Checkout / API
    … +12 lines

  Your branch changes Payments, which Checkout Web calls and the Refund
  Worker reads. Tell @payments before merging.

› /run last

• Linguagem natural vai para o assistente. Ele responde a partir da arquitetura e, quando a resposta depende do seu código ou do que está acontecendo agora, executa aqui o comando correspondente — impact, check, brief, show, runs… — e mostra cada um (⏺) antes de usar a saída dele. Comandos somente leitura rodam em paralelo; comandos que alteram algo, como aprovar o plano de uma execução ou registrar uma memória, pedem sua confirmação antes (y/n).
• Comandos / são executados diretamente: /impact, /review, /brief <files>, /show <element>, /runs, /activity… Visualizações em tela cheia (/map, /search, /run, /agents) ocupam a tela e a devolvem quando você sai delas. /help lista tudo.
• @file anexa à pergunta o conteúdo do arquivo, com o briefing de arquitetura dele: até 400 linhas ou 24 KB por arquivo; arquivos binários e caminhos fora do repositório são ignorados. #element direciona a pergunta a um elemento. Ambos têm autocompletar enquanto você digita.
• Enter envia; Shift+Enter (ou Alt+Enter, Ctrl+J) começa uma nova linha, e o texto colado mantém suas quebras de linha.
• ↑ ↓ percorrem seu histórico, Tab completa, Esc interrompe uma resposta, Ctrl-D sai.

As conversas são guardadas por repositório: archyl -c (--continue) reabre a última, /resume escolhe uma anterior em uma lista e /new começa uma nova.

Na primeira vez, a sessão informa o que está faltando: fazer login (/login), vincular o repositório (/init). O assistente está disponível nos planos que incluem o chat de IA; os comandos / funcionam em todos os planos. Com modelos da OpenAI e da Anthropic, ele chama os comandos como ferramentas nativas; com outros provedores, passa por um protocolo de texto, e você não nota nenhuma diferença.

doctor

archyl doctor verifica tudo de que a CLI depende e diz como corrigir o que não está certo: sua versão, o perfil, o login, a latência da API, o repositório, o vínculo com o projeto, os agentes conectados, o hook Guard e o hook pre-push. Sai com código 1 quando algo precisa ser corrigido.

Explorar a arquitetura

activity

archyl activity é um único feed do que acontece no projeto: elementos criados e alterados (com os campos que mudaram), solicitações de mudança abertas e mescladas, execuções de agentes na fila, aguardando alguém e concluídas, sessões de trabalho abertas e encerradas. --follow o mantém aberto e imprime os eventos à medida que acontecem, como tail -f; adicione --notify para receber uma notificação na área de trabalho quando um agente estiver aguardando você.

archyl activity --follow --notify
archyl activity --element "Payments"

map

archyl map abre um explorador em tela cheia do modelo C4: sistemas, containers, componentes e código em uma árvore, com a descrição de cada elemento, suas tecnologias, seus relacionamentos nos dois sentidos e seu raio de impacto. Informe um elemento para abrir diretamente nele: archyl map "Payments".

d mostra o nível atual como diagrama. Tab e Shift+Tab selecionam um elemento, as setas ou h j k l rolam a vista, Enter desce na seleção, Backspace ou u volta a subir, o abre no app web, y copia o ID, e d ou Esc volta para a árvore.

diagram

archyl diagram desenha uma visão C4 do modelo: o contexto de sistema por padrão, os contêineres de um sistema quando você nomeia um sistema, os componentes de um contêiner quando você nomeia um contêiner. Elementos fora da visão aparecem tracejados, por causa das relações com ela.

archyl diagram
archyl diagram Billing
archyl diagram "Billing API" -o billing-api.png
archyl diagram --format mermaid > context.mmd
archyl diagram Billing --json | jq '.nodes[].name'

No Kitty, Ghostty, WezTerm e iTerm2 o diagrama é uma imagem dentro do terminal. Nos outros terminais, e quando a saída vai para um pipe, ele é desenhado com caracteres de caixa:

 ┌─────────────────┐   ┌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┐   ┌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┐
 │ ▣ Storefront    │   ╎ ◆ Warehouse     ╎   ╎ ◆ Mailgun       ╎
 │ web app · React │   ╎ software system ╎   ╎ software system ╎
 └────────┬────────┘   └╌╌╌╌╌╌╌╌┬╌╌╌╌╌╌╌╌┘   └╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┘
          │                     │
          └───────────────┐     │ updates stock
         places orders ×2 │     │
                          ▼     ▼
                    ┌─────────────────┐
                    │ ▣ Shop API  4 ◉ │
                    │ api · Go        │
                    └─────┬─────┬─────┘
            charges cards │     │ reads from ×2
                          ▼     ▼

Dentro do tmux, as imagens precisam de set -g allow-passthrough on e de um terminal que entenda o protocolo de imagens do iTerm2. Defina ARCHYL_IMAGES=0 para sempre desenhar em texto.

search

archyl search pesquisa tudo o que você pode ver no Archyl: elementos, decisões, documentação, contratos de API, canais de eventos, fluxos e projetos. Os resultados se atualizam enquanto você digita, com uma pré-visualização; Enter mostra o item escolhido, ctrl+o o abre no aplicativo web. Em um pipe ou com --json, archyl search invoice imprime os resultados.

show

archyl show <element> imprime um elemento com seu caminho, descrição, tecnologias, relacionamentos, decisões vinculadas e raio de impacto. archyl show ADR-12 exibe um registro de decisão. Os elementos são encontrados pelo nome (exato, depois parcial) ou pelo ID.

open

archyl open abre o projeto no aplicativo web; archyl open "Payments" seleciona um elemento no diagrama, archyl open ADR-12 expande uma decisão. O endereço do aplicativo web é o host da API com api. substituído por app.; quando ele fica em outro lugar, faça login com --app-url ou defina ARCHYL_APP_URL.

ask

archyl ask "<question>" faz uma pergunta ao assistente de IA sobre a arquitetura do projeto. A resposta é renderizada em markdown enquanto é escrita. Tudo o que você passar por pipe é adicionado à pergunta:

archyl ask "Which services write to the orders database?"
git diff main | archyl ask "Does this break any of our decisions?"

O assistente está disponível nos planos que incluem o chat de IA.

adr

archyl adr lista as decisões do projeto. archyl adr new registra uma: em um terminal, um formulário pede o título, o status, o contexto, a decisão e as consequências; em scripts, passe-os como flags.

archyl adr new "Use slog for structured logging" --status accepted \
  --context "Three logging libraries are in use" --decision "slog everywhere"

discover

archyl discover inicia uma descoberta com IA nos repositórios vinculados ao projeto e a acompanha, com o progresso na stderr. O que ela encontra não entra no modelo de imediato: fica aguardando revisão, que se abre sozinha quando a descoberta termina em um terminal. Cada repositório vinculado conta como uma descoberta com IA na cota do seu plano.

archyl discover
archyl discover --repo acme/payments --branch develop
archyl discover --no-wait --json

archyl discover review lista os elementos propostos pelas descobertas, agrupados por nível C4, com os detalhes do elemento selecionado ao lado:

Fora de um terminal, imprime a lista; --approve-all ou --reject-all resolve tudo de uma vez, e --json a imprime para scripts.

Comandos de arquitetura

where

archyl where <path>… situa arquivos no modelo C4: o elemento ao qual cada um pertence, quem é o responsável e o que depende dele. Diretórios são expandidos para os arquivos que o git conhece.

archyl where internal/billing/invoice.go
archyl where src/checkout/

why

archyl why <file[:line]> é o git blame da arquitetura. Para um arquivo, mostra os elementos a que ele pertence, as decisões que se aplicam (as aceitas primeiro), quem é responsável, o que agentes e pessoas registraram sobre ele, as últimas mudanças do modelo nesses elementos e as regras de conformidade voltadas para ele. Com um número de linha, encontra também o commit que alterou a linha por último e o relaciona às decisões tomadas na mesma época.

archyl why internal/billing/invoice.go
archyl why internal/billing/invoice.go:42
archyl why --json src/checkout/cart.ts | jq '.decisions[].title'

Em um terminal a resposta é formatada; em um pipe ou executado por um agente, imprime markdown compacto.

impact

archyl impact compara sua árvore de trabalho com uma branch base, situa cada arquivo alterado na arquitetura e percorre os relacionamentos para encontrar o que depende dele, junto com os responsáveis a avisar. Ele cobre mudanças com commit, em stage, fora de stage e não rastreadas, então você pode executá-lo antes mesmo de fazer commit.

archyl impact --base origin/develop --depth 3
archyl impact --diagram

Cada arquivo conta apenas para a correspondência mais específica: um arquivo mapeado para um componente não arrasta junto o container inteiro.

status

archyl status resume o projeto em uma única tela: o alinhamento entre modelo e código, sua branch e os agentes trabalhando no projeto neste momento.

context

archyl context imprime a arquitetura do projeto em markdown ajustado para agentes de programação: sistemas, containers, componentes, relacionamentos, decisões e regras. Encadeie a saída com um pipe ou grave-a no arquivo que seu agente lê.

archyl context > ARCHITECTURE.md
archyl context -o .archyl/context.md

Agentes de programação

A CLI é a forma mais rápida de colocar um agente de programação sob o Archyl Harness.

setup

archyl setup

archyl setup configura Claude Code, Cursor, VS Code e Codex para usar o servidor MCP do Archyl com o perfil de ferramentas coding, instala o hook Guard e ensina a CLI aos agentes. Restrinja-o com --agent (repetível: claude-code, cursor, vscode, codex); dispense partes com --no-guard, --no-instructions ou --no-statusline.

archyl setup também oferece instalar o autocompletar do shell; --no-completion pula essa etapa.

Arquivos existentes são mesclados, não sobrescritos.

Por padrão (--transport cli), cada agente inicia archyl mcp, que acessa o servidor MCP do Archyl com a própria sessão da CLI: faça login uma vez com archyl login e todos os agentes ficam conectados, sem fluxo OAuth por agente e sem chave em arquivo. Com --transport http, a configuração contém apenas a URL do servidor e cada agente faz login pelo próprio Archyl. Em ambos os casos, os arquivos do repositório não contêm nenhum segredo e podem receber commit com segurança.

mcp

archyl mcp serve as ferramentas MCP do Archyl a um agente via stdio, autenticado como você. archyl setup o configura; à mão, para qualquer cliente MCP:

{ "mcpServers": { "archyl": { "command": "archyl", "args": ["mcp"] } } }

Ele usa o perfil de ferramentas coding; --tools full expõe todas as ferramentas.

O bloco da CLI é uma seção curta entre os marcadores <!-- archyl:start --> e <!-- archyl:end --> que diz ao agente quais comandos archyl executar e quando: plan antes de uma mudança não trivial, brief antes de editar arquivos, check e radar check antes de terminar, remember e recall para o que o código não consegue mostrar. Executar setup de novo atualiza o bloco e deixa o resto do arquivo intacto. Uma linha de status já definida no Claude Code nunca é substituída.

plan

archyl plan "<task>" devolve um plano de implementação fundamentado na arquitetura: as etapas, o elemento que cada uma toca, as decisões e regras a respeitar e o que as sessões anteriores aprenderam.

archyl plan "Add partial refunds to the payments flow"

brief

archyl brief <files> diz a você, ou a um agente, o que saber antes de editar esses arquivos: os elementos aos quais pertencem, o que esses elementos usam e o que depende deles, as decisões que se aplicam a eles ou aos seus pais, os responsáveis e o que o Archyl lembra sobre eles. Sem caminhos, cobre todos os arquivos que a branch altera.

Assim como plan, recall e context, ele é renderizado em um terminal e imprime markdown compacto quando um agente o executa a partir do seu shell, para que o agente leia estrutura, e não códigos de escape.

remember e recall

archyl remember registra, no elemento a que se refere, um fato que o código não consegue mostrar; toda sessão de trabalho futura sobre esse elemento recebe esse fato no briefing. archyl recall encontra o que o Archyl lembra, por assunto, elemento ou tipo.

archyl remember "Refund amounts are in minor units; never use floats" \
  --element "Payments" --kind pitfall
archyl recall refunds
archyl recall --element "Payments" --kind convention

A memória é atribuída ao agente que a escreveu quando a CLI roda dentro do Claude Code, do Codex ou do Cursor; defina ARCHYL_AGENT para nomeá-lo você mesmo.

agents

archyl agents é uma visão ao vivo dos agentes em ação no projeto: qual agente, em qual tarefa, sobre quais elementos, com quais arquivos alterados. Elementos reservados por mais de um agente são sinalizados, para que dois agentes não colidam no mesmo código. Pressione a para incluir as sessões encerradas recentemente. Em um pipe ou com --json, ele imprime as sessões uma única vez.

statusline

archyl statusline é uma linha de status para o Claude Code: o projeto, a pontuação de alinhamento dele, os agentes em ação e se a sessão atual roda sob o harness. archyl setup a instala; à mão, em .claude/settings.json:

{ "statusLine": { "type": "command", "command": "archyl statusline" } }

runs

archyl runs lista as execuções gerenciadas de agentes do projeto, sinalizando as que aguardam você. archyl runs view acompanha uma ao vivo: as mensagens do agente, suas chamadas de ferramentas e os arquivos que ele altera no feed, seu plano com o progresso de cada etapa, e o tempo, os tokens e o custo ao lado. E você age sobre ela sem sair do terminal:

As mesmas ações existem como comandos, para scripts e para agentes que supervisionam outros agentes. As execuções são identificadas pelos primeiros caracteres do ID, ou por last:

archyl runs start "Add partial refunds" --profile backend-fixer
archyl runs view last
archyl runs answer 3f2a9c4e "Keep the v1 endpoint"
archyl runs approve 3f2a9c4e
archyl runs request-changes 3f2a9c4e "Split the migration from the API change"
archyl runs steer 3f2a9c4e "Use the ledger service, not the orders table"
archyl runs continue 3f2a9c4e "Add tests for the edge cases"
archyl runs cancel 3f2a9c4e

As execuções gerenciadas de agentes estão disponíveis nos planos que as incluem.

wrap

archyl wrap -- claude                                   # asks what the task is
archyl wrap --task "Add PDF export to invoices" -- claude
archyl wrap --agent codex --exclusive -- codex "fix the flaky checkout test"

archyl wrap executa qualquer agente dentro de uma sessão de trabalho:

1. Ele abre uma sessão para a tarefa. O Archyl seleciona os elementos, decisões e regras relevantes, reserva esses elementos para que dois agentes não colidam e devolve um briefing com o veredicto do gate.
2. O Claude Code recebe o briefing como um system prompt adicional. Todo agente encontra ARCHYL_SESSION_ID e ARCHYL_BRIEFING_FILE no seu ambiente.
3. Enquanto o agente trabalha, a sessão é mantida viva com um heartbeat a cada 10 minutos, e o hook Guard atribui a ela cada arquivo editado.
4. Quando o agente termina, wrap informa os arquivos alterados, encerra a sessão e oferece abrir um rascunho de solicitação de mudança de arquitetura, para que uma pessoa avalie como o modelo deve ser atualizado.

Se o Archyl estiver inacessível, wrap emite um aviso e executa o agente mesmo assim.

fix

archyl fix
archyl fix --severity high --agent codex
archyl fix --print | pbcopy
archyl fix -- claude --model opus

archyl fix coloca um agente de programação para trabalhar nas violações de regras da sua branch, sob o harness:

1. Executa a verificação de conformidade na branch, como archyl check, e deixa você escolher as violações a corrigir.
2. Abre uma sessão de trabalho e passa ao agente cada violação com sua regra, severidade, localização e sugestão, junto com o brief dos elementos a que os arquivos pertencem e as decisões que se aplicam.
3. Quando o agente termina, executa a verificação de novo e mostra o que sobrou, por exemplo "3 violations → 0".

Nada é commitado: revise as mudanças com git diff. O agente é o primeiro instalado entre Claude Code e Codex, ou o indicado por --agent. Depois de --, qualquer comando roda no lugar dele; ele lê a tarefa do arquivo indicado em ARCHYL_FIX_TASK_FILE.

lsp

archyl lsp é um language server via stdio para qualquer editor com cliente LSP. Ele roda ao lado do servidor próprio da linguagem:

Ele usa a sessão da CLI (archyl login ou ARCHYL_API_KEY) e o .archyl.json do repositório. Quando o Archyl está inacessível, ele grava um único aviso no log LSP do editor e não mostra diagnósticos. Os diagnósticos acompanham os salvamentos, não a digitação.

Neovim 0.11 e posteriores:

vim.lsp.config("archyl", {
  cmd = { "archyl", "lsp" },
  root_markers = { ".archyl.json", ".git" },
  filetypes = { "go", "typescript", "python", "java", "rust" },
})
vim.lsp.enable("archyl")

Helix, em languages.toml:

[language-server.archyl]
command = "archyl"
args = ["lsp"]

[[language]]
name = "go"
language-servers = ["gopls", "archyl"]

O VS Code usa a extensão Generic LSP Client, e o Zed uma pequena extensão de desenvolvimento. A configuração de cada editor está em docs/lsp.md.

guard

archyl guard é o hook PreToolUse do Claude Code que archyl setup instala. Ele lê o payload do hook na stdin, executa as regras de conformidade do projeto sobre o arquivo tal como ele ficaria após a edição e responde com uma decisão: violações críticas bloqueiam a edição, as altas geram um aviso. Defina ARCHYL_GUARD_BLOCK como high para bloquear também as violações altas, ou off para apenas avisar.

Quando o agente edita um manifesto de dependências (go.mod, package.json, pom.xml…), o Guard também o confere com o radar de tecnologias e bloqueia uma dependência que o radar coloca Em espera, com a alternativa que a nota dela sugere. Dependências Em espera que já estavam lá não bloqueiam a edição.

O Guard sempre falha de forma aberta: sem credencial, sem rede ou diante de uma ferramenta desconhecida, a edição passa, então ele nunca pode quebrar seu fluxo de trabalho.

session

archyl session dá acesso de baixo nível ao protocolo de sessões de trabalho, para scripts ou agentes que o conduzem por conta própria. Na maior parte do tempo, archyl wrap faz tudo isso por você.

archyl session start --task "Migrate invoices to the new ledger" --exclusive
archyl session heartbeat <session-id>
archyl session finish --summary "Ledger migration done" \
  --decision "Invoices are written through the ledger service only" \
  --follow-up "Backfill invoices older than 2024" \
  --change-request
archyl session list --all
archyl session cancel <session-id>

finish recebe o ID da sessão como argumento ou a partir de ARCHYL_SESSION_ID. Coloque em --decision apenas escolhas dignas de um ADR: cada uma se torna uma memória reapresentada às sessões futuras sobre os mesmos elementos. Tudo o que é circunstancial vai em --follow-up.

Verificações e CI

Os mesmos comandos rodam no seu notebook, em um hook do git e em qualquer CI. Na CI, eles obtêm do ambiente a branch base, o commit e o formato do relatório: GitHub Actions, GitLab CI, Bitbucket Pipelines e Azure Pipelines são reconhecidos.

check

archyl check executa as regras de conformidade do projeto em cada arquivo que difere da branch base e sai com código 1 quando uma violação atinge --fail-on.

$ archyl check

CRITICAL Forbidden pattern found: fmt.Println (use slog)  No printing in services
   ╭─ internal/billing/invoice.go:42
 42 │ 	fmt.Println("total", total)
   ╰─ → Remove usage of the forbidden pattern: fmt.Println (use slog)

✗ 1 violation in 3 changed files · 1 critical

Com --format auto, a saída acompanha a CI:

--format sarif grava um log SARIF 2.1.0 para o code scanning do GitHub, o Azure DevOps ou qualquer painel de segurança.

Checkouts de CI costumam ser rasos (shallow). Busque o histórico para que a branch base exista; caso contrário, check para e avisa você.

# GitHub Actions
- uses: actions/checkout@v4
  with:
    fetch-depth: 0
- run: archyl check
  env:
    ARCHYL_API_KEY: ${{ secrets.ARCHYL_API_KEY }}

# GitLab CI
archyl:
  variables:
    GIT_DEPTH: 0
  script:
    - archyl check
  artifacts:
    reports:
      codequality: gl-code-quality-report.json

review

archyl review é a verificação a rodar antes de abrir um pull request. Ela reúne as violações de regras que sua branch introduz, os elementos que ela toca junto com o que depende deles, quem avisar e a pontuação de alinhamento atual. Sai com código 1 quando uma violação atinge --fail-on (padrão high).

Com --comment, a revisão é publicada no pull request ou merge request e editada no lugar a cada push seguinte, para que a solicitação mantenha um único comentário do Archyl: o veredicto, as violações com arquivo e linha, os elementos tocados junto com o que depende deles e os responsáveis a envolver. O GitHub precisa de GITHUB_TOKEN com pull-requests: write; o GitLab precisa de GITLAB_TOKEN com o escopo api, já que CI_JOB_TOKEN não pode comentar.

O comentário inclui o impacto como um flowchart Mermaid, que o GitHub e o GitLab renderizam. archyl review --diagram imprime o mesmo flowchart localmente, para colar em uma descrição ou documento.

A forma mais rápida de configurar no GitHub é a action do Archyl, que instala a CLI e executa um comando:

name: Architecture
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  archyl:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: archyl-com/cli@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          command: review --comment

Deixe command vazio para apenas instalar a CLI e chamá-la nas etapas seguintes.

hooks

archyl hooks install                   # blocks critical violations on git push
archyl hooks install --fail-on high
archyl hooks uninstall

archyl hooks install adiciona um hook pre-push do git que executa archyl check --fail-open. Um push que traz uma violação no nível de --fail-on ou acima (padrão critical) é recusado; sem archyl no PATH, offline ou sem login, o push passa. Para pulá-lo uma vez, use git push --no-verify. O hook respeita core.hooksPath, e um hook pre-push que o archyl não escreveu nunca é substituído, a menos que você passe --force.

drift

archyl drift mostra o quanto o modelo documentado corresponde ao código: 100 significa que todo elemento documentado foi encontrado no código. --compute reanalisa primeiro o repositório conectado e aguarda o resultado; --fail-under o transforma em um quality gate.

archyl drift --compute --fail-under 80

dsl

archyl dsl mantém em sincronia um arquivo de arquitetura como código e o modelo do projeto. Todo subcomando trabalha com archyl.yaml na raiz do repositório, a menos que você passe --file.

archyl dsl pull                 # write the project's model to archyl.yaml
archyl dsl diff                 # what pushing the file would change
archyl dsl diff --exit-code     # in CI: fail when the file and the model differ
archyl dsl push                 # import the file into the project

• pull exporta o modelo (elementos, relacionamentos, tecnologias, decisões, documentação, contratos, ambientes e releases). Pergunta antes de sobrescrever o arquivo, a menos que você passe --yes; --file - o imprime em vez disso.
• diff é uma simulação (dry run) no servidor, sem gravar nada: os elementos e relacionamentos que um push adicionaria (+) ou alteraria (~), agrupados por nível C4, e os que só o Archyl tem (−). --exit-code sai com código 1 quando há qualquer diferença.
• push cria os novos elementos e relacionamentos e atualiza os existentes, correspondidos pelo nome. Nunca exclui nada: o que só o Archyl tem permanece. Em um terminal, mostra o diff e pergunta antes; --yes pula a pergunta.

$ archyl dsl diff

▍ Containers
  + Refund Worker
  ~ Payments API
      description  "Card payments" → "Card and wallet payments"
  − Legacy Billing  only in Archyl, push keeps it

  archyl.yaml vs the model: 1 to add · 1 to change · 1 only in Archyl

archyl sync [file] é o mesmo que archyl dsl push.

release

archyl release registra uma release, para correlacionar mudanças de arquitetura com o que foi entregue e alimentar as métricas DORA. A versão padrão é a tag sendo construída na CI e, depois, a tag em HEAD; o link padrão é a execução da CI.

archyl release v2.4.0 --environment production

radar

archyl radar mostra as tecnologias da organização por anel de governança (Adotar, Experimentar, Avaliar, Em espera), com quanto da arquitetura usa cada uma. archyl radar check lê os manifestos de dependências do repositório, associa cada dependência ao radar e sai com código 1 quando alguma está Em espera, com a mesma saída de CI que archyl check.

$ archyl radar check

  HOLD    github.com/sirupsen/logrus 1.9.3  go.mod
          → Use log/slog from the standard library
  ASSESS  go.uber.org/zap 1.27.0  go.mod

✗ 1 dependency on hold · 4 dependencies in 1 manifest · 1 adopt · 0 trial · 1 assess · 1 hold · 1 unclassified

cr

archyl cr lista as solicitações de mudança de arquitetura do projeto — muitas vezes abertas por agentes no fim de uma sessão de trabalho — e permite revisá-las sem sair do terminal.

archyl cr                                   # list
archyl cr show 12                           # the request and its changes
archyl cr approve 12
archyl cr request-changes 12 -m "Keep the ledger behind the Payments API"
archyl cr open 12                           # in the web app

Contas e perfis

Um perfil é um host e uma organização do Archyl com credencial própria. Crie um fazendo login com um nome, que é também a forma de se conectar a um Archyl auto-hospedado:

archyl login --host https://archyl.example.com --profile work
archyl profile use work

Prompt do shell

archyl prompt imprime em poucos caracteres a pontuação de alinhamento do projeto e os agentes ativos, para o prompt do seu shell. Ele nunca espera pela rede: imprime o último estado conhecido e o atualiza em segundo plano a cada dez minutos. Com o Starship:

[custom.archyl]
command = "archyl prompt"
when = "test -f .archyl.json"
format = "[$output]($style) "
style = "purple"

Cache do modelo

map, show, open, o autocompletar de elementos e as sugestões # da sessão respondem a partir de uma cópia local do modelo, por isso iniciam instantaneamente. Há uma cópia por perfil, host, organização, identidade e projeto, no seu diretório de cache de usuário, legível só por você. Uma cópia com menos de 30 segundos é usada sem chamar a API; uma mais antiga é atualizada, e quando a API leva mais de 1,5 segundo o comando responde a partir da cópia e avisa na stderr. Comandos que alteram o modelo, como dsl push ou aprovar descobertas, descartam a cópia.

Ignore o cache em um único comando com --no-cache, ou em todos com ARCHYL_NO_CACHE=1. archyl login e archyl logout limpam as cópias do perfil; archyl cache clear faz isso manualmente.

Atualizações

Quando sai uma versão mais nova, a CLI avisa assim que um comando termina. A verificação roda em segundo plano no máximo uma vez por dia, nunca em CI nem em scripts; defina ARCHYL_NO_UPDATE_NOTIFIER para desativá-la.

archyl upgrade atualiza a CLI do jeito que você a instalou: brew upgrade para Homebrew, o comando go install para um build a partir do código-fonte e, nos demais casos, no próprio lugar: baixa o arquivo da versão para a sua plataforma, confere com o checksums.txt da versão (e a assinatura cosign quando o cosign está no seu PATH) e o coloca no lugar do binário em execução. --check apenas informa se saiu uma versão mais nova.

archyl upgrade
archyl upgrade --check

Flags globais

Mensagens de status e spinners vão para a stderr, os resultados para a stdout, então os pipes só veem o resultado:

archyl where --json . | jq '.files[].elements[0].name'
archyl impact --json | jq '.impact.notify'

CI e scripts

Nenhum login necessário: crie uma chave de API em Profile → API Keys e defina-a no ambiente.

export ARCHYL_API_KEY=arch_…
export ARCHYL_PROJECT_ID=…       # or commit .archyl.json
archyl impact --json | jq '.impact.notify'
archyl dsl diff --exit-code      # fails when archyl.yaml and the model differ

Para guardar uma chave de API como credencial, passe-a por pipe para archyl login --with-token.

Autocompletar do shell

archyl completion install grava o script de autocompletar onde o seu shell o carrega: um diretório do fpath do zsh que pertença a você (ou ~/.zfunc), ~/.config/fish/completions ou ~/.local/share/bash-completion/completions. Execute de novo para atualizar o script. Ele só altera o arquivo de inicialização do shell quando é necessário (zsh sem um diretório fpath seu, PowerShell) e você concorda. archyl setup também oferece isso.

archyl completion install
archyl completion install --shell fish

Para gravar o script você mesmo:

archyl completion zsh > "${fpath[1]}/_archyl"
archyl completion bash > /etc/bash_completion.d/archyl
archyl completion fish > ~/.config/fish/completions/archyl.fish