Ferramenta de linha de comando da LabelGrid (CLI)

Q: A LabelGrid tem uma ferramenta de linha de comando?

Tem. A LabelGrid publica uma ferramenta de linha de comando oficial como o pacote npm @labelgrid/cli. Instale com npm install -g @labelgrid/cli e ela acrescenta o comando labelgrid ao seu terminal. É necessário Node.js 20 ou mais recente. A CLI é uma camada fina sobre a API pública da LabelGrid, então funciona com as mesmas ações de catálogo, arquivos, analytics e distribuição que a API oferece.

Q: O que dá para fazer com a CLI da LabelGrid?

Você pode entrar na conta e gerenciar tokens; buscar, consultar, criar, atualizar e excluir selos, artistas, compositores, editoras, lançamentos e faixas; enviar áudio, arte, letras e arte em movimento; validar lançamentos, enviá-los para distribuição e tirá-los do ar; puxar extratos, transações, royalties e analytics de streaming; consultar problemas de revisão e relatórios de qualidade; gerenciar webhooks; e gerenciar a habilitação do Beatport. Tudo o que a API pública da LabelGrid permite, a CLI faz; tudo o que a API recusa, a CLI recusa da mesma forma.

Q: Como faço a autenticação da CLI?

A CLI usa um token de API da LabelGrid. Ela procura o token em três lugares, nesta ordem: a variável de ambiente LABELGRID_API_TOKEN, depois uma credencial salva com labelgrid auth login (guardada no Keychain do macOS ou em um arquivo com permissões restritas em ~/.config/labelgrid, em outros sistemas) e, por fim, a flag --token. A CLI nunca imprime o valor dos tokens.

Q: Qual é a diferença entre a CLI e o servidor MCP?

Os dois são ferramentas oficiais da LabelGrid construídas sobre a mesma API pública. A CLI é para o seu terminal e para scripts: você digita comandos ou os executa em automações. O servidor MCP é para assistentes de IA como Claude e Cursor, que fazem as chamadas de API por você em linguagem natural. Use o que se encaixar no seu fluxo de trabalho, ou os dois.

Atualizado em julho de 2026.

A LabelGrid publica uma ferramenta de linha de comando oficial para você trabalhar com a sua conta direto do terminal ou de um script. É o pacote npm @labelgrid/cli, e a instalação acrescenta o comando labelgrid à sua máquina.

A CLI é uma camada fina sobre a API pública da LabelGrid: a mesma superfície, a mesma validação e as mesmas permissões. Tudo o que a API pública permite, a CLI faz; tudo o que a API recusa, a CLI recusa exatamente da mesma forma. Se você prefere trabalhar em linguagem natural com um assistente de IA, a LabelGrid também publica um servidor MCP construído sobre a mesma API.

O que dá para fazer

Os comandos são organizados em grupos. Do seu terminal, você pode:

auth — entrar na conta, sair, ver com qual conta você está conectado e revogar um token
catalog — buscar, consultar, criar, atualizar e excluir selos, artistas, compositores, editoras, lançamentos e faixas
release — validar um lançamento, enviá-lo para distribuição, tirá-lo do ar, confirmar a revisão e gerenciar a sua landing page e o seu link curto
upload — adicionar áudio, arte, letras e arte em movimento (cada tipo aceita somente as extensões de arquivo permitidas)
download, asset, license — recuperar arquivos e gerenciar licenças
statement, transactions, royalties, analytics — puxar extratos, transações, detalhamentos de royalties e analytics de streaming
review — consultar problemas de revisão, ler relatórios de qualidade e adicionar notas
webhook — registrar e gerenciar webhooks para notificações assíncronas
beatport — gerenciar a habilitação do Beatport

O que você precisa ter

Uma conta LabelGrid com acesso à API. O acesso à API faz parte dos planos de API da LabelGrid: veja a Visão geral da API para saber como obtê-lo.
Um token de API. Gere um no seu painel da LabelGrid em Profile → API Tokens.
Node.js 20 ou mais recente no computador em que você executa a CLI.

Instalação

Instale a CLI globalmente com o npm:

npm install -g @labelgrid/cli

Isso acrescenta o comando labelgrid. Confirme que deu certo com:

labelgrid --version

Autenticação

A CLI precisa do seu token de API. Ela procura por um em três lugares, nesta ordem:

A variável de ambiente LABELGRID_API_TOKEN — a melhor opção para scripts e CI.
Uma credencial salva que você guarda uma única vez com labelgrid auth login. No macOS ela fica no Keychain; em outros sistemas, é salva em um arquivo com permissões restritas em ~/.config/labelgrid/.
A flag --token em um comando específico.

