Archyl CLI

archyl collega un repository alla sua architettura in Archyl. Dal terminale puoi scoprire dove si colloca un file nel modello C4, vedere cosa tocca il tuo branch e chi avvisare, fornire un briefing agli agenti di programmazione prima che mettano mano al codice e sorvegliare ciò che scrivono.

$ 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 è open source con licenza MIT: github.com/archyl-com/cli.

Installazione

# 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

Puoi anche scaricare un binario dalla pagina delle release. Gli archivi sono accompagnati da checksum, firmati con cosign e distribuiti con uno SBOM.

Verifica l'installazione con archyl --version.

Per iniziare

Dalla radice del tuo repository:

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 apre il browser ed effettua l'accesso con OAuth 2.1 e PKCE. La sessione viene salvata nel portachiavi del sistema operativo e si rinnova da sola; dovrai accedere di nuovo solo dopo un mese di inutilizzo.

archyl init scrive .archyl.json nella radice del repository, così ogni comando archyl, e l'hook Guard, sa a quale progetto appartiene questo codice. Quando il remote del repository è collegato a un progetto in Archyl, quel progetto viene scelto per te; altrimenti lo selezioni da un elenco. Fai commit del file: non contiene alcun segreto, e così il tuo team e la tua CI condividono lo stesso collegamento.

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

Esegui archyl init --force per collegare un repository a un altro progetto.

Non hai ancora un progetto? archyl init --new ne crea uno senza lasciare il terminale:

1. Crea il progetto, con il nome del repository (o --name), nel team che scegli (--team, per nome, slug o ID).
2. Collega il repository a partire dal suo remote git. Per un remote self-hosted, indica il provider con --provider: github_enterprise, gitlab_private o gitea.
3. Avvia una scoperta tramite IA su --branch (predefinito: il branch predefinito del remote) e ne mostra l'avanzamento in diretta.
4. Apre la revisione di ciò che la scoperta ha trovato, poi disegna il risultato come diagramma.
5. Propone di collegare i tuoi agenti di sviluppo.

archyl init da solo propone la stessa cosa quando nessun progetto corrisponde al remote del repository. --no-discover si limita a creare e collegare il progetto, --no-setup salta l'ultimo passaggio e --yes accetta tutti i valori predefiniti senza chiedere, compresa l'approvazione di ciò che la scoperta trova.

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

La sessione

Esegui archyl da solo per aprire una sessione: un prompt in cui fai domande sull'architettura in linguaggio naturale o digiti comandi, con le risposte che scorrono nel terminale come qualsiasi altro output.

$ 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

• Il linguaggio naturale va all'assistente. Risponde a partire dall'architettura e, quando la risposta dipende dal tuo codice o da ciò che sta succedendo in questo momento, esegue qui il comando corrispondente — impact, check, brief, show, runs… — e mostra ciascuno (⏺) prima di usarne l'output. I comandi in sola lettura vengono eseguiti in parallelo; quelli che modificano qualcosa, come approvare il piano di un'esecuzione o registrare una memoria, ti chiedono prima conferma (y/n).
• I comandi / vengono eseguiti direttamente: /impact, /review, /brief <files>, /show <element>, /runs, /activity… Le viste a schermo intero (/map, /search, /run, /agents) occupano lo schermo e lo restituiscono quando le chiudi. /help elenca tutto.
• @file allega alla domanda il contenuto del file, con il suo briefing architetturale: fino a 400 righe o 24 KB per file; i file binari e i percorsi esterni al repository vengono ignorati. #element indirizza la domanda a un elemento. Entrambi si completano mentre scrivi.
• Enter invia; Shift+Enter (o Alt+Enter, Ctrl+J) va a capo, e il testo incollato mantiene le sue interruzioni di riga.
• ↑ ↓ scorrono la cronologia, Tab completa, Esc interrompe una risposta, Ctrl-D esce.

Le conversazioni vengono conservate per repository: archyl -c (--continue) riapre l'ultima, /resume ne sceglie una precedente da un elenco e /new ne avvia una nuova.

La prima volta, la sessione ti dice cosa manca: l'accesso (/login), il collegamento del repository (/init). L'assistente è disponibile nei piani che includono la chat IA; i comandi / funzionano con tutti i piani. Con i modelli OpenAI e Anthropic chiama i comandi come strumenti nativi; con gli altri provider passa per un protocollo testuale, e non noti alcuna differenza.

