Archyl CLI

archyl relie un dépôt à son architecture dans Archyl. Depuis votre terminal, vous pouvez trouver où se situe un fichier dans le modèle C4, voir ce que votre branche impacte et qui prévenir, briefer les agents de développement avant qu'ils ne touchent au code, et contrôler ce qu'ils écrivent.

$ 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 est open source sous licence MIT : github.com/archyl-com/cli.

Installation

# 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

Vous pouvez aussi télécharger un binaire depuis la page des releases. Les archives sont accompagnées de sommes de contrôle, signées avec cosign et livrées avec un SBOM.

Vérifiez l'installation avec archyl --version.

Premiers pas

À la racine de votre dépôt :

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 ouvre votre navigateur et vous connecte avec OAuth 2.1 et PKCE. La session est stockée dans le trousseau du système et se renouvelle d'elle-même ; vous ne vous reconnectez qu'après un mois sans utilisation.

archyl init écrit .archyl.json à la racine du dépôt pour que chaque commande archyl, ainsi que le hook Guard, sache à quel projet appartient ce code. Quand le remote du dépôt est connecté à un projet dans Archyl, ce projet est choisi pour vous ; sinon, vous le sélectionnez dans une liste. Committez le fichier : il ne contient aucun secret, et votre équipe comme votre CI partagent alors le même lien.

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

Lancez archyl init --force pour relier un dépôt à un autre projet.

Pas encore de projet ? archyl init --new en crée un sans quitter le terminal :

1. Il crée le projet, nommé d'après le dépôt (ou --name), dans l'équipe de votre choix (--team, par nom, slug ou ID).
2. Il connecte le dépôt à partir de son remote git. Pour un remote auto-hébergé, indiquez le fournisseur avec --provider : github_enterprise, gitlab_private ou gitea.
3. Il lance une découverte IA sur --branch (par défaut : la branche par défaut du remote) et en affiche la progression en direct.
4. Il ouvre la revue de ce que la découverte a trouvé, puis dessine le résultat sous forme de diagramme.
5. Il propose de connecter vos agents de développement.

archyl init seul propose la même chose quand aucun projet ne correspond au remote du dépôt. --no-discover se contente de créer et de lier le projet, --no-setup saute la dernière étape, et --yes prend toutes les valeurs par défaut sans rien demander, y compris l'approbation de ce que la découverte trouve.

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

La session

Lancez archyl seul pour ouvrir une session : une invite où vous posez vos questions sur l'architecture en langage naturel ou tapez des commandes, les réponses s'affichant dans votre terminal comme n'importe quelle autre sortie.

$ 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

• Le langage naturel va à l'assistant. Il répond à partir de l'architecture et, quand la réponse dépend de votre code ou de ce qui se passe en ce moment, il lance ici la commande correspondante — impact, check, brief, show, runs… — et affiche chacune (⏺) avant d'utiliser sa sortie. Les commandes en lecture seule s'exécutent en parallèle ; celles qui modifient quelque chose, comme approuver le plan d'une exécution ou enregistrer une mémoire, vous demandent d'abord votre accord (y/n).
• Les commandes / s'exécutent directement : /impact, /review, /brief <files>, /show <element>, /runs, /activity… Les vues plein écran (/map, /search, /run, /agents) prennent tout l'écran et vous le rendent quand vous les quittez. /help liste tout.
• @file joint le contenu du fichier à la question, avec son brief d'architecture : jusqu'à 400 lignes ou 24 Ko par fichier ; les fichiers binaires et les chemins hors du dépôt sont ignorés. #element oriente la question vers un élément. Les deux se complètent pendant la saisie.
• Enter envoie ; Shift+Enter (ou Alt+Enter, Ctrl+J) passe à la ligne, et le texte collé conserve ses retours à la ligne.
• ↑ ↓ parcourent votre historique, Tab complète, Esc interrompt une réponse, Ctrl-D quitte.

Les conversations sont conservées par dépôt : archyl -c (--continue) rouvre la dernière, /resume en choisit une plus ancienne dans une liste, et /new en démarre une nouvelle.

La première fois, la session vous indique ce qui manque : la connexion (/login), la liaison du dépôt (/init). L'assistant est disponible avec les offres qui incluent le chat IA ; les commandes / fonctionnent avec toutes les offres. Avec les modèles OpenAI et Anthropic, il appelle les commandes comme des outils natifs ; avec les autres fournisseurs, il passe par un protocole textuel, sans aucune différence pour vous.

