Archyl CLI

archyl conecta un repositorio con su arquitectura en Archyl. Desde tu terminal puedes averiguar dónde se sitúa un archivo en el modelo C4, ver a qué afecta tu rama y a quién avisar, dar un briefing a los agentes de codificación antes de que toquen el código y vigilar lo que escriben.

$ 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

La CLI es open source bajo la licencia MIT: github.com/archyl-com/cli.

Instalación

# 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

También puedes descargar un binario desde la página de releases. Los archivos comprimidos incluyen sumas de verificación, están firmados con cosign y se distribuyen con un SBOM.

Comprueba la instalación con archyl --version.

Primeros pasos

Desde la raíz de tu repositorio:

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 tu navegador e inicia sesión con OAuth 2.1 y PKCE. La sesión se guarda en el llavero del sistema operativo y se renueva sola; solo vuelves a iniciar sesión tras un mes sin usarla.

archyl init escribe .archyl.json en la raíz del repositorio para que cada comando archyl, y el hook Guard, sepan a qué proyecto pertenece este código. Cuando el remoto del repositorio está conectado a un proyecto en Archyl, ese proyecto se elige por ti; si no, lo eliges de una lista. Haz commit del archivo: no contiene ningún secreto, y así tu equipo y tu CI comparten el mismo vínculo.

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

Ejecuta archyl init --force para vincular un repositorio a otro proyecto.

¿Todavía no tienes proyecto? archyl init --new crea uno sin salir del terminal:

1. Crea el proyecto, con el nombre del repositorio (o --name), en el equipo que elijas (--team, por nombre, slug o ID).
2. Conecta el repositorio a partir de su remote de git. Para un remote autoalojado, indica el proveedor con --provider: github_enterprise, gitlab_private o gitea.
3. Lanza un descubrimiento con IA sobre --branch (por defecto: la rama por defecto del remote) y muestra su progreso en directo.
4. Abre la revisión de lo que ha encontrado el descubrimiento y luego dibuja el resultado como un diagrama.
5. Ofrece conectar tus agentes de programación.

archyl init a secas ofrece lo mismo cuando ningún proyecto coincide con el remote del repositorio. --no-discover solo crea y vincula el proyecto, --no-setup se salta el último paso y --yes acepta todos los valores por defecto sin preguntar, incluida la aprobación de lo que encuentre el descubrimiento.

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

La sesión

Ejecuta archyl sin nada más para abrir una sesión: un prompt donde preguntas sobre la arquitectura en lenguaje natural o escribes comandos, y las respuestas aparecen en tu terminal como cualquier otra salida.

$ 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

• El lenguaje natural va al asistente. Responde a partir de la arquitectura y, cuando la respuesta depende de tu código o de lo que está pasando ahora mismo, ejecuta aquí el comando correspondiente — impact, check, brief, show, runs… — y muestra cada uno (⏺) antes de usar su salida. Los comandos de solo lectura se ejecutan en paralelo; los que cambian algo, como aprobar el plan de una ejecución o registrar una memoria, te piden confirmación antes (y/n).
• Los comandos / se ejecutan directamente: /impact, /review, /brief <files>, /show <element>, /runs, /activity… Las vistas a pantalla completa (/map, /search, /run, /agents) ocupan la pantalla y te la devuelven cuando sales de ellas. /help lo lista todo.
• @file adjunta a la pregunta el contenido del archivo, con su briefing de arquitectura: hasta 400 líneas o 24 KB por archivo; los archivos binarios y las rutas fuera del repositorio se omiten. #element dirige la pregunta a un elemento. Ambos se autocompletan mientras escribes.
• Enter envía; Shift+Enter (o Alt+Enter, Ctrl+J) empieza una nueva línea, y el texto pegado conserva sus saltos de línea.
• ↑ ↓ recorren tu historial, Tab autocompleta, Esc detiene una respuesta, Ctrl-D sale.

Las conversaciones se guardan por repositorio: archyl -c (--continue) reabre la última, /resume elige una anterior de una lista y /new empieza una nueva.

La primera vez, la sesión te indica lo que falta: iniciar sesión (/login), vincular el repositorio (/init). El asistente está disponible en los planes que incluyen el chat de IA; los comandos / funcionan en todos los planes. Con los modelos de OpenAI y Anthropic llama a los comandos como herramientas nativas; con otros proveedores pasa por un protocolo de texto, y no notas ninguna diferencia.