Aponte a CLI para uma variável de ambiente:

export LABELGRID_API_TOKEN=your-api-token
labelgrid auth whoami

Ou guarde o token uma vez e deixe a CLI reutilizá-lo:

labelgrid auth login

A CLI nunca imprime o valor dos tokens. Para encerrar o acesso, saia com labelgrid auth logout ou revogue o token no seu painel, o que tem efeito imediato.

Saída e códigos de saída

Por padrão, a CLI imprime uma saída limpa e legível. Para scripts, acrescente --json a qualquer comando e ela imprime a resposta bruta da API, para você encaminhá-la a outras ferramentas:

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

Os comandos usam códigos de saída padrão, para que os seus scripts reajam ao resultado:

Código de saída	Significado
`0`	Sucesso
`1`	Erro de API (a requisição chegou à LabelGrid e foi recusada)
`2`	Erro de uso (um engano no próprio comando)

Segurança

Comandos definitivos e destrutivos pedem confirmação antes de enviar qualquer coisa. Enviar um lançamento para distribuição, tirar um lançamento do ar, confirmar a revisão, excluir itens do catálogo e habilitar o Beatport pedem que você digite y para confirmar antes que a CLI faça qualquer chamada de API.

Em automações, quando não há ninguém no teclado, acrescente --yes para pular a confirmação:

labelgrid release distribute REL123 --yes

Todas as proteções da conta (validação, limites do plano e limites de taxa) são aplicadas pelos servidores da LabelGrid, então a CLI não consegue contorná-las, seja qual for a forma como você a executa.

Solução de problemas

command not found: labelgrid — a instalação global não terminou ou não está no seu PATH. Execute npm install -g @labelgrid/cli de novo e confirme que você tem o Node.js 20 ou mais recente com node --version.
Token inválido ou recusado — recrie o token no seu painel em Profile → API Tokens e defina-o de novo com export LABELGRID_API_TOKEN=... ou labelgrid auth login.
A página “API Tokens” não aparece — a sua conta ainda não tem acesso à API. Veja a Visão geral da API para saber como habilitá-lo.
Um comando falha dentro de um script — verifique o código de saída (1 é erro de API, 2 é erro de uso) e execute o mesmo comando com --json para ler a resposta completa.

Perguntas frequentes

”A LabelGrid tem uma ferramenta de linha de comando?”

Tem. A LabelGrid publica uma CLI oficial como o pacote npm @labelgrid/cli. Instale com npm install -g @labelgrid/cli e ela acrescenta o comando labelgrid ao seu terminal. É necessário Node.js 20 ou mais recente, e ela é uma camada fina sobre a API pública da LabelGrid.

”O que dá para fazer com ela?”

Entrar na conta e gerenciar tokens; buscar, consultar, criar, atualizar e excluir selos, artistas, compositores, editoras, lançamentos e faixas; enviar áudio, arte, letras e arte em movimento; validar lançamentos, enviá-los para distribuição e tirá-los do ar; puxar extratos, transações, royalties e analytics de streaming; consultar problemas de revisão e relatórios de qualidade; gerenciar webhooks; e gerenciar a habilitação do Beatport.

”Como faço a autenticação da CLI?”

Com um token de API da LabelGrid. A CLI o procura em três lugares, nesta ordem: a variável de ambiente LABELGRID_API_TOKEN, depois uma credencial salva com labelgrid auth login e, por fim, a flag --token. A CLI nunca imprime o valor dos tokens.

”Preciso de um plano de API?”

Precisa. A CLI se conecta pela API pública da LabelGrid, então a sua conta precisa de acesso à API, que faz parte dos planos de API da LabelGrid. Veja a Visão geral da API para saber como obter acesso.

”Qual é a diferença entre a CLI e o servidor MCP?”

Os dois são ferramentas oficiais da LabelGrid sobre a mesma API pública. A CLI é para o seu terminal e para scripts; o servidor MCP é para assistentes de IA como Claude e Cursor, que fazem as chamadas de API por você em linguagem natural. Use o que se encaixar no seu fluxo de trabalho, ou os dois.

Relacionados

Visão geral da API — como obter acesso à API e fazer a autenticação
Conecte o seu assistente de IA à LabelGrid (MCP) — as mesmas ações, em linguagem natural
Webhooks — notificações assíncronas de eventos
@labelgrid/cli no npm
Documentação no GitHub — referência da CLI em packages/cli

Precisa de ajuda?

Se você tiver dúvidas sobre a CLI, fale com a nossa equipe de suporte.

Ainda não usa a LabelGrid?

Tudo o que você acabou de ler está disponível na nossa plataforma.

Veja o que a LabelGrid pode fazer →