doctor

archyl doctor vérifie tout ce dont la CLI dépend et explique comment corriger ce qui ne va pas : votre version, le profil, la connexion, la latence de l'API, le dépôt, le lien avec le projet, les agents connectés, le hook Guard et le hook pre-push. Il sort avec le code 1 quand quelque chose doit être corrigé.

Explorer l'architecture

activity

archyl activity rassemble dans un seul fil tout ce qui se passe sur le projet : éléments créés et modifiés (avec les champs modifiés), demandes de changement ouvertes et fusionnées, exécutions d'agents mises en file, en attente de quelqu'un et terminées, sessions de travail ouvertes et fermées. --follow le garde ouvert et affiche les événements à mesure qu'ils se produisent, comme tail -f ; ajoutez --notify pour recevoir une notification de bureau quand un agent vous attend.

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

map

archyl map ouvre un explorateur plein écran du modèle C4 : systèmes, conteneurs, composants et code dans une arborescence, avec pour chaque élément sa description, ses technologies, ses relations dans les deux sens et son rayon d'impact. Nommez un élément pour l'ouvrir directement dessus : archyl map "Payments".

d affiche le niveau courant sous forme de diagramme. Tab et Shift+Tab sélectionnent un élément, les flèches ou h j k l font défiler, Enter descend dans la sélection, Backspace ou u remonte, o l'ouvre dans l'application web, y copie son ID, et d ou Esc revient à l'arborescence.

diagram

archyl diagram dessine une vue C4 du modèle : le contexte système par défaut, les conteneurs d'un système quand vous nommez un système, les composants d'un conteneur quand vous nommez un conteneur. Les éléments hors de la vue apparaissent en pointillés, pour leurs relations avec elle.

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'

Dans Kitty, Ghostty, WezTerm et iTerm2, le diagramme est une image affichée dans le terminal. Dans les autres terminaux, et quand la sortie passe dans un pipe, il est dessiné avec des caractères de tracé de boîtes :

 ┌─────────────────┐   ┌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┐   ┌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┐
 │ ▣ 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
                          ▼     ▼

Dans tmux, les images demandent set -g allow-passthrough on et un terminal qui comprend le protocole d'images d'iTerm2. Définissez ARCHYL_IMAGES=0 pour toujours dessiner en texte.

search

archyl search cherche dans tout ce que vous pouvez voir dans Archyl : éléments, décisions, documentation, contrats d'API, canaux d'événements, flux et projets. Les résultats se mettent à jour pendant la saisie, avec un aperçu ; Entrée affiche l'élément choisi, ctrl+o l'ouvre dans l'application web. Dans un pipe ou avec --json, archyl search invoice affiche les résultats.

show

archyl show <element> affiche un élément avec son chemin, sa description, ses technologies, ses relations, les décisions liées et son rayon d'impact. archyl show ADR-12 affiche un enregistrement de décision. Les éléments sont trouvés par nom (exact, puis partiel) ou par ID.

open

archyl open ouvre le projet dans l'application web ; archyl open "Payments" sélectionne un élément sur le diagramme, archyl open ADR-12 déplie une décision. L'adresse de l'application web est l'hôte de l'API où api. est remplacé par app. ; si elle se trouve ailleurs, connectez-vous avec --app-url ou définissez ARCHYL_APP_URL.

ask

archyl ask "<question>" interroge l'assistant IA sur l'architecture du projet. La réponse est rendue en markdown au fil de sa rédaction. Tout ce que vous envoyez via un pipe est ajouté à la question :

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

L'assistant est disponible avec les offres qui incluent le chat IA.

adr

archyl adr liste les décisions du projet. archyl adr new en enregistre une : dans un terminal, un formulaire demande le titre, le statut, le contexte, la décision et les conséquences ; dans les scripts, passez-les en options.

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

discover

archyl discover lance une découverte IA sur les dépôts liés au projet et la suit, avec sa progression sur stderr. Ce qu'elle trouve n'entre pas tout de suite dans le modèle : cela attend une revue, qui s'ouvre d'elle-même quand la découverte se termine dans un terminal. Chaque dépôt lié compte pour une découverte IA dans le quota de votre offre.

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

archyl discover review liste les éléments proposés par les découvertes, regroupés par niveau C4, avec le détail de l'élément sélectionné sur le côté :

Hors d'un terminal, la commande affiche la liste ; --approve-all ou --reject-all règle tout d'un coup, et --json l'affiche pour les scripts.

Commandes d'architecture

