Cosa ti offre la CLI
Il binario zero è l'intera toolchain di sviluppo. Non ci sono un gestore di pacchetti, un formattatore, un linter o un test runner separati: sono tutti sottocomandi di zero. Così la superficie resta piccola e prevedibile, ed è proprio questo l'obiettivo.
Un breve menu dei comandi che userai di più:
| Comando | Cosa fa |
|---|---|
zero check | Controlla i tipi del sorgente senza produrre un eseguibile. |
zero run | Compila ed esegue in un solo passaggio. |
zero build | Compila in un eseguibile nativo. |
zero test | Esegue i target di test di un pacchetto. |
zero fix | Applica o mostra in anteprima i piani di correzione strutturati. |
zero explain | Cerca la spiegazione in prosa di un codice di diagnostica. |
zero new | Crea la struttura di un nuovo pacchetto. |
zero --version | Stampa la versione della toolchain. |
Ognuno di questi accetta --json per emettere un output leggibile dalle macchine invece di testo formattato per le persone.
zero check
Il cavallo di battaglia. zero check esegue i controlli statici del compilatore, cioè parsing, controllo dei tipi, inferenza di capability ed effetti e rilevamento degli import mancanti, e si ferma prima della generazione del codice. È veloce, e questo conta perché agenti ed editor lo chiamano di continuo.
zero check hello.0
Un output pulito (niente stampato, codice di uscita 0) significa che il file è ben formato. Per impostazione predefinita gli errori escono come testo leggibile. Aggiungi --json e ottieni la forma strutturata usata dagli agenti:
zero check hello.0 --json
{
"ok": false,
"diagnostics": [
{
"code": "NAM003",
"message": "unknown identifier",
"line": 3,
"repair": { "id": "declare-missing-symbol" }
}
]
}
La struttura della diagnostica è documentata in dettaglio in Diagnostica JSON. Nota il campo stabile code: NAM003 significa sempre "identificatore sconosciuto", qualunque sia la versione del compilatore.
Puoi anche indicare a check la cartella di un pacchetto invece di un singolo file:
zero check ./mio-pacchetto
Legge zero.json, percorre l'albero dei sorgenti e segnala ogni problema in ogni target.
zero run
run compila ed esegue in un solo passaggio. È l'ideale quando stai iterando su un piccolo programma e non ti interessa produrre un binario su disco.
zero run hello.0
Equivale a eseguire zero build e poi lanciare il binario prodotto, solo che l'artefatto viene scartato. Lo stdout del tuo programma viene inoltrato allo stdout del terminale: le chiamate world.out.write del programma finiscono sul tuo schermo.
Se il programma ha bisogno di argomenti, passali dopo un --:
zero run greet.0 -- Alice
Il runtime dà al programma accesso a quegli argomenti tramite la stessa capability World che espone l'I/O.
zero build
Quando vuoi un artefatto, usa build:
zero build hello.0
Il compilatore produce un eseguibile nativo accanto al tuo file sorgente (o nella cartella di build del pacchetto, se stai lavorando in un pacchetto). Puoi eseguirlo come qualsiasi altro programma: non serve un runtime separato perché i binari di Zero sono autonomi.
I binari di Zero sono piccoli. L'obiettivo di design del progetto sono eseguibili sotto i 10 KB per i programmi banali, ottenuti saltando la toolchain LLVM ed emettendo direttamente percorsi di codice compatti.
zero test
Esegue i target di test di un pacchetto:
zero test
I test vivono accanto ai sorgenti in src/, dichiarati come target di test nel zero.json del pacchetto. Il runner li trova, li esegue uno per uno e riporta superato/fallito. Con --json l'output è strutturato per ogni test, con nome, stato, durata e diagnostica raccolta, per agenti e strumenti di CI.
Pacchetti Zero spiega come dichiarare i target di test in zero.json.
zero fix
fix usa i metadati di correzione prodotti da check --json. Ha due modalità:
zero fix --plan --json # mostra il piano strutturato, senza applicarlo
zero fix # applica il piano sul posto
Un piano ha più o meno questo aspetto (la struttura è indicativa):
{
"diagnostic": { "code": "NAM003", "line": 3 },
"plan": {
"id": "declare-missing-symbol",
"edits": [
{ "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
]
}
}
L'idea è che un agente ottenga il piano, decida se fidarsi e poi lo applichi direttamente o lo passi a un passaggio di ragionamento di livello più alto. I piani sono dati; gli agenti non devono interpretare prosa per agire.
zero explain
explain è il lato in prosa del sistema di diagnostica:
zero explain NAM003
Stampa una spiegazione leggibile del codice di errore: cosa significa, perché il compilatore lo emette e come sono di solito le correzioni. È utile quando:
- Una persona sta facendo debug e vuole una risposta più lunga del messaggio in linea.
- Un agente incontra un codice di diagnostica che non era nei suoi dati di addestramento e vuole più contesto.
Il codice in sé è stabile tra le versioni del compilatore, quindi le spiegazioni salvate restano valide.
zero new
Crea la struttura di un nuovo pacchetto:
zero new cli hello
Questo crea una cartella hello/ con un manifest zero.json e un src/main.0 iniziale. Il primo argomento (qui cli) sceglie un template, in questo caso un'applicazione eseguibile a riga di comando. Pacchetti Zero spiega la struttura nel dettaglio.
L'abitudine del --json
Quasi ogni comando supporta --json. Se stai costruendo strumenti, un ambiente per agenti o una pipeline di CI attorno a Zero, usa per impostazione predefinita la forma JSON. È:
- Stabile. Lo schema ha una versione e il team lo tratta come un contratto.
- Completa. Ottieni campi che non compaiono nell'output per le persone (intervalli precisi, ID dei piani di correzione, dati del grafo delle dipendenze).
- Analizzabile. Nessuna espressione regolare su prosa in inglese per estrarre un numero di riga.
Se sei una persona, lascia perdere --json: al terminale il testo formattato è quello che ti serve.
Altri comandi utili
Alcuni comandi usati meno spesso ma che vale la pena conoscere:
zero graph --json: emette il grafo delle dipendenze di un pacchetto come dati strutturati. Utile per capire cosa dipende da cosa, e per gli agenti che vogliono ragionare sui punti di chiamata.zero size --json: riporta la dimensione su disco degli artefatti compilati, suddivisa per target. Utile quando ti interessa l'ingombro del binario (che è un obiettivo di design di Zero).zero --version: stampa la versione della toolchain. Annotala da qualche parte se lavori in un team: Zero è pre-1.0 e le modifiche incompatibili arrivano davvero.
Prossimo passo: pacchetti Zero
Un singolo file .0 va bene per un hello world. I progetti reali usano pacchetti con un manifest zero.json e una cartella src/. Pacchetti Zero mostra come crearne uno e spiega ogni campo.
Domande frequenti
Quali sono i comandi principali della CLI di Zero?
I comandi fondamentali sono zero check (controlla i tipi di un file o di un pacchetto), zero run (compila ed esegue), zero build (compila in un eseguibile), zero test (esegue i test), zero fix (applica le correzioni suggerite) e zero explain (cerca il significato di un codice di diagnostica). Ognuno accetta un flag --json per un output leggibile dalle macchine.
Cosa fa zero check?
zero check?zero check <file-or-package> esegue i controlli statici del compilatore, cioè parsing, controllo dei tipi e analisi di capability ed effetti, senza produrre un eseguibile. È il modo più rapido per sapere se il tuo codice è ben formato. Con --json emette diagnostica strutturata pensata per gli agenti.
Qual è la differenza tra zero run e zero build?
zero run e zero build?zero run <file> compila ed esegue il programma in un solo passaggio, come go run o cargo run. zero build compila il programma e si ferma, lasciando un binario nativo che puoi distribuire o eseguire in seguito. Usa run mentre stai iterando; usa build quando vuoi un artefatto.
Come funziona zero fix --plan?
zero fix --plan?Quando zero check --json riporta una diagnostica con un campo repair, zero fix --plan --json restituisce il piano strutturato che un agente può applicare per risolverla. Il piano è fatto di dati, cioè operazioni di modifica sul sorgente, non di istruzioni in inglese. Un agente può scegliere di applicarlo o rifiutarlo in modo programmatico.
Cosa fa zero explain?
zero explain?zero explain <code> cerca la spiegazione leggibile di un codice di diagnostica stabile come NAM003. È il complemento in prosa della diagnostica JSON: utile quando una persona sta facendo debug, e un modo per un agente di ottenere contesto quando non riconosce il codice dai suoi dati di addestramento.