doctor

archyl doctor controlla tutto ciò da cui dipende la CLI e ti dice come sistemare ciò che non va: la tua versione, il profilo, l'accesso, la latenza dell'API, il repository, il collegamento al progetto, gli agenti connessi, l'hook Guard e l'hook pre-push. Esce con 1 quando c'è qualcosa da sistemare.

Esplorare l'architettura

activity

archyl activity è un unico feed di ciò che succede nel progetto: elementi creati e modificati (con i campi cambiati), richieste di modifica aperte e unite, esecuzioni degli agenti in coda, in attesa di qualcuno e terminate, sessioni di lavoro aperte e chiuse. --follow lo tiene aperto e stampa gli eventi man mano che accadono, come tail -f; aggiungi --notify per ricevere una notifica desktop quando un agente ti aspetta.

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

map

archyl map apre un esploratore a schermo intero del modello C4: sistemi, container, componenti e codice in un albero, con la descrizione di ogni elemento, le sue tecnologie, le relazioni in entrambe le direzioni e il raggio d'impatto. Indica un elemento per aprire l'esploratore direttamente su di esso: archyl map "Payments".

d mostra il livello corrente come diagramma. Tab e Shift+Tab selezionano un elemento, le frecce o h j k l scorrono la vista, Enter scende nella selezione, Backspace o u risale, o la apre nell'app web, y ne copia l'ID, e d o Esc torna all'albero.

diagram

archyl diagram disegna una vista C4 del modello: il contesto di sistema per impostazione predefinita, i container di un sistema quando nomini un sistema, i componenti di un container quando nomini un container. Gli elementi fuori dalla vista appaiono tratteggiati, per le loro relazioni con essa.

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 e iTerm2 il diagramma è un'immagine dentro il terminale. Negli altri terminali, e quando l'output passa in una pipe, viene disegnato con caratteri di riquadro:

 ┌─────────────────┐   ┌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┐   ┌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┐
 │ ▣ 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 tmux, le immagini richiedono set -g allow-passthrough on e un terminale che capisca il protocollo immagini di iTerm2. Imposta ARCHYL_IMAGES=0 per disegnare sempre in testo.

search

archyl search cerca in tutto ciò che puoi vedere in Archyl: elementi, decisioni, documentazione, contratti API, canali di eventi, flussi e progetti. I risultati si aggiornano mentre scrivi, con un'anteprima; Invio mostra la voce scelta, ctrl+o la apre nell'app web. In pipe o con --json, archyl search invoice stampa i risultati.

show

archyl show <element> stampa un elemento con il suo percorso, la descrizione, le tecnologie, le relazioni, le decisioni collegate e il raggio d'impatto. archyl show ADR-12 mostra un record di decisione. Gli elementi vengono trovati per nome (esatto, poi parziale) o per ID.

open

archyl open apre il progetto nell'app web; archyl open "Payments" seleziona un elemento nel diagramma, archyl open ADR-12 espande una decisione. L'indirizzo dell'app web è l'host dell'API con api. sostituito da app.; se si trova altrove, accedi con --app-url o imposta ARCHYL_APP_URL.

ask

archyl ask "<question>" pone una domanda all'assistente IA sull'architettura del progetto. La risposta viene resa in markdown mentre viene scritta. Tutto ciò che passi in pipe viene aggiunto alla domanda:

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

L'assistente è disponibile nei piani che includono la chat IA.

adr

archyl adr elenca le decisioni del progetto. archyl adr new ne registra una: in un terminale, un modulo chiede titolo, stato, contesto, decisione e conseguenze; negli script, passali come flag.

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

discover

archyl discover avvia una scoperta tramite IA sui repository collegati al progetto e la segue, con l'avanzamento su stderr. Ciò che trova non entra subito nel modello: resta in attesa di revisione, che si apre da sola quando la scoperta termina in un terminale. Ogni repository collegato conta come una scoperta tramite IA nella quota del tuo piano.

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

archyl discover review elenca gli elementi proposti dalle scoperte, raggruppati per livello C4, con i dettagli dell'elemento selezionato a lato:

Fuori da un terminale stampa l'elenco; --approve-all o --reject-all risolve tutto in una volta, e --json lo stampa per gli script.

Comandi di architettura