doctor

archyl doctor comprueba todo aquello de lo que depende la CLI y te dice cómo arreglar lo que no está bien: tu versión, el perfil, el inicio de sesión, la latencia de la API, el repositorio, el vínculo con el proyecto, los agentes conectados, el hook Guard y el hook pre-push. Termina con código 1 cuando hay algo que arreglar.

Explorar la arquitectura

activity

archyl activity reúne en un solo feed todo lo que pasa en el proyecto: elementos creados y modificados (con los campos que cambiaron), solicitudes de cambio abiertas y fusionadas, ejecuciones de agentes en cola, esperando a alguien y terminadas, sesiones de trabajo abiertas y cerradas. --follow lo mantiene abierto e imprime los eventos a medida que ocurren, como tail -f; añade --notify para recibir una notificación de escritorio cuando un agente te espera.

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

map

archyl map abre un explorador a pantalla completa del modelo C4: sistemas, contenedores, componentes y código en un árbol, con la descripción de cada elemento, sus tecnologías, sus relaciones en ambos sentidos y su radio de impacto. Indica un elemento para abrirlo directamente en él: archyl map "Payments".

d muestra el nivel actual como diagrama. Tab y Shift+Tab seleccionan un elemento, las flechas o h j k l desplazan la vista, Enter baja a la selección, Backspace o u vuelve a subir, o la abre en la aplicación web, y copia su ID, y d o Esc vuelve al árbol.

diagram

archyl diagram dibuja una vista C4 del modelo: el contexto del sistema por defecto, los contenedores de un sistema cuando nombras un sistema, los componentes de un contenedor cuando nombras un contenedor. Los elementos fuera de la vista aparecen con línea discontinua, por sus relaciones con ella.

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'

En Kitty, Ghostty, WezTerm e iTerm2 el diagrama es una imagen dentro del terminal. En otros terminales, y cuando la salida va a un pipe, se dibuja con caracteres de recuadro:

 ┌─────────────────┐   ┌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┐   ┌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┐
 │ ▣ 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 de tmux, las imágenes necesitan set -g allow-passthrough on y un terminal que entienda el protocolo de imágenes de iTerm2. Define ARCHYL_IMAGES=0 para dibujar siempre en texto.

search

archyl search busca en todo lo que puedes ver en Archyl: elementos, decisiones, documentación, contratos de API, canales de eventos, flujos y proyectos. Los resultados se actualizan mientras escribes, con una vista previa; Enter muestra el resultado elegido y ctrl+o lo abre en la aplicación web. Por un pipe o con --json, archyl search invoice imprime los resultados.

show

archyl show <element> imprime un elemento con su ruta, descripción, tecnologías, relaciones, decisiones vinculadas y radio de impacto. archyl show ADR-12 muestra un registro de decisión. Los elementos se buscan por nombre (exacto y, después, parcial) o por ID.

open

archyl open abre el proyecto en la aplicación web; archyl open "Payments" selecciona un elemento en el diagrama y archyl open ADR-12 despliega una decisión. La dirección de la aplicación web es el host de la API con api. sustituido por app.; si está en otro sitio, inicia sesión con --app-url o define ARCHYL_APP_URL.

ask

archyl ask "<question>" hace una pregunta al asistente de IA sobre la arquitectura del proyecto. La respuesta se muestra como markdown mientras se escribe. Todo lo que le pases por un pipe se añade a la pregunta:

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

El asistente está disponible en los planes que incluyen el chat de IA.

adr

archyl adr lista las decisiones del proyecto. archyl adr new registra una: en un terminal, un formulario te pide el título, el estado, el contexto, la decisión y las consecuencias; en scripts, pásalos 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 lanza un descubrimiento con IA sobre los repositorios vinculados al proyecto y lo sigue, con su progreso en stderr. Lo que encuentra no se incorpora al modelo de inmediato: queda pendiente de revisión, que se abre sola cuando el descubrimiento termina en un terminal. Cada repositorio vinculado cuenta como un descubrimiento con IA en la cuota de tu plan.

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

archyl discover review lista los elementos que proponen los descubrimientos, agrupados por nivel C4, con los detalles del elemento seleccionado al lado:

Fuera de un terminal imprime la lista; --approve-all o --reject-all lo resuelve todo de una vez, y --json la imprime para scripts.

