Herramienta de línea de comandos de LabelGrid (CLI)

Actualizado en julio de 2026.

LabelGrid publica una herramienta de línea de comandos oficial para que pueda trabajar con su cuenta directamente desde el terminal o desde un script. Es el paquete npm @labelgrid/cli, y su instalación añade un comando labelgrid a su máquina.

La CLI es un envoltorio ligero sobre la API pública de LabelGrid: la misma validación y los mismos permisos. Cada comando se corresponde con una llamada a la API, así que todo lo que la API rechaza, la CLI lo rechaza exactamente igual, y ningún comando de la CLI puede hacer algo que su token no tenga permitido. Cubre los grupos de comandos que se enumeran más abajo, no todos los endpoints que publica la API; para un rincón de la API que aún no tenga un comando equivalente, llame directamente al endpoint. Si prefiere trabajar en lenguaje natural con un asistente de IA, LabelGrid también publica un servidor MCP construido sobre la misma API.

Qué puede hacer

Los comandos están organizados en grupos. Desde su terminal puede:

• auth — iniciar sesión, cerrar sesión, comprobar con qué cuenta está conectado y revocar un token
• catalog — buscar, ver, crear, actualizar y eliminar sellos, artistas, autores, editores, lanzamientos y pistas
• release — validar un lanzamiento, enviarlo a distribución, retirarlo, confirmar la revisión y gestionar su página de destino y su enlace corto
• upload — añadir audio, portadas, letras y portadas animadas (cada tipo solo acepta sus extensiones de archivo permitidas)
• download, asset, license — recuperar archivos y gestionar licencias
• statement, transactions, royalties, analytics — obtener declaraciones, transacciones, desgloses de regalías y analíticas de streaming
• review — consultar incidencias de revisión, leer informes de calidad y añadir notas
• webhook — registrar y gestionar webhooks para notificaciones asíncronas
• beatport — gestionar la activación de Beatport

---

Qué necesita

1. Una cuenta de LabelGrid con acceso a la API. El acceso a la API forma parte de los planes de API de LabelGrid — vea la visión general de la API para saber cómo obtenerlo.
2. Un token de API. Genérelo en su panel de LabelGrid en Perfil → Tokens de API.
3. Node.js 20 o superior en el equipo donde ejecuta la CLI.

---

Instalación

Instale la CLI de forma global con npm:

npm install -g @labelgrid/cli

Esto añade el comando labelgrid. Compruebe que funcionó con:

labelgrid --version

---

Autenticación

La CLI necesita su token de API. Lo busca en tres lugares, en este orden:

1. La variable de entorno LABELGRID_API_TOKEN — ideal para scripts y CI, donde el valor procede del almacén de secretos de su proveedor de CI.
2. Una credencial guardada que almacena una vez con labelgrid auth login. En macOS se guarda en su Llavero; en otros sistemas se guarda en un archivo con permisos restringidos en ~/.config/labelgrid/.
3. La opción --token en un comando concreto — el último recurso.

En su propia máquina, lo más seguro es guardar el token una sola vez. Ejecute labelgrid auth login sin argumentos y le pedirá que pegue el token con la entrada oculta, de modo que el valor no aparece en pantalla ni en el historial de su shell:

labelgrid auth login

Todos los comandos posteriores reutilizan la credencial guardada, así que no vuelve a escribir el token:

labelgrid auth whoami

Precaución

Evite poner el token directamente en una línea de comandos, ya sea como valor de --token o en export LABELGRID_API_TOKEN=.... Todo lo que escribe queda registrado en el archivo de historial de su shell, y los argumentos de la línea de comandos son visibles para otros usuarios de la misma máquina a través de la lista de procesos. Use preferentemente labelgrid auth login y, en CI, inyecte LABELGRID_API_TOKEN desde el almacén de secretos del proveedor en lugar de escribirlo en un script.

Para una configuración desatendida, en la que nada puede pedir datos por pantalla, canalice el token hacia labelgrid auth login desde un gestor de secretos en lugar de pasarlo como argumento:

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

La CLI nunca muestra el valor del token. Para cortar el acceso, cierre sesión con labelgrid auth logout — lo que elimina la credencial guardada de esa máquina — o revoque el token desde su panel, lo que impide de inmediato que ese token funcione en cualquier sitio. Los demás tokens de su cuenta siguen funcionando; revoque uno a uno los que quiera retirar.

Nota

Genere y gestione los tokens en su panel en Perfil → Tokens de API. Si no ve esa página, su cuenta aún no tiene acceso a la API — vea la visión general de la API.

