Archyl CLI

archyl verbindet ein Repository mit seiner Architektur in Archyl. Aus Ihrem Terminal heraus finden Sie, wo eine Datei im C4-Modell liegt, sehen, was Ihr Branch betrifft und wen Sie informieren sollten, briefen Coding-Agenten, bevor sie Code anfassen, und überwachen, was sie schreiben.

$ 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

Die CLI ist Open Source unter der MIT-Lizenz: 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

Sie können auch eine Binärdatei von der Releases-Seite herunterladen. Die Archive haben Prüfsummen, sind mit cosign signiert und werden mit einer SBOM ausgeliefert.

Prüfen Sie die Installation mit archyl --version.

Erste Schritte

Im Wurzelverzeichnis Ihres Repositorys:

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 öffnet Ihren Browser und meldet Sie mit OAuth 2.1 und PKCE an. Die Sitzung wird im Schlüsselbund des Betriebssystems gespeichert und erneuert sich selbst; neu anmelden müssen Sie sich erst nach einem Monat ohne Nutzung.

archyl init schreibt .archyl.json in das Wurzelverzeichnis des Repositorys, damit jeder archyl-Befehl und der Guard-Hook wissen, zu welchem Projekt dieser Code gehört. Ist das Remote des Repositorys mit einem Projekt in Archyl verbunden, wird dieses Projekt automatisch gewählt; andernfalls wählen Sie es aus einer Liste. Committen Sie die Datei: Sie enthält keine Geheimnisse, und Ihr Team und Ihre CI teilen dann dieselbe Verknüpfung.

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

Mit archyl init --force verknüpfen Sie ein Repository mit einem anderen Projekt.

Noch kein Projekt? archyl init --new legt eins an, ohne dass Sie das Terminal verlassen:

1. Es erstellt das Projekt, benannt nach dem Repository (oder --name), im Team Ihrer Wahl (--team, per Name, Slug oder ID).
2. Es verbindet das Repository über sein Git-Remote. Bei einem selbst gehosteten Remote geben Sie den Anbieter mit --provider an: github_enterprise, gitlab_private oder gitea.
3. Es startet eine KI-Entdeckung auf --branch (Standard: der Standard-Branch des Remotes) und zeigt ihren Fortschritt live.
4. Es öffnet das Review dessen, was die Entdeckung gefunden hat, und zeichnet das Ergebnis dann als Diagramm.
5. Es bietet an, Ihre Coding-Agenten zu verbinden.

Ein einfaches archyl init bietet dasselbe an, wenn kein Projekt zum Remote des Repositorys passt. --no-discover erstellt und verknüpft nur das Projekt, --no-setup überspringt den letzten Schritt, und --yes übernimmt alle Standardwerte ohne Rückfrage, einschließlich der Freigabe dessen, was die Entdeckung findet.

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

Die Session

Führen Sie archyl ohne Argumente aus, um eine Session zu öffnen: eine Eingabeaufforderung, in der Sie in natürlicher Sprache Fragen zur Architektur stellen oder Befehle eingeben, wobei die Antworten wie jede andere Ausgabe in Ihrem Terminal erscheinen.

$ 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

• Natürliche Sprache geht an den Assistenten. Er antwortet auf Grundlage der Architektur, und wenn die Antwort von Ihrem Code oder vom aktuellen Geschehen abhängt, führt er hier den passenden Befehl aus — impact, check, brief, show, runs… — und zeigt jeden davon (⏺), bevor er dessen Ausgabe verwendet. Lesende Befehle laufen parallel; Befehle, die etwas ändern, etwa den Plan eines Runs freigeben oder eine Erinnerung speichern, fragen Sie vorher (y/n).
• /-Befehle werden direkt ausgeführt: /impact, /review, /brief <files>, /show <element>, /runs, /activity… Vollbildansichten (/map, /search, /run, /agents) übernehmen den Bildschirm und geben ihn zurück, wenn Sie sie verlassen. /help listet alles auf.
• @file hängt den Inhalt der Datei mit ihrem Architektur-Briefing an die Frage an: bis zu 400 Zeilen oder 24 KB pro Datei; Binärdateien und Pfade außerhalb des Repositorys werden übersprungen. #element richtet die Frage auf ein Element. Beide werden während der Eingabe vervollständigt.
• Enter sendet; Shift+Enter (oder Alt+Enter, Ctrl+J) beginnt eine neue Zeile, und eingefügter Text behält seine Zeilenumbrüche.
• ↑ ↓ blättern durch Ihren Verlauf, Tab vervollständigt, Esc bricht eine Antwort ab, Ctrl-D beendet die Session.