where

archyl where <path>… situe des fichiers dans le modèle C4 : l'élément auquel chacun appartient, qui en est propriétaire et ce qui en dépend. Les répertoires sont développés en fichiers connus de git.

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

why

archyl why <file[:line]>, c'est git blame pour l'architecture. Pour un fichier, il montre les éléments auxquels il appartient, les décisions qui s'appliquent (les acceptées d'abord), qui en est responsable, ce que les agents et les personnes en ont retenu, les derniers changements du modèle sur ces éléments et les règles de conformité qui le visent. Avec un numéro de ligne, il retrouve aussi le commit qui a modifié la ligne en dernier et le relie aux décisions prises à la même période.

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

Dans un terminal, la réponse est mise en forme ; dans un pipe ou lancée par un agent, elle s'affiche en markdown compact.

impact

archyl impact compare votre copie de travail à une branche de base, situe chaque fichier modifié dans l'architecture et parcourt les relations pour trouver ce qui en dépend, avec les propriétaires à prévenir. La commande couvre les modifications commitées, indexées, non indexées et non suivies : vous pouvez donc la lancer avant même de committer.

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

Chaque fichier n'est compté que pour sa correspondance la plus précise : un fichier rattaché à un composant n'entraîne pas en plus tout son conteneur.

status

archyl status fait tenir le projet sur un seul écran : l'alignement entre le modèle et le code, votre branche et les agents qui travaillent sur le projet en ce moment.

context

archyl context affiche l'architecture du projet en markdown adapté aux agents de développement : systèmes, conteneurs, composants, relations, décisions et règles. Redirigez la sortie vers un pipe, ou écrivez-la dans le fichier que lit votre agent.

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

Agents de développement

La CLI est le moyen le plus rapide de placer un agent de développement sous l'Archyl Harness.

setup

archyl setup

archyl setup configure Claude Code, Cursor, VS Code et Codex pour utiliser le serveur MCP d'Archyl avec le profil d'outils coding, installe le hook Guard et apprend la CLI aux agents. Restreignez-la avec --agent (répétable : claude-code, cursor, vscode, codex) ; ignorez certaines parties avec --no-guard, --no-instructions ou --no-statusline.

archyl setup propose aussi d'installer la complétion du shell ; --no-completion s'en passe.

Les fichiers existants sont fusionnés, pas écrasés.

Par défaut (--transport cli), chaque agent lance archyl mcp, qui joint le serveur MCP d'Archyl avec la propre session de la CLI : connectez-vous une fois avec archyl login et tous les agents sont connectés, sans flux OAuth par agent ni clé dans un fichier. Avec --transport http, la configuration ne contient que l'URL du serveur et chaque agent se connecte via Archyl lui-même. Dans les deux cas, les fichiers du dépôt ne contiennent aucun secret et peuvent être committés sans risque.

mcp

archyl mcp sert les outils MCP d'Archyl à un agent via stdio, authentifié en votre nom. archyl setup le configure ; à la main, pour n'importe quel client MCP :

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

Il utilise le profil d'outils coding ; --tools full expose tous les outils.

Le bloc CLI est une courte section entre les marqueurs <!-- archyl:start --> et <!-- archyl:end --> qui indique à l'agent quelles commandes archyl lancer et quand : plan avant une modification non triviale, brief avant de modifier des fichiers, check et radar check avant de terminer, remember et recall pour ce que le code ne peut pas montrer. Relancer setup actualise le bloc et laisse le reste du fichier intact. Une ligne de statut déjà définie dans Claude Code n'est jamais remplacée.

plan

archyl plan "<task>" renvoie un plan d'implémentation ancré dans l'architecture : les étapes, l'élément que chacune touche, les décisions et règles à respecter, et ce que les sessions précédentes ont appris.

archyl plan "Add partial refunds to the payments flow"

brief

archyl brief <files> vous indique, à vous ou à un agent, ce qu'il faut savoir avant de modifier ces fichiers : les éléments auxquels ils appartiennent, ce que ces éléments utilisent et ce qui en dépend, les décisions qui s'appliquent à eux ou à leurs parents, leurs propriétaires, et ce dont Archyl se souvient à leur sujet. Sans chemin, la commande couvre tous les fichiers que modifie la branche.

Comme plan, recall et context, elle s'affiche de façon riche dans un terminal et produit un markdown compact quand un agent la lance depuis son shell, pour que l'agent lise une structure et non des codes d'échappement.

remember et recall

