Cloudflare Wrangler e cf CLI: guida pratica alla nuova beta

Il vantaggio concreto non è un comando più corto, ma meno lavoro di integrazione. Un founder può controllare un account senza perdersi nella dashboard, un platform team può fornire a un agente risultati leggibili dalle macchine e un'agenzia può uniformare le attività Cloudflare per tutti i clienti senza mantenere un wrapper API distinto per ogni prodotto.

Non occorre acquistare una licenza separata per cf. Il repository è open source, un piccolo Worker può partire dal piano Free di Cloudflare e Workers Paid prevede un minimo mensile di $5. All'estremo opposto del budget, una piattaforma generale per la governance dell'infrastruttura come Spacelift propone il piano Starter+ da $20,000. cf elimina buona parte del lavoro necessario per collegare le API tra questi due estremi. Non sostituisce però approvazioni, audit trail o una gestione attenta dei permessi.

Che cos'è davvero la nuova Cloudflare CLI

cf offre un'interfaccia a comandi generata per l'intera API Cloudflare, affiancata da workflow progettati a mano per creare, compilare, migrare e distribuire i Worker. Cloudflare Wrangler è come un banco da lavoro specializzato e ben attrezzato per i Worker. cf aggiunge l'indice e lo sportello di servizio per l'intero ecosistema Cloudflare, continuando ad affidare a Wrangler alcune attività sui Worker quando rimane lo strumento più affidabile.

È anche ciò che distingue questa release dall'anteprima tecnica del 13 aprile. La versione di aprile copriva soltanto un piccolo sottoinsieme di prodotti. L'open beta di settembre introduce la copertura completa delle API, risultati JSON predefiniti, ricerca dei comandi, configurazione TypeScript dei Worker e Vite come percorso predefinito per i Worker.

I quattro elementi che cambiano il workflow sono semplici:

• Copertura completa delle API: i comandi generati seguono lo schema cf <product> [group…] <operation> per più di 3,000 operazioni.
• Ricerca dei comandi: cf cli search riceve un'attività descritta in linguaggio naturale e restituisce cinque corrispondenze JSON ordinate per rilevanza. Non occorre memorizzare l'albero dei comandi.
• JSON predefinito: i risultati strutturati delle API vengono inviati allo standard output come JSON ben formattato, così una persona, uno script o un coding agent possono filtrare la stessa risposta.
• Configurazione tipizzata dei Worker: cloudflare.config.ts offre a editor e coding agent il feedback di TypeScript. Oggi si parte dai Worker. Estendere la configurazione all'intero account, inclusi DNS, zone e policy, è una direzione futura, non una funzione già disponibile.

Installare la Cloudflare CLI, autenticarsi e verificare una lettura

Conviene iniziare con un'operazione di sola lettura. In questo modo si verificano pacchetto, credenziali, selezione dell'account, individuazione del comando e percorso JSON prima di consentire a uno script di modificare qualcosa.

Il pacchetto ufficiale richiede Node.js 22 o versioni successive. Per chi lavora da terminale, cf auth login gestisce il profilo OAuth predefinito. In CI va invece impostato un CLOUDFLARE_API_TOKEN con autorizzazioni limitate: cf controlla questa variabile d'ambiente prima di qualsiasi profilo OAuth salvato. Quando si opera su account di clienti o aziende diversi, è possibile creare profili denominati e associarli a directory differenti.

Il testo passato a cf cli search deve restare generico. Va indicata l'azione e il tipo di risorsa, non un dominio, un indirizzo email, un ID account o un token.

node --version
npm i -g cf
cf --version

cf auth login
cf auth whoami

cf cli search "list zones in an account"
cf zones list | jq -e 'type == "array" and all(.[]; has("name") and has("status"))'

Per questa attività, la ricerca colloca attualmente cf zones list al primo posto. L'ultima riga è la verifica effettiva: esegue una chiamata API di sola lettura e termina con successo soltanto se il risultato è un array JSON le cui voci contengono name e status. In presenza di più account, si può selezionare un profilo denominato con --profile oppure filtrare il comando con --account-id.