Unterhaltungen werden pro Repository gespeichert: archyl -c (--continue) öffnet die letzte wieder, /resume wählt eine frühere aus einer Liste, und /new beginnt eine neue.

Beim ersten Mal zeigt Ihnen die Session, was noch fehlt: die Anmeldung (/login), die Verknüpfung des Repositorys (/init). Der Assistent ist in den Plänen verfügbar, die den KI-Chat enthalten; /-Befehle funktionieren in jedem Plan. Mit Modellen von OpenAI und Anthropic ruft er die Befehle als native Tools auf; bei anderen Anbietern nutzt er ein Textprotokoll, ohne dass Sie einen Unterschied bemerken.

doctor

archyl doctor prüft alles, wovon die CLI abhängt, und sagt Ihnen, wie Sie beheben, was nicht stimmt: Ihre Version, das Profil, die Anmeldung, die API-Latenz, das Repository, die Projektverknüpfung, verbundene Agenten, den Guard-Hook und den Pre-Push-Hook. Der Befehl beendet sich mit Code 1, wenn etwas behoben werden muss.

Die Architektur erkunden

activity

archyl activity ist ein einziger Feed für alles, was im Projekt passiert: erstellte und geänderte Elemente (mit den geänderten Feldern), geöffnete und gemergte Änderungsanträge, Agent-Runs, die eingereiht sind, auf jemanden warten oder abgeschlossen sind, sowie geöffnete und geschlossene Arbeitssessions. --follow hält den Feed offen und gibt Ereignisse aus, sobald sie eintreten, wie tail -f; mit --notify erhalten Sie zusätzlich eine Desktop-Benachrichtigung, wenn ein Agent auf Sie wartet.

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

map

archyl map öffnet einen Vollbild-Explorer für das C4-Modell: Systeme, Container, Komponenten und Code in einem Baum, mit Beschreibung, Technologien, Beziehungen in beide Richtungen und Auswirkungsradius jedes Elements. Geben Sie ein Element an, um direkt dort zu starten: archyl map "Payments".

d zeigt die aktuelle Ebene als Diagramm. Tab und Shift+Tab wählen ein Element aus, die Pfeiltasten oder h j k l scrollen, Enter steigt in die Auswahl hinab, Backspace oder u geht eine Ebene hinauf, o öffnet sie in der Web-App, y kopiert ihre ID, und d oder Esc kehrt zum Baum zurück.

diagram

archyl diagram zeichnet eine C4-Ansicht des Modells: standardmäßig den Systemkontext, die Container eines Systems, wenn Sie ein System nennen, die Komponenten eines Containers, wenn Sie einen Container nennen. Elemente außerhalb der Ansicht erscheinen gestrichelt, wegen ihrer Beziehungen zu ihr.

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'

In Kitty, Ghostty, WezTerm und iTerm2 ist das Diagramm ein Bild direkt im Terminal. In anderen Terminals, und wenn die Ausgabe in eine Pipe geht, wird es mit Rahmenzeichen gezeichnet:

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

In tmux brauchen Bilder set -g allow-passthrough on und ein Terminal, das das Bildprotokoll von iTerm2 versteht. Setzen Sie ARCHYL_IMAGES=0, um immer als Text zu zeichnen.

search