where

archyl where <path>… colloca i file nel modello C4: l'elemento a cui appartiene ciascuno, chi ne è responsabile e cosa ne dipende. Le directory vengono espanse nei file noti a git.

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

why

archyl why <file[:line]> è git blame per l'architettura. Per un file, mostra gli elementi a cui appartiene, le decisioni che si applicano (prima quelle accettate), chi ne è responsabile, ciò che agenti e persone hanno memorizzato su di esso, le ultime modifiche al modello su quegli elementi e le regole di conformità che lo riguardano. Con un numero di riga, trova anche il commit che ha modificato la riga per ultimo e lo collega alle decisioni prese nello stesso periodo.

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

In un terminale la risposta viene formattata; in una pipe o eseguito da un agente, stampa markdown compatto.

impact

archyl impact confronta la tua working tree con un branch di base, colloca ogni file modificato nell'architettura e percorre le relazioni per trovare cosa ne dipende, insieme ai responsabili da avvisare. Copre le modifiche committate, in staging, non in staging e non tracciate, quindi puoi eseguirlo ancora prima di fare commit.

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

Ogni file conta solo per la sua corrispondenza più specifica: un file associato a un componente non trascina con sé anche l'intero container.

status

archyl status fa stare il progetto in una sola schermata: l'allineamento tra modello e codice, il tuo branch e gli agenti che stanno lavorando al progetto in questo momento.

context

archyl context stampa l'architettura del progetto in markdown pensato per gli agenti di programmazione: sistemi, container, componenti, relazioni, decisioni e regole. Passalo in pipe o scrivilo nel file che il tuo agente legge.

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

Agenti di programmazione

La CLI è il modo più rapido per mettere un agente di programmazione sotto l'Archyl Harness.

setup

archyl setup

archyl setup configura Claude Code, Cursor, VS Code e Codex per usare il server MCP di Archyl con il profilo di strumenti coding, installa l'hook Guard e insegna la CLI agli agenti. Limitalo con --agent (ripetibile: claude-code, cursor, vscode, codex); salta alcune parti con --no-guard, --no-instructions o --no-statusline.

archyl setup propone anche di installare il completamento della shell; --no-completion lo salta.

I file esistenti vengono uniti, non sovrascritti.

Per impostazione predefinita (--transport cli), ogni agente avvia archyl mcp, che raggiunge il server MCP di Archyl con la sessione della CLI stessa: accedi una volta con archyl login e ogni agente è connesso, senza un flusso OAuth per agente né chiavi in un file. Con --transport http, la configurazione contiene solo l'URL del server e ogni agente accede tramite Archyl stesso. In entrambi i casi i file del repository non contengono segreti e puoi farne il commit in tutta sicurezza.

mcp

archyl mcp serve gli strumenti MCP di Archyl a un agente tramite stdio, autenticato come te. archyl setup lo configura; a mano, per qualsiasi client MCP:

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

Usa il profilo di strumenti coding; --tools full espone tutti gli strumenti.

Il blocco CLI è una breve sezione tra i marcatori <!-- archyl:start --> e <!-- archyl:end --> che dice all'agente quali comandi archyl eseguire e quando: plan prima di una modifica non banale, brief prima di modificare dei file, check e radar check prima di concludere, remember e recall per ciò che il codice non può mostrare. Eseguire di nuovo setup aggiorna il blocco e lascia intatto il resto del file. Una status line già impostata in Claude Code non viene mai sostituita.

plan

archyl plan "<task>" restituisce un piano di implementazione basato sull'architettura: i passaggi, l'elemento che ciascuno tocca, le decisioni e le regole da rispettare e ciò che le sessioni precedenti hanno imparato.

archyl plan "Add partial refunds to the payments flow"

brief

archyl brief <files> dice a te, o a un agente, cosa sapere prima di modificare quei file: gli elementi a cui appartengono, ciò che quegli elementi usano e ciò che ne dipende, le decisioni che si applicano a loro o ai loro genitori, i loro responsabili e ciò che Archyl ricorda su di loro. Senza percorsi, copre tutti i file modificati dal branch.

Come plan, recall e context, si presenta in forma grafica in un terminale e stampa un markdown compatto quando un agente lo esegue dalla propria shell, così l'agente legge una struttura, non sequenze di escape.

remember e recall