archyl remember enregistre un fait que le code ne peut pas montrer sur l'élément qu'il concerne ; chaque future session de travail sur cet élément en est informée dans son briefing. archyl recall retrouve ce dont Archyl se souvient, par sujet, élément ou type.

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 mémoire est attribuée à l'agent qui l'a écrite quand la CLI s'exécute dans Claude Code, Codex ou Cursor ; définissez ARCHYL_AGENT pour le nommer vous-même.

agents

archyl agents est une vue en direct des agents au travail sur le projet : quel agent, sur quelle tâche, sur quels éléments, avec quels fichiers modifiés. Les éléments réservés par plus d'un agent sont signalés, pour que deux agents n'entrent pas en collision sur le même code. Appuyez sur a pour inclure les sessions récemment terminées. Dans un pipe ou avec --json, la commande affiche les sessions une seule fois.

statusline

archyl statusline est une ligne de statut pour Claude Code : le projet, son score d'alignement, les agents au travail et si la session en cours s'exécute sous le harness. archyl setup l'installe ; à la main, dans .claude/settings.json :

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

runs

archyl runs liste les exécutions d'agents gérées du projet, en signalant celles qui vous attendent. archyl runs view en suit une en direct : les messages de l'agent, ses appels d'outils et les fichiers qu'il modifie dans le fil, son plan avec l'avancement de chaque étape, la durée, les tokens et le coût sur le côté. Et vous agissez dessus sans quitter le terminal :

Les mêmes actions existent sous forme de commandes, pour les scripts et pour les agents qui en supervisent d'autres. Les exécutions se désignent par les premiers caractères de leur ID, ou par 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

Les exécutions d'agents gérées sont disponibles avec les offres qui les incluent.

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 exécute n'importe quel agent dans une session de travail :

1. La commande ouvre une session pour la tâche. Archyl choisit les éléments, décisions et règles pertinents, pose des réservations (leases) sur les éléments pour que deux agents n'entrent pas en collision, et renvoie un briefing avec le verdict du gate.
2. Claude Code reçoit le briefing sous forme de prompt système ajouté. Chaque agent trouve ARCHYL_SESSION_ID et ARCHYL_BRIEFING_FILE dans son environnement.
3. Pendant que l'agent travaille, la session est maintenue active par un heartbeat toutes les 10 minutes, et le hook Guard lui attribue chaque fichier modifié.
4. Quand l'agent se termine, wrap indique les fichiers modifiés, ferme la session et propose d'ouvrir une demande de changement d'architecture en brouillon, pour qu'un humain examine comment le modèle doit se mettre à jour.

Si Archyl est injoignable, wrap affiche un avertissement et lance quand même l'agent.

fix

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

archyl fix met un agent de développement au travail sur les violations de règles de votre branche, sous le harness :

1. Il exécute le contrôle de conformité sur la branche, comme archyl check, et vous laisse choisir les violations à corriger.
2. Il ouvre une session de travail et transmet à l'agent chaque violation avec sa règle, sa sévérité, son emplacement et sa suggestion, ainsi que le brief des éléments auxquels appartiennent les fichiers et les décisions qui s'appliquent.
3. Quand l'agent se termine, il relance le contrôle et montre ce qui reste, par exemple « 3 violations → 0 ».

Rien n'est commité : relisez les modifications avec git diff. L'agent est le premier installé parmi Claude Code et Codex, ou celui que nomme --agent. Après --, n'importe quelle commande s'exécute à la place ; elle lit la tâche dans le fichier indiqué par ARCHYL_FIX_TASK_FILE.

lsp

archyl lsp est un serveur de langage (LSP) sur stdio, pour tout éditeur doté d'un client LSP. Il tourne à côté du serveur propre au langage :

Il utilise la session de la CLI (archyl login ou ARCHYL_API_KEY) et le .archyl.json du dépôt. Quand Archyl est injoignable, il écrit un seul avertissement dans le journal LSP de l'éditeur et n'affiche aucun diagnostic. Les diagnostics suivent les enregistrements, pas la frappe.

Neovim 0.11 et versions ultérieures :

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

Helix, dans languages.toml :

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

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

VS Code passe par l'extension Generic LSP Client, et Zed par une petite extension de développement. La configuration de chaque éditeur se trouve dans docs/lsp.md.

guard