Comandos de arquitectura

where

archyl where <path>… ubica archivos en el modelo C4: el elemento al que pertenece cada uno, quién es su responsable y qué depende de él. Los directorios se expanden a los archivos que git conoce.

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

why

archyl why <file[:line]> es git blame para la arquitectura. Para un archivo, muestra los elementos a los que pertenece, las decisiones que se aplican (primero las aceptadas), quién es responsable, lo que agentes y personas recordaron sobre él, los últimos cambios del modelo en esos elementos y las reglas de conformidad que lo afectan. Con un número de línea, encuentra además el commit que cambió la línea por última vez y lo relaciona con las decisiones tomadas en las mismas fechas.

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

En un terminal la respuesta se muestra con formato; en un pipe o ejecutado por un agente, imprime markdown compacto.

impact

archyl impact compara tu árbol de trabajo con una rama base, ubica cada archivo modificado en la arquitectura y recorre las relaciones para encontrar qué depende de él, junto con los responsables a quienes avisar. Abarca los cambios confirmados, preparados, sin preparar y sin seguimiento, así que puedes ejecutarlo incluso antes de hacer commit.

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

Cada archivo cuenta solo para su coincidencia más específica: un archivo asignado a un componente no arrastra además todo su contenedor.

status

archyl status resume el proyecto en una sola pantalla: la alineación entre el modelo y el código, tu rama y los agentes que trabajan en el proyecto en este momento.

context

archyl context imprime la arquitectura del proyecto en markdown pensado para agentes de codificación: sistemas, contenedores, componentes, relaciones, decisiones y reglas. Pásalo por un pipe o escríbelo en el archivo que lee tu agente.

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

Agentes de codificación

La CLI es la forma más rápida de poner un agente de codificación bajo el Archyl Harness.

setup

archyl setup

archyl setup configura Claude Code, Cursor, VS Code y Codex para usar el servidor MCP de Archyl con el perfil de herramientas coding, instala el hook Guard y enseña la CLI a los agentes. Restríngelo con --agent (repetible: claude-code, cursor, vscode, codex); omite partes con --no-guard, --no-instructions o --no-statusline.

archyl setup también ofrece instalar el autocompletado del shell; --no-completion lo omite.

Los archivos existentes se fusionan, no se sobrescriben.

Por defecto (--transport cli), cada agente inicia archyl mcp, que llega al servidor MCP de Archyl con la propia sesión de la CLI: inicia sesión una vez con archyl login y todos los agentes quedan conectados, sin un flujo OAuth por agente ni claves en un archivo. Con --transport http, la configuración solo contiene la URL del servidor y cada agente inicia sesión a través del propio Archyl. En ambos casos, los archivos del repositorio no contienen ningún secreto y puedes hacer commit de ellos sin riesgo.

mcp

archyl mcp sirve las herramientas MCP de Archyl a un agente por stdio, autenticado como tú. archyl setup lo configura; a mano, para cualquier cliente MCP:

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

Usa el perfil de herramientas coding; --tools full expone todas las herramientas.

El bloque de la CLI es una sección breve entre los marcadores <!-- archyl:start --> y <!-- archyl:end --> que indica al agente qué comandos archyl ejecutar y cuándo: plan antes de un cambio no trivial, brief antes de editar archivos, check y radar check antes de terminar, remember y recall para lo que el código no puede mostrar. Volver a ejecutar setup actualiza el bloque y deja intacto el resto del archivo. Una línea de estado ya configurada en Claude Code nunca se reemplaza.

plan

archyl plan "<task>" devuelve un plan de implementación basado en la arquitectura: los pasos, el elemento que toca cada uno, las decisiones y reglas que hay que respetar, y lo que aprendieron las sesiones anteriores.

archyl plan "Add partial refunds to the payments flow"

brief

archyl brief <files> te dice, a ti o a un agente, lo que hay que saber antes de editar esos archivos: los elementos a los que pertenecen, lo que usan esos elementos y lo que depende de ellos, las decisiones que se aplican a ellos o a sus padres, sus responsables y lo que Archyl recuerda sobre ellos. Sin rutas, abarca todos los archivos que modifica la rama.

Como plan, recall y context, se muestra con formato en un terminal e imprime markdown compacto cuando un agente lo ejecuta desde su shell, de modo que el agente lee estructura, no códigos de escape.