archyl remember registra un fatto che il codice non può mostrare sull'elemento a cui si riferisce; ogni futura sessione di lavoro su quell'elemento riceve questo fatto nel briefing. archyl recall trova ciò che Archyl ricorda, per argomento, 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 viene attribuita all'agente che l'ha scritta quando la CLI gira dentro Claude Code, Codex o Cursor; imposta ARCHYL_AGENT per indicarne tu il nome.

agents

archyl agents è una vista in tempo reale degli agenti al lavoro sul progetto: quale agente, su quale compito, su quali elementi, con quali file modificati. Gli elementi su cui più di un agente detiene un lease vengono segnalati, in modo che due agenti non entrino in collisione sullo stesso codice. Premi a per includere le sessioni terminate di recente. In pipe o con --json, stampa le sessioni una sola volta.

statusline

archyl statusline è una status line per Claude Code: il progetto, il suo punteggio di allineamento, gli agenti al lavoro e se la sessione corrente gira sotto l'harness. archyl setup la installa; a mano, in .claude/settings.json:

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

runs

archyl runs elenca le esecuzioni gestite degli agenti del progetto, segnalando quelle in attesa di te. archyl runs view ne segue una in tempo reale: i messaggi dell'agente, le sue chiamate agli strumenti e i file che modifica nel feed, il suo piano con l'avanzamento di ogni passo, il tempo, i token e il costo a lato. E puoi intervenire senza lasciare il terminale:

Le stesse azioni esistono come comandi, per gli script e per gli agenti che supervisionano altri agenti. Le esecuzioni si indicano con i primi caratteri del loro ID, oppure 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

Le esecuzioni gestite degli agenti sono disponibili nei piani che le includono.

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 esegue qualsiasi agente all'interno di una sessione di lavoro:

1. Apre una sessione per il compito. Archyl sceglie gli elementi, le decisioni e le regole pertinenti, acquisisce dei lease sugli elementi in modo che due agenti non entrino in collisione, e restituisce un briefing con il verdetto del gate.
2. Claude Code riceve il briefing come prompt di sistema aggiuntivo. Ogni agente trova ARCHYL_SESSION_ID e ARCHYL_BRIEFING_FILE nel proprio ambiente.
3. Mentre l'agente lavora, la sessione viene mantenuta attiva con un heartbeat ogni 10 minuti, e l'hook Guard le attribuisce ogni file modificato.
4. Quando l'agente termina, wrap riporta i file cambiati, chiude la sessione e propone di aprire una bozza di richiesta di modifica architetturale, così che una persona valuti come il modello debba mettersi in pari.

Se Archyl non è raggiungibile, wrap mostra un avviso ed esegue comunque l'agente.

fix

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

archyl fix mette un agente di sviluppo al lavoro sulle violazioni delle regole del tuo branch, sotto l'harness:

1. Esegue il controllo di conformità sul branch, come archyl check, e ti lascia scegliere le violazioni da correggere.
2. Apre una sessione di lavoro e passa all'agente ogni violazione con regola, severità, posizione e suggerimento, insieme al brief degli elementi a cui appartengono i file e alle decisioni che si applicano.
3. Quando l'agente termina, riesegue il controllo e mostra cosa resta, per esempio «3 violations → 0».

Non viene fatto alcun commit: rivedi le modifiche con git diff. L'agente è il primo installato tra Claude Code e Codex, oppure quello indicato da --agent. Dopo -- viene eseguito al suo posto un comando qualsiasi, che legge il compito dal file indicato in ARCHYL_FIX_TASK_FILE.

lsp

archyl lsp è un language server su stdio per qualsiasi editor con un client LSP. Gira accanto al server proprio del linguaggio:

Usa la sessione della CLI (archyl login o ARCHYL_API_KEY) e il .archyl.json del repository. Quando Archyl non è raggiungibile, scrive un solo avviso nel log LSP dell'editor e non mostra diagnostica. La diagnostica segue i salvataggi, non la digitazione.

Neovim 0.11 e successivi:

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 passa per l'estensione Generic LSP Client, Zed per una piccola estensione di sviluppo. La configurazione di ogni editor è in docs/lsp.md.

guard