archyl guard est le hook PreToolUse de Claude Code qu'installe archyl setup. Il lit le payload du hook sur stdin, exécute les règles de conformité du projet sur le fichier tel qu'il serait après la modification, et répond par une décision : les violations critiques bloquent la modification, les violations élevées déclenchent un avertissement. Réglez ARCHYL_GUARD_BLOCK sur high pour bloquer aussi les violations élevées, ou sur off pour ne faire qu'avertir.

Quand l'agent modifie un manifeste de dépendances (go.mod, package.json, pom.xml…), le Guard le vérifie aussi par rapport au radar technologique et bloque une dépendance que le radar place en Suspendre, avec l'alternative suggérée par sa note. Les dépendances en Suspendre déjà présentes ne bloquent pas la modification.

Le Guard échoue toujours en mode ouvert : sans identifiants, sans réseau ou face à un outil inconnu, il laisse passer la modification, si bien qu'il ne peut jamais casser votre workflow.

session

archyl session donne un accès bas niveau au protocole des sessions de travail, pour les scripts ou les agents qui le pilotent eux-mêmes. La plupart du temps, archyl wrap fait tout cela à votre place.

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 prend l'ID de session en argument ou depuis ARCHYL_SESSION_ID. Ne mettez dans --decision que des choix dignes d'un ADR : chacun devient une mémoire rejouée aux futures sessions portant sur les mêmes éléments. Tout ce qui est circonstanciel va dans --follow-up.

Contrôles et CI

Les mêmes commandes s'exécutent sur votre poste, dans un hook git et dans n'importe quelle CI. En CI, elles déduisent de l'environnement la branche de base, le commit et le format du rapport : GitHub Actions, GitLab CI, Bitbucket Pipelines et Azure Pipelines sont reconnus.

check

archyl check exécute les règles de conformité du projet sur chaque fichier qui diffère de la branche de base, et sort avec le code 1 quand une violation atteint --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

Avec --format auto, la sortie s'adapte à la CI :

--format sarif écrit un journal SARIF 2.1.0 pour le code scanning de GitHub, Azure DevOps ou n'importe quel tableau de bord de sécurité.

Les checkouts en CI sont souvent superficiels (shallow). Récupérez l'historique pour que la branche de base existe ; sinon, check s'arrête et vous le signale.

# 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 est le passage à lancer avant d'ouvrir une pull request. Il réunit les violations de règles qu'introduit votre branche, les éléments qu'elle touche avec ce qui en dépend, les personnes à prévenir et le score d'alignement actuel. Il sort avec le code 1 quand une violation atteint --fail-on (par défaut high).

Avec --comment, la revue est publiée sur la pull request ou la merge request, puis modifiée sur place à chaque push suivant, pour que la demande ne garde qu'un seul commentaire Archyl : le verdict, les violations avec leur fichier et leur ligne, les éléments touchés avec ce qui en dépend, et les propriétaires à mettre dans la boucle. GitHub demande GITHUB_TOKEN avec pull-requests: write ; GitLab demande GITLAB_TOKEN avec le scope api, car CI_JOB_TOKEN ne peut pas commenter.

Le commentaire inclut l'impact sous forme de flowchart Mermaid, que GitHub et GitLab affichent. archyl review --diagram affiche ce même flowchart en local, à coller dans une description ou un document.

Sur GitHub, le plus rapide est l'action Archyl, qui installe la CLI et exécute une commande :

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

Laissez command vide pour seulement installer la CLI et l'appeler dans les étapes suivantes.

hooks

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

archyl hooks install ajoute un hook git pre-push qui exécute archyl check --fail-open. Un push qui apporte une violation de niveau --fail-on ou supérieur (par défaut critical) est refusé ; si archyl n'est pas dans le PATH, hors ligne ou déconnecté, le push passe. Contournez-le ponctuellement avec git push --no-verify. Le hook respecte core.hooksPath, et un hook pre-push qu'archyl n'a pas écrit n'est jamais remplacé, sauf si vous passez --force.

drift

archyl drift montre dans quelle mesure le modèle documenté correspond au code : 100 signifie que chaque élément documenté a été retrouvé dans le code. --compute réanalyse d'abord le dépôt connecté et attend le résultat ; --fail-under en fait un quality gate.

archyl drift --compute --fail-under 80

dsl

