Strumento da riga di comando di LabelGrid (CLI)

Aggiornato a luglio 2026.

LabelGrid pubblica uno strumento da riga di comando ufficiale così puoi lavorare con il tuo account direttamente dal terminale o da uno script. È il pacchetto npm @labelgrid/cli, e la sua installazione aggiunge un comando labelgrid alla tua macchina.

La CLI è un wrapper leggero sull’API pubblica di LabelGrid: la stessa superficie, la stessa validazione e gli stessi permessi. Tutto ciò che l’API pubblica consente, la CLI può farlo; tutto ciò che l’API rifiuta, la CLI lo rifiuta esattamente allo stesso modo. Se preferisci lavorare in linguaggio naturale con un assistente IA, LabelGrid pubblica anche un server MCP costruito sulla stessa API.

Cosa puoi fare

I comandi sono organizzati in gruppi. Dal tuo terminale puoi:

• auth — accedere, disconnetterti, verificare con quale account sei connesso e revocare un token
• catalog — cercare, visualizzare, creare, aggiornare ed eliminare label, artisti, autori, editori, release e tracce
• release — validare una release, inviarla alla distribuzione, ritirarla, confermare la revisione e gestirne la pagina di destinazione e il link breve
• upload — aggiungere audio, artwork, testi e artwork animati (ogni tipo accetta solo le sue estensioni di file consentite)
• download, asset, license — recuperare file e gestire licenze
• statement, transactions, royalties, analytics — recuperare rendiconti, transazioni, dettagli delle royalty e analisi di streaming
• review — consultare le segnalazioni di revisione, leggere i report di qualità e aggiungere note
• webhook — registrare e gestire i webhook per le notifiche asincrone
• beatport — gestire l’attivazione di Beatport

---

Cosa ti serve

1. Un account LabelGrid con accesso API. L’accesso API fa parte dei piani API di LabelGrid — consulta la panoramica dell’API per sapere come ottenerlo.
2. Un token API. Generane uno nella tua dashboard di LabelGrid sotto Profilo → Token API.
3. Node.js 20 o versione successiva sul computer dove esegui la CLI.

---

Installazione

Installa la CLI a livello globale con npm:

npm install -g @labelgrid/cli

Questo aggiunge il comando labelgrid. Verifica che abbia funzionato con:

labelgrid --version

---

Autenticazione

La CLI ha bisogno del tuo token API. Ne cerca uno in tre punti, in questo ordine:

1. La variabile d’ambiente LABELGRID_API_TOKEN — ideale per script e CI.
2. Una credenziale salvata che memorizzi una volta con labelgrid auth login. Su macOS è conservata nel tuo Portachiavi; sugli altri sistemi è salvata in un file con permessi limitati in ~/.config/labelgrid/.
3. L’opzione --token su un singolo comando.

Punta la CLI a una variabile d’ambiente:

export LABELGRID_API_TOKEN=your-api-token
labelgrid auth whoami

Oppure salva il token una volta e lascia che la CLI lo riutilizzi:

labelgrid auth login

La CLI non stampa mai il valore del token. Per interrompere l’accesso, disconnettiti con labelgrid auth logout o revoca il token dalla tua dashboard, con effetto immediato.

Nota

Genera e gestisci i token nella tua dashboard sotto Profilo → Token API. Se non vedi quella pagina, il tuo account non ha ancora l’accesso API — consulta la panoramica dell’API.

---

Output e codici di uscita

Per impostazione predefinita la CLI stampa un output chiaro e leggibile. Per lo scripting, aggiungi --json a qualsiasi comando e stamperà la risposta grezza dell’API così da poterla incanalare verso altri strumenti:

labelgrid catalog search releases --query "summer" --json

I comandi impostano codici di uscita standard così i tuoi script possono reagire al risultato:

Codice di uscita	Significato
0	Successo
1	Errore dell’API (la richiesta ha raggiunto LabelGrid ed è stata rifiutata)
2	Errore d’uso (un errore nel comando stesso)