archyl guard è l'hook PreToolUse di Claude Code che archyl setup installa. Legge il payload dell'hook da stdin, esegue le regole di conformità del progetto sul file così come sarebbe dopo la modifica e risponde con una decisione: le violazioni critiche bloccano la modifica, quelle alte generano un avviso. Imposta ARCHYL_GUARD_BLOCK su high per bloccare anche le violazioni alte, o su off per limitarti agli avvisi.

Quando l'agente modifica un manifest delle dipendenze (go.mod, package.json, pom.xml…), il Guard lo confronta anche con il technology radar e blocca una dipendenza che il radar mette In sospeso, indicando l'alternativa suggerita dalla sua nota. Le dipendenze In sospeso già presenti non bloccano la modifica.

Il Guard fallisce sempre in modalità aperta: senza credenziali, senza rete o con uno strumento sconosciuto lascia passare la modifica, quindi non può mai interrompere il tuo workflow.

session

archyl session offre un accesso di basso livello al protocollo delle sessioni di lavoro, per gli script o gli agenti che lo gestiscono in autonomia. Nella maggior parte dei casi archyl wrap fa tutto questo al posto tuo.

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 prende l'ID di sessione come argomento o da ARCHYL_SESSION_ID. In --decision metti solo scelte degne di un ADR: ciascuna diventa memoria riproposta alle sessioni future sugli stessi elementi. Tutto ciò che è contingente va in --follow-up.

Controlli e CI

Gli stessi comandi girano sul tuo portatile, in un hook git e in qualsiasi CI. In CI ricavano dall'ambiente il branch di base, il commit e il formato del report: GitHub Actions, GitLab CI, Bitbucket Pipelines e Azure Pipelines vengono riconosciuti.

check

archyl check esegue le regole di conformità del progetto su ogni file che differisce dal branch di base ed esce con 1 quando una violazione raggiunge --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, l'output segue la CI:

--format sarif scrive un log SARIF 2.1.0 per il code scanning di GitHub, Azure DevOps o qualsiasi dashboard di sicurezza.

I checkout in CI sono spesso shallow. Recupera la cronologia in modo che il branch di base esista, altrimenti check si ferma e te lo segnala.

# 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 è il passaggio da eseguire prima di aprire una pull request. Riunisce le violazioni delle regole introdotte dal tuo branch, gli elementi che tocca insieme a ciò che ne dipende, chi avvisare e il punteggio di allineamento attuale. Esce con 1 quando una violazione raggiunge --fail-on (predefinito high).

Con --comment, la review viene pubblicata sulla pull o merge request e modificata sul posto a ogni push successivo, così la richiesta conserva un solo commento di Archyl: il verdetto, le violazioni con il loro file e la loro riga, gli elementi toccati insieme a ciò che ne dipende e i responsabili da coinvolgere. GitHub richiede GITHUB_TOKEN con pull-requests: write; GitLab richiede GITLAB_TOKEN con lo scope api, perché CI_JOB_TOKEN non può commentare.

Il commento include l'impatto come flowchart Mermaid, che GitHub e GitLab visualizzano. archyl review --diagram stampa lo stesso flowchart in locale, da incollare in una descrizione o in un documento.

Il modo più rapido per configurarla su GitHub è l'action di Archyl, che installa la CLI ed esegue 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

Lascia vuoto command per installare soltanto la CLI e richiamarla nei passaggi successivi.

hooks

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

archyl hooks install aggiunge un hook git pre-push che esegue archyl check --fail-open. Un push che porta una violazione pari o superiore a --fail-on (predefinito critical) viene rifiutato; senza archyl nel PATH, offline o senza accesso, il push passa. Per saltarlo una volta usa git push --no-verify. L'hook rispetta core.hooksPath, e un hook pre-push non scritto da archyl non viene mai sostituito, a meno che tu non passi --force.

drift

archyl drift mostra quanto il modello documentato corrisponde al codice: 100 significa che ogni elemento documentato è stato trovato nel codice. --compute rianalizza prima il repository collegato e attende il risultato; --fail-under lo trasforma in un quality gate.

archyl drift --compute --fail-under 80

dsl