archyl dsl garde un fichier d'architecture-as-code et le modèle du projet synchronisés. Chaque sous-commande travaille sur archyl.yaml à la racine du dépôt, sauf si vous passez --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 exporte le modèle (éléments, relations, technologies, décisions, documentation, contrats, environnements et releases). La commande demande avant d'écraser le fichier, sauf si vous passez --yes ; --file - l'affiche à la place.
• diff est un essai à blanc côté serveur, sans rien écrire : les éléments et relations qu'un push ajouterait (+) ou modifierait (~), regroupés par niveau C4, et ceux que seul Archyl possède (−). --exit-code sort avec le code 1 dès qu'il y a une différence.
• push crée les nouveaux éléments et relations et met à jour les existants, rapprochés par nom. Il ne supprime jamais rien : ce que seul Archyl possède est conservé. Dans un terminal, il affiche le diff et demande d'abord ; --yes saute la question.

$ 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] équivaut à archyl dsl push.

release

archyl release enregistre une release, pour corréler les changements d'architecture avec ce qui a été livré et alimenter les métriques DORA. La version est par défaut le tag en cours de build dans la CI, puis le tag sur HEAD ; le lien pointe par défaut vers l'exécution de la CI.

archyl release v2.4.0 --environment production

radar

archyl radar affiche les technologies de l'organisation par anneau de gouvernance (Adopter, Essayer, Évaluer, Suspendre), avec la part de l'architecture qui utilise chacune. archyl radar check lit les manifestes de dépendances du dépôt, rapproche chaque dépendance du radar et sort avec le code 1 quand l'une d'elles est en Suspendre, avec la même sortie 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 liste les demandes de changement d'architecture du projet — souvent ouvertes par des agents à la fin d'une session de travail — et vous permet de les examiner sans quitter le 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

Comptes et profils

Un profil correspond à un hôte Archyl et une organisation, avec son propre identifiant. Créez-en un en vous connectant avec un nom ; c'est aussi ainsi que vous vous connectez à une instance Archyl auto-hébergée :

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

Prompt du shell

archyl prompt affiche en quelques caractères le score d'alignement du projet et les agents actifs, pour le prompt de votre shell. Il n'attend jamais le réseau : il affiche le dernier état connu et le rafraîchit en arrière-plan toutes les dix minutes. Avec Starship :

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

Cache local

map, show, open, la complétion des éléments et les suggestions # de la session répondent à partir d'une copie locale du modèle, et démarrent donc instantanément. Il existe une copie par profil, hôte, organisation, identité et projet, dans votre répertoire de cache utilisateur, lisible par vous seul. Une copie de moins de 30 secondes est utilisée sans appeler l'API ; une copie plus ancienne est rafraîchie, et quand l'API met plus de 1,5 seconde à répondre, la commande répond à partir de la copie et le signale sur stderr. Les commandes qui modifient le modèle, comme dsl push ou l'approbation de découvertes, invalident la copie.

Ignorez le cache pour une commande avec --no-cache, ou partout avec ARCHYL_NO_CACHE=1. archyl login et archyl logout vident les copies du profil ; archyl cache clear le fait à la main.

Mises à jour

Quand une nouvelle release est disponible, la CLI le signale une fois la commande terminée. La vérification s'exécute en arrière-plan au plus une fois par jour, jamais en CI ni dans les scripts ; définissez ARCHYL_NO_UPDATE_NOTIFIER pour la désactiver.

archyl upgrade met la CLI à jour de la façon dont vous l'avez installée : brew upgrade pour Homebrew, la commande go install pour une compilation depuis les sources, et sinon sur place : il télécharge l'archive de la release pour votre plateforme, la vérifie avec le checksums.txt de la release (et sa signature cosign quand cosign est dans votre PATH), puis remplace le binaire en cours d'exécution. --check indique seulement si une release plus récente est sortie.

archyl upgrade
archyl upgrade --check

Options globales

Les messages d'état et les spinners vont sur stderr, les résultats sur stdout : les pipes ne voient donc jamais que le résultat.

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

CI et scripts

Aucune connexion nécessaire : créez une clé API dans Profil → Clés API et définissez-la dans l'environnement.

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

Pour stocker plutôt une clé API comme identifiant, passez-la à archyl login --with-token via un pipe.

Complétion du shell

archyl completion install écrit le script de complétion là où votre shell le charge : un répertoire du fpath de zsh qui vous appartient (ou ~/.zfunc), ~/.config/fish/completions ou ~/.local/share/bash-completion/completions. Relancez-le pour mettre le script à jour. Il ne modifie le fichier de démarrage de votre shell que si c'est nécessaire (zsh sans répertoire fpath à vous, PowerShell) et que vous l'acceptez. archyl setup le propose aussi.

archyl completion install
archyl completion install --shell fish

Pour écrire le script vous-même :

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