Ferramenta de linha de comando da LabelGrid (CLI)

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 validação e as mesmas permissões. Todo comando corresponde a uma chamada de API, então tudo o que a API recusa, a CLI recusa exatamente da mesma forma, e nenhum comando da CLI consegue fazer algo que o seu token não tem permissão para fazer. Ela cobre os grupos de comandos listados abaixo, e não todos os endpoints que a API publica: para um canto da API que ainda não tem um comando correspondente, chame o endpoint diretamente. 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

1. 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.
2. Um token de API. Gere um no seu painel da LabelGrid em Profile → API Tokens.
3. 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:

1. A variável de ambiente LABELGRID_API_TOKEN — a melhor opção para scripts e CI, com o valor vindo do cofre de segredos do seu provedor de CI.
2. 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/.
3. A flag --token em um comando específico — o último recurso.

Na sua própria máquina, a opção mais segura é guardar o token uma única vez. Execute labelgrid auth login sem argumentos e ela pede que você cole o token com a digitação oculta, para que o valor nunca apareça na tela nem no histórico do shell:

labelgrid auth login

Todos os comandos seguintes reutilizam a credencial salva, então você não digita o token de novo:

labelgrid auth whoami

Cuidado

Evite colocar o token direto na linha de comando, seja como valor de --token ou em export LABELGRID_API_TOKEN=.... Tudo o que você digita é gravado no arquivo de histórico do shell, e os argumentos da linha de comando ficam visíveis para outros usuários da mesma máquina pela lista de processos. Prefira o labelgrid auth login e, na CI, injete LABELGRID_API_TOKEN a partir do cofre de segredos do provedor em vez de escrevê-lo dentro de um script.

Em uma configuração sem supervisão, em que nada pode pedir a digitação, mande o token para o labelgrid auth login por um pipe a partir de um gerenciador de segredos, em vez de passá-lo como argumento:

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

A CLI nunca imprime o valor dos tokens. Para encerrar o acesso, saia com labelgrid auth logout — o que remove a credencial salva daquela máquina — ou revogue o token no seu painel, o que faz esse token parar de funcionar imediatamente em todo lugar. Os outros tokens da sua conta continuam valendo; revogue um a um os que você quiser aposentar.

Nota

Gere e gerencie tokens no seu painel em Profile → API Tokens. Se essa página não aparecer, a sua conta ainda não tem acesso à API: veja a Visão geral da API.

---

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 guarde-o de novo com 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. Prefira o labelgrid auth login: ele pede o token com a digitação oculta, então o valor nunca chega ao histórico do shell nem à lista de processos. 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

Montando um fluxo de lançamento para um agente de IA?

O projeto no GitHub também traz uma skill de agente pronta que ensina a um assistente de IA todo o fluxo de lançamento usando o servidor MCP e a CLI: veja skills/labelgrid-release.

---

Precisa de ajuda?

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