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 validazione e gli stessi permessi. Ogni comando corrisponde a una chiamata all’API, quindi tutto ciò che l’API rifiuta, la CLI lo rifiuta esattamente allo stesso modo, e nessun comando della CLI può fare qualcosa che il tuo token non è autorizzato a fare. Copre i gruppi di comandi elencati qui sotto, non tutti gli endpoint pubblicati dall’API: per un angolo dell’API che non ha ancora un comando corrispondente, chiama direttamente l’endpoint. 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, dove il valore arriva dal gestore di segreti del tuo provider 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 — l’ultima risorsa.

Sul tuo computer l’opzione più sicura è memorizzare il token una volta sola. Esegui labelgrid auth login senza argomenti: ti chiede di incollare il token con l’inserimento nascosto, così il valore non compare mai a schermo né nella cronologia della shell:

labelgrid auth login

Ogni comando successivo riutilizza la credenziale salvata, quindi non devi più digitare il token:

labelgrid auth whoami

Attenzione

Evita di mettere il token direttamente sulla riga di comando, come valore di --token o in export LABELGRID_API_TOKEN=.... Tutto ciò che digiti finisce nel file di cronologia della shell, e gli argomenti della riga di comando sono visibili agli altri utenti della stessa macchina attraverso l’elenco dei processi. Usa piuttosto labelgrid auth login e, in CI, inietta LABELGRID_API_TOKEN dal gestore di segreti del provider invece di scriverlo dentro uno script.

Per una configurazione non presidiata, dove nulla può chiedere un input, passa il token a labelgrid auth login in pipe da un gestore di segreti invece di indicarlo come argomento:

my-secret-manager read labelgrid-token | labelgrid auth login

La CLI non stampa mai il valore del token. Per interrompere l’accesso, disconnettiti con labelgrid auth logout — che rimuove la credenziale salvata da quella macchina — oppure revoca il token dalla tua dashboard: quel token smette immediatamente di funzionare ovunque. Gli altri token del tuo account continuano a funzionare; revoca uno per uno quelli che vuoi ritirare.

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 salvalo di nuovo con 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. Meglio usare labelgrid auth login: chiede il token con l’inserimento nascosto, così il valore non arriva mai nella cronologia della shell né nell’elenco dei processi. 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.