archyl dsl mantiene allineati un file di architecture-as-code e il modello del progetto. Ogni sottocomando lavora su archyl.yaml nella root del repository, a meno che tu non passi --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 esporta il modello (elementi, relazioni, tecnologie, decisioni, documentazione, contratti, ambienti e release). Chiede conferma prima di sovrascrivere il file, a meno che tu non passi --yes; --file - lo stampa invece di scriverlo.
• diff è un dry run sul server, senza scrivere nulla: gli elementi e le relazioni che un push aggiungerebbe (+) o modificherebbe (~), raggruppati per livello C4, e quelli presenti solo in Archyl (−). --exit-code esce con 1 quando c'è una qualsiasi differenza.
• push crea i nuovi elementi e relazioni e aggiorna quelli esistenti, abbinati per nome. Non elimina mai nulla: ciò che c'è solo in Archyl resta. In un terminale mostra il diff e chiede prima conferma; --yes salta la domanda.

$ 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, per correlare le modifiche architetturali con ciò che è stato rilasciato e alimentare le metriche DORA. La versione è per impostazione predefinita il tag in fase di build in CI, poi il tag su HEAD; il link punta per impostazione predefinita all'esecuzione della CI.

archyl release v2.4.0 --environment production

radar

archyl radar mostra le tecnologie dell'organizzazione per anello di governance (Adottare, Provare, Valutare, In sospeso), con quanta parte dell'architettura usa ciascuna. archyl radar check legge i manifest delle dipendenze del repository, abbina ogni dipendenza al radar ed esce con 1 quando una è In sospeso, con lo stesso output per la CI di 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 elenca le richieste di modifica architetturale del progetto — spesso aperte dagli agenti alla fine di una sessione di lavoro — e ti permette di esaminarle senza lasciare il terminale.

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

Account e profili

Un profilo è un host Archyl con un'organizzazione e una propria credenziale. Ne crei uno accedendo con un nome, che è anche il modo per collegarti a un Archyl self-hosted:

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

Prompt della shell

archyl prompt stampa in pochi caratteri il punteggio di allineamento del progetto e gli agenti attivi, per il prompt della tua shell. Non attende mai la rete: stampa l'ultimo stato noto e lo aggiorna in background ogni dieci minuti. Con Starship:

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

Cache del modello

map, show, open, il completamento degli elementi e i suggerimenti # della sessione rispondono a partire da una copia locale del modello, così partono all'istante. C'è una copia per profilo, host, organizzazione, identità e progetto, nella tua directory di cache utente, leggibile solo da te. Una copia con meno di 30 secondi viene usata senza chiamare l'API; una più vecchia viene aggiornata, e quando l'API impiega più di 1,5 secondi il comando risponde a partire dalla copia e lo segnala su stderr. I comandi che modificano il modello, come dsl push o l'approvazione delle scoperte, scartano la copia.

Salta la cache per un singolo comando con --no-cache, o ovunque con ARCHYL_NO_CACHE=1. archyl login e archyl logout svuotano le copie del profilo; archyl cache clear lo fa a mano.

Aggiornamenti

Quando esce una release più recente, la CLI lo segnala al termine di un comando. Il controllo gira in background al massimo una volta al giorno, mai in CI o negli script; imposta ARCHYL_NO_UPDATE_NOTIFIER per disattivarlo.

archyl upgrade aggiorna la CLI nel modo in cui l'hai installata: brew upgrade per Homebrew, il comando go install per una build dai sorgenti, e altrimenti sul posto: scarica l'archivio della release per la tua piattaforma, lo verifica con il checksums.txt della release (e la sua firma cosign quando cosign è nel tuo PATH), poi lo sostituisce al binario in esecuzione. --check si limita a dire se è uscita una release più recente.

archyl upgrade
archyl upgrade --check

Flag globali

I messaggi di stato e gli spinner vanno su stderr, i risultati su stdout, così le pipe vedono sempre e solo il risultato:

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

CI e script

Nessun accesso necessario: crea una chiave API in Profilo → Chiavi API e impostala nell'ambiente.

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

Per salvare invece una chiave API come credenziale, passala in pipe a archyl login --with-token.

Completamento della shell

archyl completion install scrive lo script di completamento dove la tua shell lo carica: una directory del fpath di zsh di tua proprietà (o ~/.zfunc), ~/.config/fish/completions o ~/.local/share/bash-completion/completions. Rieseguilo per aggiornare lo script. Modifica il file di avvio della shell solo quando serve (zsh senza una directory fpath tua, PowerShell) e se sei d'accordo. Anche archyl setup lo propone.

archyl completion install
archyl completion install --shell fish

Per scrivere lo script a mano:

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