archyl search durchsucht alles, was Sie in Archyl sehen können: Elemente, Entscheidungen, Dokumentation, API-Verträge, Event-Kanäle, Flows und Projekte. Die Ergebnisse aktualisieren sich während der Eingabe, mit einer Vorschau; Enter zeigt den gewählten Treffer, ctrl+o öffnet ihn in der Web-App. Per Pipe oder mit --json gibt archyl search invoice die Treffer aus.

show

archyl show <element> gibt ein Element mit Pfad, Beschreibung, Technologien, Beziehungen, verknüpften Entscheidungen und Auswirkungsradius aus. archyl show ADR-12 stellt einen Entscheidungsdatensatz dar. Elemente werden über ihren Namen (zuerst exakt, dann teilweise) oder ihre ID gefunden.

open

archyl open öffnet das Projekt in der Web-App; archyl open "Payments" wählt ein Element im Diagramm aus, archyl open ADR-12 klappt eine Entscheidung auf. Die Adresse der Web-App ist der API-Host, bei dem api. durch app. ersetzt wird; liegt sie woanders, melden Sie sich mit --app-url an oder setzen Sie ARCHYL_APP_URL.

ask

archyl ask "<question>" stellt dem KI-Assistenten eine Frage zur Architektur des Projekts. Die Antwort wird schon während des Schreibens als Markdown dargestellt. Alles, was Sie per Pipe übergeben, wird der Frage hinzugefügt:

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

Der Assistent ist in den Plänen verfügbar, die den KI-Chat enthalten.

adr

archyl adr listet die Entscheidungen des Projekts auf. archyl adr new erfasst eine neue: Im Terminal fragt ein Formular nach Titel, Status, Kontext, Entscheidung und Konsequenzen; in Skripten übergeben Sie diese als Flags.

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

discover

archyl discover startet eine KI-Entdeckung auf den mit dem Projekt verknüpften Repositorys und verfolgt sie, mit ihrem Fortschritt auf stderr. Was sie findet, landet nicht sofort im Modell: Es wartet auf ein Review, das sich von selbst öffnet, wenn die Entdeckung in einem Terminal endet. Jedes verknüpfte Repository zählt als eine KI-Entdeckung im Kontingent Ihres Plans.

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

archyl discover review listet die von Entdeckungen vorgeschlagenen Elemente auf, gruppiert nach C4-Ebene, mit den Details des ausgewählten Elements daneben:

Außerhalb eines Terminals gibt der Befehl die Liste aus; --approve-all oder --reject-all erledigt alles auf einmal, und --json gibt sie für Skripte aus.

Architekturbefehle

where

archyl where <path>… verortet Dateien im C4-Modell: das Element, zu dem jede gehört, wer dafür verantwortlich ist und was davon abhängt. Verzeichnisse werden zu den Dateien aufgelöst, die git kennt.

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

why

archyl why <file[:line]> ist git blame für die Architektur. Für eine Datei zeigt es die Elemente, zu denen sie gehört, die geltenden Entscheidungen (angenommene zuerst), wer sie verantwortet, was Agenten und Menschen sich dazu gemerkt haben, die letzten Modelländerungen an diesen Elementen und die Konformitätsregeln, die auf sie zielen. Mit einer Zeilennummer findet es außerdem den Commit, der die Zeile zuletzt geändert hat, und verknüpft ihn mit den Entscheidungen, die um dieselbe Zeit getroffen wurden.

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

Im Terminal wird die Antwort formatiert dargestellt; in einer Pipe oder von einem Agenten aufgerufen, gibt es kompaktes Markdown aus.

impact

archyl impact vergleicht Ihr Arbeitsverzeichnis mit einem Basis-Branch, verortet jede geänderte Datei in der Architektur und folgt den Beziehungen, um zu finden, was davon abhängt, samt den zu informierenden Verantwortlichen. Erfasst werden committete, gestagte, nicht gestagte und nicht getrackte Änderungen, sodass Sie den Befehl schon vor dem Commit ausführen können.

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