Un token non va incollato nella cronologia della shell. È meglio inserire un token con scope limitato nell'ambiente del processo usato dalla CI e concedergli solo i permessi di lettura o scrittura indispensabili. Per una sessione individuale da terminale, OAuth è la scelta più comoda perché cf può aggiornare il profilo selezionato.

Che cosa ha dimostrato il test usa e getta

Il 29 settembre, un'installazione nuova e isolata ha restituito cf v1.0.0-beta.5. La ricerca dei comandi ha prodotto un array JSON valido di cinque elementi, cf init ha creato un progetto Worker tipizzato e sia il nuovo progetto sia una fixture Vite migrata sono stati compilati in locale. Nell'ambiente non erano presenti le credenziali di un account Cloudflare di test, quindi né la lettura autenticata delle zone né un deployment figurano come test completati.

Questo limite è importante. Una build locale riuscita dimostra che il percorso del progetto funziona. Non dimostra che il token disponga delle autorizzazioni di produzione corrette o che un deployment abbia raggiunto Cloudflare.

Creare un piccolo Worker e controllare il risultato di cf

cf init è il test pulito più rapido per il nuovo workflow di progetto. In una directory vuota crea il sorgente TypeScript, cloudflare.config.ts, vite.config.ts, gli script del pacchetto e i tipi Worker generati. cf build passa poi il lavoro al Cloudflare Vite Plugin e produce un Build Output standardizzato.

cf init hello-cf --package-manager npm
cd hello-cf
npm run build

# In a copied existing Vite Worker:
cf migrate --dry-run
cf migrate
npm run build

Dopo entrambi i percorsi, va aperto cloudflare.config.ts. Per un Worker di base, ci si aspetta un blocco worker con nome, data di compatibilità, entrypoint e binding tipizzati. Un binding di testo viene dichiarato tramite l'API di configurazione, senza copiarlo in diversi blocchi di ambiente. È qui che TypeScript mostra il suo valore: un campo scritto male può generare un avviso nell'editor prima di causare un deployment fallito.

La configurazione Vite generata non è un elemento decorativo. Vite è ora il percorso predefinito di sviluppo locale e build per cf, e Cloudflare consiglia il relativo plugin sia per i frontend sia per le API backend. Nel progetto usa e getta, npm run build ha delegato il lavoro a Vite e si è concluso correttamente. Il deployment è stato escluso di proposito. Una volta completati revisione e test sull'account, il comando documentato cf deploy esegue per impostazione predefinita build e upload.

Quando serve ancora Cloudflare Wrangler

Non conviene rimuovere Wrangler appena cf viene installato correttamente. La decisione sulla migrazione dipende dal percorso di build del progetto.

Per un Worker Vite esistente, cf migrate può convertire una configurazione Wrangler in formato JSON, JSONC o TOML in cloudflare.config.ts. Il comando rileva il Cloudflare Vite Plugin accanto alla configurazione Wrangler e sceglie il percorso Vite. Se il plugin non è dichiarato, le attuali release beta scelgono invece il bundler di Wrangler. Prima di intervenire sul progetto di lavoro, è bene eseguire l'anteprima, leggere ogni attività successiva e migrare una copia o un branch pulito.

Per i Worker JavaScript che dipendono ancora dal comportamento esbuild di Wrangler, cf delega a Wrangler sviluppo e deployment. Lo stesso vale per i Worker Rust e Python. È una scelta di compatibilità, non una migrazione fallita: il team usa cf come porta d'ingresso, mentre nel workflow rimane il sistema di build già collaudato.

Anche la finestra di supporto Cloudflare può essere interpretata male. La manutenzione di Wrangler è prevista per 18 mesi dopo la fine dell'open beta, non per 18 mesi dal lancio del 28 settembre. Non c'è quindi alcun motivo per imporre questa settimana la conversione a Vite di un progetto Rust, Python o esbuild.

Sette workflow da cui partire