remember y recall

archyl remember registra un hecho que el código no puede mostrar en el elemento al que se refiere; cada futura sesión de trabajo sobre ese elemento recibe ese dato en su briefing. archyl recall encuentra lo que Archyl recuerda, por tema, elemento o 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

La memoria se atribuye al agente que la escribió cuando la CLI se ejecuta dentro de Claude Code, Codex o Cursor; define ARCHYL_AGENT para indicar el nombre tú mismo.

agents

archyl agents es una vista en directo de los agentes que trabajan en el proyecto: qué agente, en qué tarea, sobre qué elementos y con qué archivos modificados. Los elementos reservados por más de un agente se señalan para que dos agentes no choquen en el mismo código. Pulsa a para incluir las sesiones terminadas recientemente. Por un pipe o con --json, imprime las sesiones una sola vez.

statusline

archyl statusline es una línea de estado para Claude Code: el proyecto, su puntuación de alineación, los agentes trabajando y si la sesión actual se ejecuta bajo el harness. archyl setup la instala; a mano, en .claude/settings.json:

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

runs

archyl runs lista las ejecuciones de agentes gestionadas del proyecto y señala las que te esperan. archyl runs view sigue una en directo: los mensajes del agente, sus llamadas a herramientas y los archivos que modifica en el feed, su plan con el progreso de cada paso, y el tiempo, los tokens y el coste a un lado. Y actúas sobre ella sin salir del terminal:

Las mismas acciones existen como comandos, para scripts y para agentes que supervisan a otros agentes. Las ejecuciones se identifican por los primeros caracteres de su ID, o con 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

Las ejecuciones de agentes gestionadas están disponibles en los planes que las incluyen.

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 ejecuta cualquier agente dentro de una sesión de trabajo:

1. Abre una sesión para la tarea. Archyl elige los elementos, decisiones y reglas relevantes, toma reservas (leases) sobre los elementos para que dos agentes no choquen, y devuelve un briefing con el veredicto del gate.
2. Claude Code recibe el briefing como un prompt de sistema añadido. Todo agente encuentra ARCHYL_SESSION_ID y ARCHYL_BRIEFING_FILE en su entorno.
3. Mientras el agente trabaja, la sesión se mantiene activa con un heartbeat cada 10 minutos, y el hook Guard le atribuye cada archivo editado.
4. Cuando el agente termina, wrap informa de los archivos modificados, cierra la sesión y ofrece abrir un borrador de solicitud de cambio de arquitectura para que una persona revise cómo debe ponerse al día el modelo.

Si Archyl no está accesible, wrap muestra un aviso y ejecuta el agente de todos modos.

fix

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

archyl fix pone a un agente de programación a trabajar en las violaciones de reglas de tu rama, bajo el harness:

1. Ejecuta la comprobación de conformidad sobre la rama, como archyl check, y te deja elegir las violaciones que corregir.
2. Abre una sesión de trabajo y entrega al agente cada violación con su regla, severidad, ubicación y sugerencia, junto con el brief de los elementos a los que pertenecen los archivos y las decisiones que se aplican.
3. Cuando el agente termina, vuelve a ejecutar la comprobación y muestra lo que queda, por ejemplo «3 violations → 0».

No se hace ningún commit: revisa los cambios con git diff. El agente es el primero instalado entre Claude Code y Codex, o el que indique --agent. Después de -- se ejecuta cualquier comando en su lugar; lee la tarea del archivo que indica ARCHYL_FIX_TASK_FILE.

lsp

archyl lsp es un servidor de lenguaje (LSP) sobre stdio para cualquier editor con cliente LSP. Funciona junto al servidor propio del lenguaje:

Usa la sesión de la CLI (archyl login o ARCHYL_API_KEY) y el .archyl.json del repositorio. Cuando no puede contactar con Archyl, escribe un único aviso en el log LSP del editor y no muestra diagnósticos. Los diagnósticos siguen a los guardados, no a las pulsaciones.

Neovim 0.11 y posteriores:

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

Helix, en languages.toml:

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

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

VS Code pasa por la extensión Generic LSP Client, y Zed por una pequeña extensión de desarrollo. La configuración de cada editor está en docs/lsp.md.

guard