---

Sicurezza

I comandi finali e distruttivi ti chiedono conferma prima di inviare qualsiasi cosa. Inviare una release alla distribuzione, ritirare una release, confermare la revisione, eliminare elementi del catalogo e attivare Beatport ti chiedono tutti di digitare y per confermare prima che la CLI effettui qualsiasi chiamata all’API.

Per l’automazione dove nessuno è alla tastiera, aggiungi --yes per saltare la richiesta di conferma:

labelgrid release distribute REL123 --yes

Ogni protezione dell’account — validazione, limiti del piano e limiti di frequenza — è applicata dai server di LabelGrid, quindi la CLI non può aggirarli in nessun modo tu la esegua.

---

Risoluzione dei problemi

• command not found: labelgrid — l’installazione globale non è andata a buon fine o non è nel tuo PATH. Riesegui npm install -g @labelgrid/cli e verifica Node.js 20 o versione successiva con node --version.
• Token non valido o rifiutato — ricrea il token nella tua dashboard sotto Profilo → Token API, poi impostalo di nuovo con export LABELGRID_API_TOKEN=... o labelgrid auth login.
• Non vedi una pagina “Token API” — il tuo account non ha ancora l’accesso API. Consulta la panoramica dell’API per sapere come attivarlo.
• Un comando fallisce in uno script — controlla il codice di uscita (1 è un errore dell’API, 2 è un errore d’uso) e riesegui lo stesso comando con --json per leggere la risposta completa.

---

Domande frequenti

”LabelGrid ha uno strumento da riga di comando?”

Sì. LabelGrid pubblica una CLI ufficiale come il pacchetto npm @labelgrid/cli. Installala con npm install -g @labelgrid/cli e aggiunge un comando labelgrid al tuo terminale. Richiede Node.js 20 o versione successiva ed è un wrapper leggero sull’API pubblica di LabelGrid.

”Cosa posso fare con essa?”

Accedere e gestire i token; cercare, visualizzare, creare, aggiornare ed eliminare label, artisti, autori, editori, release e tracce; caricare audio, artwork, testi e artwork animati; validare le release, inviarle alla distribuzione e ritirarle; recuperare rendiconti, transazioni, royalty e analisi di streaming; consultare segnalazioni di revisione e report di qualità; gestire i webhook; e gestire l’attivazione di Beatport.

”Come autentico la CLI?”

Con un token API di LabelGrid. La CLI lo cerca in tre punti, in questo ordine: la variabile d’ambiente LABELGRID_API_TOKEN, poi una credenziale salvata con labelgrid auth login e infine l’opzione --token. La CLI non stampa mai il valore del token.

”Mi serve un piano API?”

Sì. La CLI si connette tramite l’API pubblica di LabelGrid, quindi il tuo account ha bisogno dell’accesso API, che fa parte dei piani API di LabelGrid. Consulta la panoramica dell’API per sapere come ottenerlo.

”In che cosa la CLI è diversa dal server MCP?”

Entrambi sono strumenti ufficiali di LabelGrid sulla stessa API pubblica. La CLI è pensata per il tuo terminale e i tuoi script; il server MCP è pensato per assistenti IA come Claude e Cursor, che chiamano l’API per te in linguaggio naturale. Usa quello più adatto al tuo flusso di lavoro, o entrambi.

---

Correlati

• Panoramica dell’API — come ottenere l’accesso all’API e autenticarsi
• Collega il tuo assistente IA a LabelGrid (MCP) — le stesse azioni, in linguaggio naturale
• Webhook — notifiche asincrone degli eventi
• @labelgrid/cli su npm
• Documentazione su GitHub — riferimento della CLI in packages/cli

Stai costruendo un flusso di release per un agente IA?

Il progetto GitHub include anche una skill per agenti pronta all’uso che insegna a un assistente IA l’intero flusso di release con il server MCP e la CLI — vedi skills/labelgrid-release.

---

Serve aiuto?

Per domande sulla CLI, contatta il nostro team di assistenza.