Progettare una CLI per agenti AI: JSON, codici di uscita e attesa

Una CLI per agenti AI non è semplicemente uno strumento a riga di comando per esseri umani che può essere chiamato anche da un modello. È un protocollo operativo. L’agente ha bisogno di input deterministici, output strutturati, codici di uscita significativi, categorie di errore stabili e un modo per attendere che l’infrastruttura asincrona raggiunga uno stato finale.

Senza questo contratto, l’agente è costretto a dedurre il successo da frasi come “deployment avviato”. Questa deduzione è pericolosa, perché una richiesta accettata può fallire in seguito durante la build, gli health check, l’avvio del container o il passaggio del traffico.

Perché è pericoloso presumere che un deployment sia riuscito?

La maggior parte delle operazioni infrastrutturali è asincrona. Un’API può accettare un deployment e restituire un ID in pochi millisecondi, mentre la build effettiva richiede diversi minuti. Se un agente segnala il successo al momento dell’accettazione, ogni passaggio successivo si basa su una premessa falsa.

Considera la differenza:

Evento	Cosa dimostra	Cosa non dimostra
Richiesta accettata	La piattaforma ha compreso la richiesta	Che il codice sia stato compilato
Build completata	È stata creata un’immagine o un artifact	Che l’app sia stata avviata
Health gate superato	La nuova istanza ha risposto come richiesto	Che i flussi business funzionino
Traffico trasferito	La release è diventata attiva	Che rimarrà in salute
Osservazione dell’uptime	Il servizio continua a essere raggiungibile	Che ogni funzionalità sia corretta

Un essere umano può notare la differenza in una dashboard. Un agente che opera tramite testo ha bisogno che questa distinzione sia codificata nell’interfaccia.

Il contratto dei comandi di Dockup separa l’accodamento dal completamento. Un deploy senza --wait restituisce immediatamente waited:false; un deploy con --wait resta in attesa fino a esito positivo, errore o timeout:

dockup deploy production/api --wait --json

Il timeout predefinito è di 900 secondi. Il comando restituisce 0 solo dopo il raggiungimento di uno stato terminale positivo. Restituisce un valore diverso da zero con deploy_failed o deploy_timeout quando il risultato non è positivo.

Cosa offre a un agente AI una CLI con JSON strutturato?

Il JSON strutturato sostituisce l’interpretazione della prosa con campi denominati. L’agente può individuare direttamente status, deploymentId, target o code, senza dipendere da punteggiatura, colori, larghezza delle colonne o formulazioni testuali.

Un risultato positivo può essere utilizzato come dato:

{
  "ok": true,
  "target": "production/api",
  "deploymentId": "dep_123",
  "waited": true,
  "status": "success",
  "durationMs": 142381,
  "url": "https://api.dockup.tech"
}

Un errore utilizza la stessa struttura di trasporto:

{
  "ok": false,
  "error": "Deployment failed",
  "code": "deploy_failed"
}

La regola di progettazione fondamentale è che il JSON venga scritto su stdout, mentre gli avvisi che non devono interferire con il parsing vengano inviati su stderr. I log in modalità follow usano NDJSON, cioè un oggetto JSON per riga, così il chiamante può elaborare il flusso progressivamente senza dover attendere un unico array di grandi dimensioni.

Dockup applica --json all’intera superficie dei comandi. Con 135 comandi, richiedere a un agente di dedurre i flag dalla memoria sarebbe fragile. La reference della CLI e la skill distribuita forniscono le istruzioni sui comandi allineate alla versione che l’agente deve seguire.

La proprietà progettuale importante non è la scoperta intelligente. È che l’agente riceva indicazioni operative aggiornate e strutturate, senza inventare un flag a partire da un prompt obsoleto.

In che modo i codici di uscita reali controllano l’automazione dei deployment?

Il codice di uscita del sistema operativo è il segnale di successo più portabile disponibile per gli script shell, i runner CI e gli agenti di coding. L’uscita 0 significa che il comando ha raggiunto il risultato definito. Un valore diverso da zero significa che il chiamante deve passare al recupero, all’escalation o all’interruzione.

Questo frammento shell è volutamente semplice:

if dockup deploy production/api --wait --json > result.json; then
  echo "deployment reached success"
else
  dockup logs production/api --build --json
  exit 1
fi

Non cerca la parola “success” nello stdout. Non presume che una risposta HTTP 202 significhi che la produzione sia pronta. Delega la definizione di successo alla CLI e propaga l’errore al processo padre.