Jede Datei zählt nur für ihren spezifischsten Treffer: Eine Datei, die einer Komponente zugeordnet ist, zieht nicht zusätzlich ihren ganzen Container mit.

status

archyl status bringt das Projekt auf einen Bildschirm: die Übereinstimmung zwischen Modell und Code, Ihren Branch und die Agenten, die gerade am Projekt arbeiten.

context

archyl context gibt die Architektur des Projekts als Markdown aus, zugeschnitten auf Coding-Agenten: Systeme, Container, Komponenten, Beziehungen, Entscheidungen und Regeln. Leiten Sie die Ausgabe per Pipe weiter oder schreiben Sie sie in die Datei, die Ihr Agent liest.

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

Coding-Agenten

Die CLI ist der schnellste Weg, einen Coding-Agenten unter den Archyl Harness zu stellen.

setup

archyl setup

archyl setup konfiguriert Claude Code, Cursor, VS Code und Codex so, dass sie den MCP-Server von Archyl mit dem Tool-Profil coding nutzen, installiert den Guard-Hook und bringt den Agenten die CLI bei. Schränken Sie das mit --agent ein (mehrfach verwendbar: claude-code, cursor, vscode, codex); einzelne Teile lassen Sie mit --no-guard, --no-instructions oder --no-statusline weg.

archyl setup bietet außerdem an, die Shell-Vervollständigung zu installieren; --no-completion überspringt das.

Bestehende Dateien werden zusammengeführt, nicht überschrieben.

Standardmäßig (--transport cli) startet jeder Agent archyl mcp, das den MCP-Server von Archyl mit der eigenen Session der CLI erreicht: Melden Sie sich einmal mit archyl login an, und jeder Agent ist verbunden, ohne OAuth-Ablauf pro Agent und ohne Schlüssel in einer Datei. Mit --transport http enthält die Konfiguration nur die Server-URL, und jeder Agent meldet sich über Archyl selbst an. In beiden Fällen enthalten die Repository-Dateien kein Geheimnis und können bedenkenlos committet werden.

mcp

archyl mcp stellt einem Agenten die MCP-Tools von Archyl über stdio bereit, authentifiziert als Sie. archyl setup richtet das ein; von Hand, für jeden MCP-Client:

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

Es nutzt das Tool-Profil coding; --tools full stellt alle Tools bereit.

Der CLI-Block ist ein kurzer Abschnitt zwischen den Markierungen <!-- archyl:start --> und <!-- archyl:end -->, der dem Agenten sagt, welche archyl-Befehle er wann ausführen soll: plan vor einer nicht trivialen Änderung, brief vor dem Bearbeiten von Dateien, check und radar check vor dem Abschluss, remember und recall für das, was der Code nicht zeigen kann. Ein erneuter Aufruf von setup aktualisiert den Block und lässt den Rest der Datei unberührt. Eine in Claude Code bereits gesetzte Statuszeile wird nie ersetzt.

plan

archyl plan "<task>" liefert einen Implementierungsplan, der auf der Architektur aufbaut: die Schritte, das Element, das jeder davon berührt, die einzuhaltenden Entscheidungen und Regeln und was frühere Sessions gelernt haben.

archyl plan "Add partial refunds to the payments flow"

brief

archyl brief <files> sagt Ihnen oder einem Agenten, was man wissen sollte, bevor man diese Dateien bearbeitet: die Elemente, zu denen sie gehören, was diese Elemente nutzen und was von ihnen abhängt, die Entscheidungen, die für sie oder ihre übergeordneten Elemente gelten, ihre Verantwortlichen und was Archyl über sie im Gedächtnis hat. Ohne Pfade deckt der Befehl jede Datei ab, die der Branch ändert.

Wie plan, recall und context wird er im Terminal grafisch dargestellt und gibt kompaktes Markdown aus, wenn ein Agent ihn aus seiner Shell heraus ausführt, sodass der Agent Struktur liest statt Escape-Sequenzen.

remember und recall