archyl guard es el hook PreToolUse de Claude Code que instala archyl setup. Lee el payload del hook por stdin, ejecuta las reglas de conformidad del proyecto sobre el archivo tal como quedaría tras la edición y responde con una decisión: las violaciones críticas bloquean la edición, las altas generan un aviso. Pon ARCHYL_GUARD_BLOCK en high para bloquear también las violaciones altas, o en off para solo avisar.

Cuando el agente edita un manifiesto de dependencias (go.mod, package.json, pom.xml…), el Guard también lo comprueba con el radar tecnológico y bloquea una dependencia que el radar tiene En espera, junto con la alternativa que sugiere su nota. Las dependencias En espera que ya estaban no bloquean la edición.

El Guard siempre falla en abierto: sin credenciales, sin red o ante una herramienta desconocida deja pasar la edición, de modo que nunca puede romper tu flujo de trabajo.

session

archyl session da acceso de bajo nivel al protocolo de sesiones de trabajo, para scripts o agentes que lo manejan por sí mismos. La mayoría de las veces, archyl wrap hace todo esto por ti.

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 toma el ID de sesión como argumento o desde ARCHYL_SESSION_ID. Pon en --decision solo decisiones dignas de un ADR: cada una se convierte en memoria que se reproduce en futuras sesiones sobre los mismos elementos. Todo lo circunstancial va en --follow-up.

Comprobaciones y CI

Los mismos comandos se ejecutan en tu portátil, en un hook de git y en cualquier CI. En CI toman del entorno la rama base, el commit y el formato del informe: se reconocen GitHub Actions, GitLab CI, Bitbucket Pipelines y Azure Pipelines.

check

archyl check ejecuta las reglas de conformidad del proyecto sobre cada archivo que difiere de la rama base y termina con código 1 cuando una violación alcanza --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

Con --format auto, la salida se adapta a la CI:

--format sarif escribe un registro SARIF 2.1.0 para el code scanning de GitHub, Azure DevOps o cualquier panel de seguridad.

Los checkouts de CI suelen ser superficiales (shallow). Descarga el historial para que exista la rama base; de lo contrario, check se detiene y te lo indica.

# 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 es la pasada que conviene ejecutar antes de abrir una pull request. Reúne las violaciones de reglas que introduce tu rama, los elementos que toca junto con lo que depende de ellos, a quién avisar y la puntuación de alineación actual. Termina con código 1 cuando una violación alcanza --fail-on (por defecto high).

Con --comment, la revisión se publica en la pull o merge request y se edita en el mismo sitio en cada push posterior, de modo que la solicitud conserva un único comentario de Archyl: el veredicto, las violaciones con su archivo y su línea, los elementos tocados junto con lo que depende de ellos y los responsables a quienes implicar. GitHub necesita GITHUB_TOKEN con pull-requests: write; GitLab necesita GITLAB_TOKEN con el scope api, ya que CI_JOB_TOKEN no puede comentar.

El comentario incluye el impacto como un flowchart de Mermaid, que GitHub y GitLab renderizan. archyl review --diagram imprime ese mismo flowchart en local, para pegarlo en una descripción o un documento.

La forma más rápida de configurarlo en GitHub es la action de Archyl, que instala la CLI y ejecuta un 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

Deja command vacío para solo instalar la CLI y llamarla en pasos posteriores.

hooks

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

archyl hooks install añade un hook pre-push de git que ejecuta archyl check --fail-open. Se rechaza todo push que traiga una violación igual o superior a --fail-on (por defecto critical); si archyl no está en el PATH, no hay conexión o no has iniciado sesión, el push pasa. Sáltalo una vez con git push --no-verify. El hook respeta core.hooksPath, y un hook pre-push que no haya escrito archyl nunca se reemplaza, salvo que pases --force.

drift

archyl drift muestra hasta qué punto el modelo documentado coincide con el código: 100 significa que cada elemento documentado se encontró en el código. --compute vuelve a analizar primero el repositorio conectado y espera el resultado; --fail-under lo convierte en un quality gate.

archyl drift --compute --fail-under 80

dsl