I casi d'uso iniziali più efficaci hanno un tratto comune: eliminano ricerche e formattazioni ripetitive senza concedere fin dal primo giorno autorizzazioni di scrittura troppo ampie.

1. Un'agenzia uniforma i controlli sugli account

Chi lavora in agenzia può associare un profilo OAuth denominato alla directory di ogni cliente, cercare il comando di lettura necessario e inviare sempre lo stesso formato JSON a uno script di revisione. Si riducono così le differenze introdotte quando un tecnico usa le dashboard e un altro mantiene un comando curl personalizzato. Il vantaggio è la ripetibilità del lavoro tra clienti, in particolare per DNS, zone, impostazioni degli account e verifiche di sicurezza.

2. Un platform team offre ai coding agent un'interfaccia Cloudflare sicura

Un platform lead può definire in AGENTS.md una regola per cf cli search, autorizzare in modo predefinito i comandi di lettura e richiedere l'approvazione umana per le modifiche. La ricerca evita che l'agente ipotizzi una vecchia sintassi Wrangler, mentre il JSON mantiene l'output compatto e filtrabile. Questo approccio è particolarmente utile se il team chiede già agli agenti di controllare stato delle build, log, code o risorse dell'account e desidera un'unica interfaccia prevedibile.

3. Un tecnico di reperibilità raccoglie il contesto di un incidente

Durante un incidente, l'operatore può cercare la lettura corretta per log, zone, ruleset o dati analitici, invece di passare tra diversi pannelli di prodotto. Il comando esatto continua a essere importante e le autorizzazioni restano valide, ma la fase di individuazione è locale e la risposta è già pronta per jq. Per i team che eseguono attività come Cloudflare Browser Run, questo accorcia il percorso tra un job fallito e lo stato dell'account che lo circonda.

4. Un founder avvia un Worker senza progettare la toolchain

Chi sta creando un webhook, un servizio di redirect o una piccola API interna può eseguire cf init, controllare Worker e binding generati e usare la build Vite senza dover scegliere ogni pacchetto separatamente. Il progetto può iniziare con Workers Free. Se serve il piano a pagamento, il minimo attuale è $5 per account al mese. Il vantaggio è un percorso breve verso un artefatto locale verificabile, non la promessa che le attività di produzione diventino gratuite.

5. Un team Vite converte la configurazione senza riscrivere l'app

Un team di sviluppo con un Worker basato su Vite può eseguire cf migrate --dry-run su una copia, controllare il TypeScript generato e quindi compilare prima di cambiare il deployment. È particolarmente utile quando i blocchi di ambiente sono diventati ripetitivi. Il nuovo formato può calcolare la configurazione a partire da una base condivisa, ma il team deve migrare il comportamento, non soltanto la sintassi del file.

6. Un team dati o operations inserisce le letture Cloudflare nei report

Poiché i risultati strutturati sono JSON per impostazione predefinita, un operatore può inviare una lettura a jq, a un loader per il data warehouse o a un report pianificato senza dover analizzare una tabella Unicode. Il vantaggio aziendale è volutamente poco spettacolare: meno adattatori di output e meno regole di parsing fragili. Va usato un token di lettura con scope limitato, evitando di esporre l'output del comando nei log pubblici della CI.

7. Un team che sviluppa Worker controlla le risorse locali prima della produzione

I comandi supportati accettano --local e comunicano con un'istanza Miniflare di breve durata basata sullo stato locale. Sono incluse le operazioni definite per KV, D1 e R2. Se non esiste un equivalente locale, cf restituisce un errore invece di passare silenziosamente alla produzione. Un team che sviluppa un Cloudflare AI Search Worker può sfruttare questo confine per provare i dati locali di supporto senza trasformare un comando di sviluppo in una scrittura remota.

Due prodotti da costruire intorno a cf

L'opportunità di prodotto non è la CLI in sé, ma il livello di controllo ancora necessario ai team per gestire una superficie API così ampia.