archyl remember hält eine Tatsache, die der Code nicht zeigen kann, an dem Element fest, um das es geht; jede künftige Arbeitssession auf diesem Element wird damit gebrieft. archyl recall findet, was Archyl im Gedächtnis hat, nach Thema, Element oder Art.

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

Die Erinnerung wird dem Agenten zugeschrieben, der sie geschrieben hat, wenn die CLI in Claude Code, Codex oder Cursor läuft; setzen Sie ARCHYL_AGENT, um den Namen selbst festzulegen.

agents

archyl agents ist eine Live-Ansicht der Agenten, die am Projekt arbeiten: welcher Agent, an welcher Aufgabe, auf welchen Elementen, mit welchen geänderten Dateien. Elemente, auf denen mehr als ein Agent ein Lease hält, werden markiert, damit zwei Agenten nicht im selben Code kollidieren. Drücken Sie a, um kürzlich beendete Sessions einzubeziehen. Per Pipe oder mit --json gibt der Befehl die Sessions einmal aus.

statusline

archyl statusline ist eine Statuszeile für Claude Code: das Projekt, seine Übereinstimmung zwischen Modell und Code, die Agenten bei der Arbeit und ob die aktuelle Session unter dem Harness läuft. archyl setup installiert sie; von Hand, in .claude/settings.json:

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

runs

archyl runs listet die verwalteten Agent-Runs des Projekts auf und markiert die, die auf Sie warten. archyl runs view verfolgt einen Run live: die Nachrichten des Agenten, seine Tool-Aufrufe und die Dateien, die er ändert, im Feed, sein Plan mit dem Fortschritt jedes Schritts, Dauer, Tokens und Kosten am Rand. Und Sie handeln, ohne das Terminal zu verlassen:

Dieselben Aktionen gibt es als Befehle, für Skripte und für Agenten, die andere Agenten beaufsichtigen. Runs werden über die ersten Zeichen ihrer ID angegeben, oder mit 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

Verwaltete Agent-Runs sind in den Plänen verfügbar, die sie enthalten.

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 führt einen beliebigen Agenten innerhalb einer Arbeitssession aus:

1. Der Befehl öffnet eine Session für die Aufgabe. Archyl wählt die relevanten Elemente, Entscheidungen und Regeln aus, nimmt Leases auf die Elemente, damit zwei Agenten nicht kollidieren, und liefert ein Briefing mit dem Gate-Urteil zurück.
2. Claude Code erhält das Briefing als angehängten System-Prompt. Jeder Agent findet ARCHYL_SESSION_ID und ARCHYL_BRIEFING_FILE in seiner Umgebung.
3. Während der Agent arbeitet, wird die Session mit einem Heartbeat alle 10 Minuten am Leben gehalten, und der Guard-Hook ordnet ihr jede bearbeitete Datei zu.
4. Wenn der Agent beendet ist, meldet wrap die geänderten Dateien, schließt die Session und bietet an, einen Architektur-Änderungsantrag im Entwurf zu öffnen, damit ein Mensch prüft, wie das Modell nachgezogen werden soll.

Ist Archyl nicht erreichbar, gibt wrap eine Warnung aus und startet den Agenten trotzdem.

fix

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

archyl fix setzt einen Coding-Agenten unter dem Harness auf die Regelverstöße Ihres Branches an:

1. Es führt die Konformitätsprüfung auf dem Branch aus, wie archyl check, und lässt Sie die zu behebenden Verstöße auswählen.
2. Es öffnet eine Arbeitssession und übergibt dem Agenten jeden Verstoß mit Regel, Schweregrad, Fundstelle und Vorschlag, dazu das Briefing der Elemente, zu denen die Dateien gehören, und die geltenden Entscheidungen.
3. Wenn der Agent sich beendet, führt es die Prüfung erneut aus und zeigt, was übrig ist, zum Beispiel „3 violations → 0“.

Es wird nichts committet: Prüfen Sie die Änderungen mit git diff. Der Agent ist der erste installierte unter Claude Code und Codex, oder der, den --agent nennt. Nach -- läuft stattdessen ein beliebiger Befehl; er liest die Aufgabe aus der Datei, die ARCHYL_FIX_TASK_FILE angibt.