archyl dsl mantiene sincronizados un archivo de arquitectura como código y el modelo del proyecto. Todos los subcomandos trabajan sobre archyl.yaml en la raíz del repositorio, salvo que pases --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 el modelo (elementos, relaciones, tecnologías, decisiones, documentación, contratos, entornos y releases). Pregunta antes de sobrescribir el archivo, salvo que pases --yes; --file - lo imprime en su lugar.
• diff es una ejecución en seco en el servidor, sin escribir nada: los elementos y relaciones que un push añadiría (+) o cambiaría (~), agrupados por nivel C4, y los que solo tiene Archyl (−). --exit-code termina con código 1 cuando hay alguna diferencia.
• push crea los elementos y relaciones nuevos y actualiza los existentes, emparejados por nombre. Nunca borra nada: lo que solo tiene Archyl se queda. En un terminal muestra el diff y pregunta antes; --yes omite la pregunta.

$ 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] equivale a archyl dsl push.

release

archyl release registra una release, para correlacionar los cambios de arquitectura con lo que se ha entregado y alimentar las métricas DORA. La versión es por defecto el tag que se está construyendo en CI y, si no, el tag de HEAD; el enlace apunta por defecto a la ejecución de CI.

archyl release v2.4.0 --environment production

radar

archyl radar muestra las tecnologías de la organización por anillo de gobernanza (Adoptar, Probar, Evaluar, En espera) y cuánta parte de la arquitectura usa cada una. archyl radar check lee los manifiestos de dependencias del repositorio, empareja cada dependencia con el radar y termina con código 1 cuando alguna está En espera, con la misma salida 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 las solicitudes de cambio de arquitectura del proyecto —a menudo abiertas por agentes al final de una sesión de trabajo— y te permite revisarlas sin salir del 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

Cuentas y perfiles

Un perfil es un host de Archyl y una organización con su propia credencial. Crea uno iniciando sesión con un nombre, que es también la forma de conectarte a un Archyl autoalojado:

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

Prompt del shell

archyl prompt imprime en pocos caracteres la puntuación de alineación del proyecto y los agentes activos, para el prompt de tu shell. Nunca espera a la red: imprime el último estado conocido y lo actualiza en segundo plano cada diez minutos. Con Starship:

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

Copia local del modelo

map, show, open, el autocompletado de elementos y las sugerencias # de la sesión responden a partir de una copia local del modelo, así que arrancan al instante. Hay una copia por perfil, host, organización, identidad y proyecto, en tu directorio de caché de usuario, legible solo por ti. Una copia de menos de 30 segundos se usa sin llamar a la API; una más antigua se actualiza, y cuando la API tarda más de 1,5 segundos el comando responde a partir de la copia y lo indica en stderr. Los comandos que cambian el modelo, como dsl push o aprobar descubrimientos, descartan la copia.

Omite la caché en un solo comando con --no-cache, o en todas partes con ARCHYL_NO_CACHE=1. archyl login y archyl logout borran las copias del perfil; archyl cache clear lo hace a mano.

Actualizaciones

Cuando sale una versión más reciente, la CLI lo indica una vez que ha terminado un comando. La comprobación se ejecuta en segundo plano como mucho una vez al día, nunca en CI ni en scripts; define ARCHYL_NO_UPDATE_NOTIFIER para desactivarla.

archyl upgrade actualiza la CLI de la misma forma en que la instalaste: brew upgrade para Homebrew, el comando go install para una compilación desde el código fuente y, en los demás casos, en el sitio: descarga el archivo de la versión para tu plataforma, lo verifica con el checksums.txt de la versión (y su firma cosign cuando cosign está en tu PATH) y lo pone en lugar del binario en ejecución. --check solo indica si ha salido una versión más reciente.

archyl upgrade
archyl upgrade --check

Flags globales

Los mensajes de estado y los spinners van a stderr y los resultados a stdout, así que los pipes solo ven el resultado:

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

CI y scripts

No hace falta iniciar sesión: crea una clave API en Perfil → Claves API y defínela en el entorno.

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 una clave API como credencial, pásala por un pipe a archyl login --with-token.

Autocompletado del shell

archyl completion install escribe el script de autocompletado donde tu shell lo carga: un directorio del fpath de zsh que sea tuyo (o ~/.zfunc), ~/.config/fish/completions o ~/.local/share/bash-completion/completions. Vuelve a ejecutarlo para actualizar el script. Solo cambia el archivo de inicio de tu shell cuando hace falta (zsh sin un directorio fpath tuyo, PowerShell) y tú lo aceptas. archyl setup también lo ofrece.

archyl completion install
archyl completion install --shell fish

Para escribir el script tú mismo:

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