Opportunità migliore: controllo delle modifiche Cloudflare per le agenzie

Si può creare un livello mirato di approvazione e raccolta delle evidenze per agenzie o piccoli platform team che gestiscono più account Cloudflare. L'utente propone una modifica a DNS, zone, WAF o Worker; il prodotto usa cf per acquisire lo stato JSON corrente, mostra una differenza comprensibile, richiede l'approvazione, esegue l'operazione con un profilo dallo scope limitato e conserva il risultato.

Il segnale di domanda è contenuto ma commerciale: cloudflare dns management riceve circa 170 ricerche mensili negli Stati Uniti, ha un CPC di $6 e offerte per la parte alta della pagina comprese tra $3.85 e $36.64. Anche la governance generale dell'infrastruttura sostiene budget reali. Spacelift propone Starter+ a $20,000. Un prodotto specifico per Cloudflare può essere più economico e facile da adottare, perché non deve governare ogni cloud.

La versione minima vendibile è una GitHub app o una coda di revisione in hosting per le modifiche a DNS e Worker, con isolamento dei profili, allowlist dei comandi, JSON prima e dopo l'operazione e rollback con un clic dove l'API sottostante lo consente. Il punto critico è la difendibilità: cf fornisce già la copertura dei comandi, quindi il valore difficile da replicare risiede in policy, evidenze, permessi e workflow per le agenzie. Un semplice wrapper grafico sarebbe copiato rapidamente.

Funzione utile: valutazione della migrazione dei Worker

Un possibile scanner può classificare un repository come Vite nativo, esbuild gestito da Wrangler, Python o Rust, quindi eseguire l'anteprima sicura della migrazione e trasformare le attività successive in una checklist per la pull request. I clienti sono team con un portafoglio di Worker, non uno sviluppatore indipendente che deve migrare un solo piccolo progetto.

La domanda è troppo ridotta perché questa funzione possa sostenere un'intera azienda. cloudflare worker deployment riceve circa 10 ricerche mensili negli Stati Uniti, anche se la query ha intento transazionale. L'MVP più sensato è una funzione a pagamento all'interno di un prodotto per le operations Cloudflare o di un servizio di migrazione: analisi del repository, cf migrate --dry-run, verifica della build e un report chiaro sul fallback a Wrangler. Il limite è la velocità delle release durante la beta. Lo scanner deve seguire attentamente le versioni di cf e Cloudflare Vite Plugin, altrimenti i suoi consigli invecchieranno più in fretta dei progetti analizzati.

Limiti e decisione pratica

cf è già adatto alla ricerca dei comandi, alle letture degli account in JSON, ai nuovi Worker Vite e alle prove di migrazione eseguite con cautela. Cloudflare Wrangler va mantenuto dove cf delega il lavoro, mentre le scritture in produzione devono restare protette da scope espliciti e revisione.

L'open beta non rende ancora cloudflare.config.ts una fonte di verità per l'intero account: il punto di partenza sono i Worker. Inoltre, non trasforma automaticamente ogni operazione delle API Cloudflare in un workflow aziendale sicuro. La copertura completa delle API amplia ciò che un token può raggiungere; per questo privilegio minimo e revisione dei comandi diventano più importanti, non meno.

L'opzione locale è volutamente circoscritta. Le operazioni supportate per KV, D1, R2, Durable Object e Workflow possono usare lo stato locale, ma un'operazione senza equivalente nel local explorer restituisce un errore. È una buona proprietà di sicurezza, ma significa che --local non è una replica offline universale di Cloudflare.

Infine, le release beta evolvono rapidamente. Nei progetti di team conviene fissare la versione di cf tra le dipendenze, controllare la configurazione generata e fare in modo che la CI usi la versione locale del progetto. Un'installazione globale è comoda per esplorare; una versione bloccata garantisce lo stesso comportamento a tutti i collaboratori.

Per progettare e realizzare un percorso sicuro di automazione Cloudflare per il proprio team, sono disponibili i servizi dedicati ai sistemi di IA in produzione.