lsp

archyl lsp ist ein Language Server über stdio für jeden Editor mit LSP-Client. Er läuft neben dem eigenen Server der Sprache:

Er nutzt die Session der CLI (archyl login oder ARCHYL_API_KEY) und die .archyl.json des Repositorys. Ist Archyl nicht erreichbar, schreibt er eine einzige Warnung ins LSP-Log des Editors und zeigt keine Diagnosen. Diagnosen folgen dem Speichern, nicht dem Tippen.

Neovim 0.11 und neuer:

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

Helix, in languages.toml:

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

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

VS Code nutzt die Erweiterung Generic LSP Client, Zed eine kleine Dev-Erweiterung. Die Einrichtung für jeden Editor steht in docs/lsp.md.

guard

archyl guard ist der PreToolUse-Hook von Claude Code, den archyl setup installiert. Er liest den Hook-Payload von stdin, wendet die Konformitätsregeln des Projekts auf die Datei so an, wie sie nach der Bearbeitung aussähe, und antwortet mit einer Entscheidung: Kritische Verstöße blockieren die Bearbeitung, hohe erzeugen eine Warnung. Setzen Sie ARCHYL_GUARD_BLOCK auf high, um auch hohe Verstöße zu blockieren, oder auf off, um nur zu warnen.

Bearbeitet der Agent ein Abhängigkeitsmanifest (go.mod, package.json, pom.xml…), prüft der Guard es außerdem gegen das Technologie-Radar und blockiert eine Abhängigkeit, die das Radar auf Zurückstellen setzt, samt der Alternative, die ihre Notiz vorschlägt. Bereits vorhandene zurückgestellte Abhängigkeiten blockieren die Bearbeitung nicht.

Der Guard schlägt immer offen fehl: Fehlen Zugangsdaten oder Netzwerk oder ist das Tool unbekannt, lässt er die Bearbeitung durch, sodass er Ihren Workflow nie unterbrechen kann.

session

archyl session bietet Low-Level-Zugriff auf das Protokoll der Arbeitssessions, für Skripte oder Agenten, die es selbst steuern. Meistens erledigt archyl wrap all das für Sie.

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 nimmt die Session-ID als Argument oder aus ARCHYL_SESSION_ID. Tragen Sie in --decision nur ADR-würdige Entscheidungen ein: Jede wird zu einem Gedächtnis, das künftigen Sessions auf denselben Elementen erneut vorgelegt wird. Alles Situative gehört in --follow-up.

Prüfungen und CI

Dieselben Befehle laufen auf Ihrem Laptop, in einem Git-Hook und in jeder CI. In der CI entnehmen sie Basis-Branch, Commit und Berichtsformat der Umgebung: GitHub Actions, GitLab CI, Bitbucket Pipelines und Azure Pipelines werden erkannt.

check

archyl check wendet die Konformitätsregeln des Projekts auf jede Datei an, die sich vom Basis-Branch unterscheidet, und beendet sich mit Code 1, sobald ein Verstoß --fail-on erreicht.

$ 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

Mit --format auto richtet sich die Ausgabe nach der CI:

--format sarif schreibt ein SARIF-2.1.0-Log für GitHub Code Scanning, Azure DevOps oder jedes Security-Dashboard.

CI-Checkouts sind oft flach (shallow). Holen Sie die Historie, damit der Basis-Branch existiert; andernfalls bricht check ab und sagt es Ihnen.

# 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 ist der Durchlauf, bevor Sie einen Pull Request öffnen. Er fasst zusammen, welche Regelverstöße Ihr Branch einführt, welche Elemente er berührt und was davon abhängt, wen Sie informieren sollten und wie hoch die Übereinstimmung zwischen Modell und Code gerade ist. Er beendet sich mit Code 1, sobald ein Verstoß --fail-on erreicht (Standard high).