I codici di uscita reali sono altrettanto importanti per i comandi one-shot eseguiti all’interno di un container. Il comando PRO exec di Dockup restituisce stdout, stderr e il codice di uscita effettivo del comando:

dockup exec "npm run migrate" \
  -s production/api \
  --json

Un agente può quindi distinguere una migrazione completata da un comando che si è limitato ad avviarsi. Questo è un principio fondamentale degli strumenti di protezione per la produzione degli agenti AI.

In che modo l’attesa dello stato terminale sostituisce il polling fragile?

I loop di polling scritti manualmente introducono decisioni implicite sulla policy: con quale frequenza eseguire il polling, quali stati siano terminali, per quanto tempo attendere, se un errore di rete temporaneo debba azzerare il timer e come comportarsi quando un container viene riavviato.

È particolarmente probabile che un agente prenda decisioni errate, perché potrebbe non conoscere l’intera macchina a stati della piattaforma. La piattaforma dovrebbe gestire direttamente la semantica dell’attesa.

Dockup offre due pattern utili:

dockup deploy production/api --wait --timeout 1800 --json
dockup push --json

deploy --wait attende esplicitamente. push attende per impostazione predefinita dopo il push e l’avvio della release; --no-wait consente di disattivare questo comportamento. Entrambi restituiscono un codice di uscita che riflette il risultato terminale.

Anche il follow dei log segue la stessa idea:

dockup logs production/api --build -f --json

Il flusso termina quando la build raggiunge un esito positivo o negativo. Un oggetto NDJSON finale indica done:true e una build fallita termina con un codice diverso da zero. Il chiamante non deve implementare un secondo meccanismo di polling.

Per verificare la disponibilità dell’applicazione dopo il deployment, il comando uptime di Dockup restituisce controlli a livello di minuto, tempo medio di risposta e p95:

dockup uptime production/api --hours 24 --json

Attesa e monitoring sono concetti distinti. --wait risponde alla domanda se questo deployment abbia raggiunto un risultato terminale; uptime indica come si è comportato nel tempo il servizio in esecuzione.

Quali codici di errore dovrebbe comprendere un agente?

Categorie di errore stabili consentono a un agente di intraprendere un’azione circoscritta senza interpretare ogni possibile messaggio. Dockup espone codici come:

Codice di errore	Significato	Risposta sicura dell’agente
not_logged_in	Nessun token utilizzabile	Interrompere e richiedere l’autenticazione
not_linked	Nessun target .dockup per push	Risolvere il target o passarlo esplicitamente
no_target	Impossibile identificare il servizio	Eseguire services --json
needs_confirm	L’azione distruttiva non dispone dell’approvazione	Chiedere a un essere umano
deploy_trigger_failed	Impossibile avviare il deployment	Segnalare l’errore dell’API
deploy_failed	La build o il deployment hanno raggiunto uno stato di errore	Leggere i build log
deploy_timeout	L’operazione è ancora in corso oltre il limite di attesa	Segnalare l’incertezza o estendere intenzionalmente il limite

Il messaggio di errore rimane utile come contesto, ma è il codice a guidare il primo ramo della logica. L’automazione rimane così resistente a formulazioni più chiare o alla localizzazione.

Anche la conferma fa parte del protocollo. Un comando distruttivo non dovrebbe procedere silenziosamente perché il chiamante è non interattivo. Dockup rifiuta queste operazioni senza --yes e restituisce needs_confirm. Un agente autonomo visualizza una richiesta, non un ostacolo da aggirare.

Il modello di sicurezza è descritto più approfonditamente nelle best practice di sicurezza.

Qual è il contratto minimo per una CLI pronta per la produzione?

Una CLI per agenti AI pronta per la produzione dovrebbe rispettare un contratto ridotto ma rigoroso:

1. Ogni operazione di lettura e scrittura dispone di output leggibile dalle macchine.
2. Un errore produce un’uscita del processo diversa da zero.
3. Le mutazioni asincrone possono attendere uno stato terminale documentato.
4. I valori segreti non vengono mai restituiti dai comandi di lettura.
5. Le azioni distruttive richiedono una conferma esplicita.
6. Gli errori hanno codici stabili adatti ai branching.
7. Il pacchetto CLI e le istruzioni dell’agente rimangono allineati alla versione.
8. Le mutazioni vengono registrate in un audit trail.