---

Salida y códigos de salida

De forma predeterminada, la CLI imprime una salida clara y legible. Para scripting, añada --json a cualquier comando y mostrará la respuesta cruda de la API para que pueda canalizarla hacia otras herramientas:

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

Los comandos establecen códigos de salida estándar para que sus scripts puedan reaccionar al resultado:

Código de salida	Significado
0	Éxito
1	Error de la API (la petición llegó a LabelGrid y fue rechazada)
2	Error de uso (un fallo en el propio comando)

---

Seguridad

Los comandos finales y destructivos le piden confirmación antes de enviar nada. Enviar un lanzamiento a distribución, retirarlo, confirmar la revisión, eliminar elementos del catálogo y activar Beatport le piden escribir y para confirmar antes de que la CLI haga cualquier llamada a la API.

Para automatizaciones en las que no hay nadie ante el teclado, añada --yes para omitir la confirmación:

labelgrid release distribute REL123 --yes

Todas las protecciones de la cuenta — validación, límites del plan y límites de peticiones — las aplican los servidores de LabelGrid, así que la CLI no puede eludirlas de ninguna forma.

---

Solución de problemas

• command not found: labelgrid — la instalación global no terminó o no está en su PATH. Vuelva a ejecutar npm install -g @labelgrid/cli y confirme Node.js 20 o superior con node --version.
• Token no válido o rechazado — vuelva a crear el token en su panel en Perfil → Tokens de API y guárdelo de nuevo con labelgrid auth login.
• No ve una página de “Tokens de API” — su cuenta aún no tiene acceso a la API. Vea la visión general de la API para saber cómo activarlo.
• Un comando falla en un script — revise el código de salida (1 es un error de la API, 2 es un error de uso) y vuelva a ejecutar el mismo comando con --json para leer la respuesta completa.

---

Preguntas frecuentes

”¿Tiene LabelGrid una herramienta de línea de comandos?”

Sí. LabelGrid publica una CLI oficial como el paquete npm @labelgrid/cli. Instálela con npm install -g @labelgrid/cli y añade un comando labelgrid a su terminal. Requiere Node.js 20 o superior y es un envoltorio ligero sobre la API pública de LabelGrid.

”¿Qué puedo hacer con ella?”

Iniciar sesión y gestionar tokens; buscar, ver, crear, actualizar y eliminar sellos, artistas, autores, editores, lanzamientos y pistas; subir audio, portadas, letras y portadas animadas; validar lanzamientos, enviarlos a distribución y retirarlos; obtener declaraciones, transacciones, regalías y analíticas de streaming; consultar incidencias de revisión e informes de calidad; gestionar webhooks; y gestionar la activación de Beatport.

”¿Cómo autentico la CLI?”

Con un token de API de LabelGrid. La CLI lo busca en tres lugares, en este orden: la variable de entorno LABELGRID_API_TOKEN, luego una credencial guardada con labelgrid auth login y, por último, la opción --token. Use preferentemente labelgrid auth login: pide el token con la entrada oculta, de modo que el valor nunca llega al historial de su shell ni a la lista de procesos. La CLI nunca muestra el valor del token.

”¿Necesito un plan de API?”

Sí. La CLI se conecta a través de la API pública de LabelGrid, por lo que su cuenta necesita acceso a la API, que forma parte de los planes de API de LabelGrid. Consulte la visión general de la API para saber cómo obtener acceso.

”¿En qué se diferencia la CLI del servidor MCP?”

Ambas son herramientas oficiales de LabelGrid sobre la misma API pública. La CLI es para su terminal y sus scripts; el servidor MCP es para asistentes de IA como Claude y Cursor, que llaman a la API por usted en lenguaje natural. Use la que mejor se adapte a su flujo de trabajo, o ambas.

---

Relacionado

• Visión general de la API — cómo obtener acceso a la API y autenticarse
• Conecte su asistente de IA a LabelGrid (MCP) — las mismas acciones, en lenguaje natural
• Webhooks — notificaciones asíncronas de eventos
• @labelgrid/cli en npm
• Documentación en GitHub — referencia de la CLI en packages/cli

¿Crea un flujo de lanzamiento para un agente de IA?

El proyecto de GitHub también incluye una skill de agente lista para usar que enseña a un asistente de IA todo el flujo de lanzamiento con el servidor MCP y la CLI — vea skills/labelgrid-release.

---

¿Necesita ayuda?

Si tiene preguntas sobre la CLI, contacte con nuestro equipo de soporte.