Mit --comment wird die Review im Pull oder Merge Request veröffentlicht und bei jedem späteren Push an Ort und Stelle aktualisiert, sodass der Request genau einen Archyl-Kommentar behält: das Urteil, die Verstöße mit Datei und Zeile, die berührten Elemente samt dem, was davon abhängt, und die Verantwortlichen, die Sie einbeziehen sollten. GitHub braucht GITHUB_TOKEN mit pull-requests: write; GitLab braucht GITLAB_TOKEN mit dem Scope api, da CI_JOB_TOKEN nicht kommentieren kann.

Der Kommentar enthält die Auswirkungen als Mermaid-Flowchart, das GitHub und GitLab darstellen. archyl review --diagram gibt dasselbe Flowchart lokal aus, zum Einfügen in eine Beschreibung oder ein Dokument.

Am schnellsten richten Sie das auf GitHub mit der Archyl-Action ein, die die CLI installiert und einen Befehl ausführt:

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

Lassen Sie command leer, um nur die CLI zu installieren und sie in späteren Schritten aufzurufen.

hooks

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

archyl hooks install fügt einen Git-pre-push-Hook hinzu, der archyl check --fail-open ausführt. Ein Push, der einen Verstoß auf oder über --fail-on (Standard critical) mitbringt, wird abgelehnt; ist archyl nicht im PATH, sind Sie offline oder abgemeldet, geht der Push durch. Einmalig überspringen Sie ihn mit git push --no-verify. Der Hook berücksichtigt core.hooksPath, und einen pre-push-Hook, den archyl nicht geschrieben hat, ersetzt er nie, es sei denn, Sie übergeben --force.

drift

archyl drift zeigt, wie gut das dokumentierte Modell zum Code passt: 100 bedeutet, dass jedes dokumentierte Element im Code gefunden wurde. --compute analysiert zuerst das verbundene Repository neu und wartet auf das Ergebnis; --fail-under macht daraus ein Quality Gate.

archyl drift --compute --fail-under 80

dsl

archyl dsl hält eine Architecture-as-Code-Datei und das Modell des Projekts im Gleichschritt. Jeder Unterbefehl arbeitet mit archyl.yaml im Wurzelverzeichnis des Repositorys, sofern Sie nicht --file übergeben.

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 exportiert das Modell (Elemente, Beziehungen, Technologien, Entscheidungen, Dokumentation, Verträge, Umgebungen und Releases). Vor dem Überschreiben der Datei fragt der Befehl nach, sofern Sie nicht --yes übergeben; --file - gibt es stattdessen aus.
• diff ist ein Probelauf auf dem Server, ohne etwas zu schreiben: die Elemente und Beziehungen, die ein Push hinzufügen (+) oder ändern (~) würde, gruppiert nach C4-Ebene, sowie die, die nur Archyl hat (−). --exit-code beendet sich mit Code 1, sobald es einen Unterschied gibt.
• push legt neue Elemente und Beziehungen an und aktualisiert bestehende, die über ihren Namen zugeordnet werden. Er löscht nie: Was nur Archyl hat, bleibt erhalten. Im Terminal zeigt er den Diff und fragt vorher; --yes überspringt die Frage.

$ 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] ist dasselbe wie archyl dsl push.

release

archyl release erfasst ein Release, um Architekturänderungen mit dem Ausgelieferten in Beziehung zu setzen und die DORA-Metriken zu speisen. Als Version dient standardmäßig das Tag, das in der CI gebaut wird, danach das Tag auf HEAD; der Link verweist standardmäßig auf den CI-Lauf.

archyl release v2.4.0 --environment production

radar

archyl radar zeigt die Technologien der Organisation nach Governance-Ring (Übernehmen, Erproben, Bewerten, Zurückstellen) und wie viel der Architektur jede davon nutzt. archyl radar check liest die Abhängigkeitsmanifeste des Repositorys, ordnet jede Abhängigkeit dem Radar zu und beendet sich mit Code 1, wenn eine davon zurückgestellt ist, mit derselben CI-Ausgabe wie 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 listet die Architektur-Änderungsanträge des Projekts auf — oft von Agenten am Ende einer Arbeitssession geöffnet — und lässt Sie sie prüfen, ohne das Terminal zu verlassen.

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