La skill di Dockup trasforma queste regole in comportamento predefinito per Claude Code e Codex. Indica all’agente di usare JSON, autenticarsi con DOCKUP_TOKEN, individuare i target esatti, eseguire il deploy con --wait, proteggere le credenziali e interrompersi in presenza di needs_confirm.

Confronta questo modello con i concetti più generali descritti in skill per agenti vs MCP. Una skill fornisce conoscenze operative; la CLI rimane l’interfaccia eseguibile il cui stato di uscita e il cui output definiscono la realtà.

Una matrice di test per un comando rivolto agli agenti

Prima di esporre un comando infrastrutturale a un agente, testa più del semplice happy path:

Test	Comportamento previsto
Richiesta valida	Risultato JSON e uscita 0
Token non valido	Codice di autenticazione stabile e uscita diversa da zero
Target sconosciuto	Codice target stabile e nessuna mutazione
Deploy di lunga durata	Attende fino allo stato terminale o al timeout
Deploy fallito	Uscita diversa da zero più deployment ID diagnosticabile
Approvazione distruttiva mancante	needs_confirm, nessuna eliminazione
Lettura di un segreto	Metadati della chiave visibili, valore oscurato
Avviso durante l’output JSON	Avviso su stderr, JSON valido su stdout

Questa matrice è più preziosa di uno spinner di avanzamento ben rifinito. La formattazione per gli esseri umani può essere aggiunta in un secondo momento; un contratto deterministico per le macchine non può essere ricostruito a posteriori.

La documentazione della CLI di Dockup mostra i comandi concreti alla base di questo modello, mentre sviluppo basato sull’AI illustra il passaggio più ampio dall’uso manuale degli strumenti ai workflow diretti dagli agenti.

Considera l’observability parte del contratto del comando

Una mutazione rivolta a un agente dovrebbe restituire identificatori che rendano possibili le analisi successive. Una risposta di deployment deve contenere il target e il deployment ID; un database creato deve avere uno slug stabile; uno snapshot di un volume deve avere il proprio snapshot ID. Senza questi riferimenti, l’agente può descrivere un evento, ma non può ispezionarlo, riprovare l’operazione o annullarla in modo affidabile.

L’audit trail completa il contratto. L’output strutturato descrive una singola invocazione, mentre i record di audit collegano più invocazioni nel tempo. Insieme consentono agli operatori di verificare se l’agente ha agito sulla risorsa prevista e se un successivo comando di ripristino si riferiva allo stesso evento di produzione.

Mantieni l’interfaccia semplice

Una CLI per agenti AI affidabile dovrebbe comportarsi in modo prevedibile in caso di successo, errore, timeout e retry.

Test finale dell’interfaccia

La CLI per agenti AI deve fallire in modo veritiero.

Porta il workflow in produzione

Testa prima il contratto da una shell: verifica il parsing del JSON, un’uscita positiva, un errore forzato, un timeout e un’operazione distruttiva bloccata, prima di delegare l’accesso alla produzione.

npm install -g dockup-cli
dockup skill install

Il primo comando installa la CLI. Il secondo installa la skill di Dockup corrispondente per Claude Code e Codex. Inizia gratuitamente su app.dockup.ai.

FAQ

Cosa rende una CLI adatta agli agenti AI?

Sono necessari output strutturati, codici di uscita reali, attesa dello stato terminale, codici di errore stabili, oscuramento dei segreti e conferme esplicite per le operazioni distruttive.

Perché il JSON è migliore dell’output CLI formattato per gli esseri umani quando si lavora con gli agenti?

Il JSON fornisce nomi e tipi di campo stabili. L’agente non deve dedurre il significato da colori, tabelle, punteggiatura o prosa variabile.

Perché una richiesta di deployment accettata non equivale a un successo?

L’accettazione dimostra solo che la piattaforma ha accodato l’operazione. La build, l’avvio, l’health gate e il passaggio del traffico successivi possono ancora fallire.

Qual è il timeout predefinito di attesa per i deployment di Dockup?

Il timeout predefinito per dockup deploy --wait è di 900 secondi e può essere modificato con l’opzione documentata --timeout.

Come dovrebbe reagire un agente a needs_confirm?

Dovrebbe interrompersi e chiedere un’approvazione esplicita. Il codice indica che l’azione richiesta è distruttiva e non è stata eseguita intenzionalmente.