Konten und Profile

Ein Profil ist ein Archyl-Host mit einer Organisation und eigenen Zugangsdaten. Sie legen eines an, indem Sie sich mit einem Namen anmelden; so verbinden Sie sich auch mit einem selbst gehosteten Archyl:

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

Shell-Prompt

archyl prompt gibt die Übereinstimmung zwischen Modell und Code und die aktiven Agenten des Projekts in wenigen Zeichen für Ihren Shell-Prompt aus. Der Befehl wartet nie auf das Netzwerk: Er gibt den letzten bekannten Stand aus und aktualisiert ihn alle zehn Minuten im Hintergrund. Mit Starship:

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

Modell-Cache

map, show, open, die Vervollständigung von Elementen und die #-Vorschläge der Session antworten aus einer lokalen Kopie des Modells und starten daher sofort. Es gibt eine Kopie pro Profil, Host, Organisation, Identität und Projekt, in Ihrem Benutzer-Cache-Verzeichnis, nur für Sie lesbar. Eine Kopie, die jünger als 30 Sekunden ist, wird ohne API-Aufruf verwendet; eine ältere wird aktualisiert, und wenn die API länger als 1,5 Sekunden braucht, antwortet der Befehl aus der Kopie und weist auf stderr darauf hin. Befehle, die das Modell ändern, etwa dsl push oder das Freigeben von Entdeckungen, verwerfen die Kopie.

Umgehen Sie den Cache für einen einzelnen Befehl mit --no-cache oder überall mit ARCHYL_NO_CACHE=1. archyl login und archyl logout leeren die Kopien des Profils; archyl cache clear erledigt das von Hand.

Updates

Wenn ein neueres Release erschienen ist, weist die CLI darauf hin, sobald ein Befehl beendet ist. Die Prüfung läuft höchstens einmal am Tag im Hintergrund, nie in der CI oder in Skripten; setzen Sie ARCHYL_NO_UPDATE_NOTIFIER, um sie abzuschalten.

archyl upgrade aktualisiert die CLI so, wie Sie sie installiert haben: brew upgrade für Homebrew, den go install-Befehl für einen Build aus dem Quellcode, und sonst an Ort und Stelle: Es lädt das Release-Archiv für Ihre Plattform herunter, prüft es gegen die checksums.txt des Releases (und deren cosign-Signatur, wenn cosign in Ihrem PATH liegt) und tauscht damit das laufende Binary aus. --check meldet nur, ob ein neueres Release erschienen ist.

archyl upgrade
archyl upgrade --check

Globale Flags

Statusmeldungen und Spinner gehen nach stderr, Ergebnisse nach stdout, sodass Pipes immer nur das Ergebnis sehen:

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

CI und Skripte

Keine Anmeldung nötig: Erstellen Sie unter Profil → API-Schlüssel einen API-Schlüssel und setzen Sie ihn in der Umgebung.

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

Um einen API-Schlüssel stattdessen als Zugangsdaten zu speichern, leiten Sie ihn per Pipe an archyl login --with-token weiter.

Shell-Vervollständigung

archyl completion install schreibt das Vervollständigungsskript dorthin, wo Ihre Shell es lädt: in ein Verzeichnis aus dem fpath von zsh, das Ihnen gehört (oder ~/.zfunc), nach ~/.config/fish/completions oder nach ~/.local/share/bash-completion/completions. Ein erneuter Aufruf aktualisiert das Skript. Die Startdatei Ihrer Shell ändert es nur, wenn es nötig ist (zsh ohne eigenes fpath-Verzeichnis, PowerShell) und Sie zustimmen. archyl setup bietet es ebenfalls an.

archyl completion install
archyl completion install --shell fish

Um das Skript selbst zu schreiben:

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