콘텐츠로 이동
Help Center
지원

LabelGrid 명령줄 도구(CLI)

2026년 7월 업데이트.

LabelGrid는 터미널이나 스크립트에서 바로 계정 작업을 할 수 있도록 공식 명령줄 도구를 배포합니다. npm 패키지 @labelgrid/cli이며, 설치하면 컴퓨터에 labelgrid 명령이 추가됩니다.

CLI는 LabelGrid 공개 API를 그대로 감싼 가벼운 래퍼입니다. 다루는 범위도, 검증 방식도, 권한 체계도 API와 동일합니다. 공개 API가 허용하는 작업은 CLI로도 할 수 있고, API가 거부하는 작업은 CLI에서도 똑같이 거부됩니다. 명령어 대신 AI 어시스턴트와 자연어로 작업하고 싶다면, LabelGrid는 같은 API 위에 만들어진 MCP 서버도 배포하고 있습니다.

무엇을 할 수 있나요

섹션 제목: “무엇을 할 수 있나요”

명령은 그룹으로 정리되어 있습니다. 터미널에서 다음 작업을 할 수 있습니다.

  • auth: 로그인, 로그아웃, 현재 로그인 계정 확인, 토큰 폐기
  • catalog: 레이블, 아티스트, 작가, 퍼블리셔, 릴리스, 트랙의 검색·조회·생성·수정·삭제
  • release: 릴리스 검증, 배급 제출, 테이크다운, 검수 확인, 랜딩 페이지 및 단축 링크 관리
  • upload: 오디오, 아트워크, 가사, 모션 아트워크 추가(각 유형은 허용된 확장자만 받습니다)
  • download, asset, license: 파일 조회 및 라이선스 관리
  • statement, transactions, royalties, analytics: 명세서, 거래 내역, 로열티 내역, 스트리밍 애널리틱스 조회
  • review: 검수 이슈 확인, 품질 리포트 열람, 메모 추가
  • webhook: 비동기 알림용 웹훅 등록 및 관리
  • beatport: Beatport 활성화 관리

준비물

섹션 제목: “준비물”
  1. API 접근 권한이 있는 LabelGrid 계정. API 접근 권한은 LabelGrid API 요금제에 포함됩니다. 자세한 내용은 API 개요를 참고하세요.
  2. API 토큰. LabelGrid 대시보드의 Profile → API Tokens에서 생성하세요.
  3. CLI를 실행할 컴퓨터의 Node.js 20 이상.

설치

섹션 제목: “설치”

npm으로 CLI를 전역 설치합니다.

Terminal window
npm install -g @labelgrid/cli

이렇게 하면 labelgrid 명령이 추가됩니다. 다음 명령으로 정상 설치를 확인하세요.

Terminal window
labelgrid --version

인증

섹션 제목: “인증”

CLI에는 API 토큰이 필요합니다. 토큰은 다음 세 곳에서 순서대로 찾습니다.

  1. LABELGRID_API_TOKEN 환경 변수: 스크립트와 CI에 가장 적합합니다.
  2. labelgrid auth login으로 한 번 저장해 두는 자격 증명. macOS에서는 키체인에 보관되고, 그 외 시스템에서는 ~/.config/labelgrid/ 아래의 권한이 제한된 파일에 저장됩니다.
  3. 개별 명령에 붙이는 --token 플래그.

환경 변수를 사용하려면 다음과 같이 실행합니다.

Terminal window
export LABELGRID_API_TOKEN=your-api-token
labelgrid auth whoami

또는 토큰을 한 번 저장해 두고 CLI가 계속 사용하도록 할 수 있습니다.

Terminal window
labelgrid auth login

CLI는 토큰 값을 절대 출력하지 않습니다. 접근을 차단하려면 labelgrid auth logout으로 로그아웃하거나 대시보드에서 토큰을 폐기하세요. 폐기는 즉시 적용됩니다.

출력과 종료 코드

섹션 제목: “출력과 종료 코드”

기본적으로 CLI는 사람이 읽기 좋은 형태로 결과를 출력합니다. 스크립트에서 사용할 때는 아무 명령에나 --json을 붙이면 API 응답 원본이 출력되어 다른 도구로 넘길 수 있습니다.

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

명령은 표준 종료 코드를 설정하므로 스크립트에서 결과에 따라 분기할 수 있습니다.

종료 코드의미
0성공
1API 오류(요청이 LabelGrid에 도달했으나 거부됨)
2사용법 오류(명령 자체에 잘못된 부분이 있음)

안전장치

섹션 제목: “안전장치”

되돌릴 수 없거나 최종적인 명령은 실행 전에 확인을 요청합니다. 릴리스 배급 제출, 릴리스 테이크다운, 검수 확인, 카탈로그 항목 삭제, Beatport 활성화는 모두 CLI가 API를 호출하기 전에 y를 입력해 확인하도록 안내합니다.

키보드 앞에 아무도 없는 자동화 환경에서는 --yes를 붙여 확인 절차를 건너뛸 수 있습니다.

Terminal window
labelgrid release distribute REL123 --yes

검증, 요금제 한도, 요청 속도 제한 등 모든 계정 보호 장치는 LabelGrid 서버에서 적용되므로, CLI를 어떤 방식으로 실행하든 이를 우회할 수 없습니다.

문제 해결

섹션 제목: “문제 해결”
  • command not found: labelgrid: 전역 설치가 끝나지 않았거나 PATH에 없는 경우입니다. npm install -g @labelgrid/cli를 다시 실행하고 node --version으로 Node.js 20 이상인지 확인하세요.
  • 토큰이 유효하지 않거나 거부됨: 대시보드의 Profile → API Tokens에서 토큰을 다시 만든 뒤 export LABELGRID_API_TOKEN=... 또는 labelgrid auth login으로 다시 설정하세요.
  • “API Tokens” 페이지가 보이지 않음: 계정에 아직 API 접근 권한이 없는 것입니다. 활성화 방법은 API 개요를 참고하세요.
  • 스크립트에서 명령이 실패함: 종료 코드를 확인하고(1은 API 오류, 2는 사용법 오류) 같은 명령을 --json과 함께 다시 실행해 전체 응답을 확인하세요.

FAQ

섹션 제목: “FAQ”

”LabelGrid에 명령줄 도구가 있나요?”

섹션 제목: “”LabelGrid에 명령줄 도구가 있나요?””

네. LabelGrid는 공식 CLI를 npm 패키지 @labelgrid/cli로 배포합니다. npm install -g @labelgrid/cli로 설치하면 터미널에 labelgrid 명령이 추가됩니다. Node.js 20 이상이 필요하며, LabelGrid 공개 API를 그대로 감싼 가벼운 래퍼입니다.

”무엇을 할 수 있나요?”

섹션 제목: “”무엇을 할 수 있나요?””

로그인과 토큰 관리, 레이블·아티스트·작가·퍼블리셔·릴리스·트랙의 검색·조회·생성·수정·삭제, 오디오·아트워크·가사·모션 아트워크 업로드, 릴리스 검증과 배급 제출 및 테이크다운, 명세서·거래 내역·로열티·스트리밍 애널리틱스 조회, 검수 이슈와 품질 리포트 확인, 웹훅 관리, Beatport 활성화 관리를 할 수 있습니다.

”CLI 인증은 어떻게 하나요?”

섹션 제목: “”CLI 인증은 어떻게 하나요?””

LabelGrid API 토큰으로 합니다. CLI는 토큰을 세 곳에서 순서대로 찾습니다. LABELGRID_API_TOKEN 환경 변수, labelgrid auth login으로 저장한 자격 증명, 그리고 --token 플래그입니다. CLI는 토큰 값을 절대 출력하지 않습니다.

”API 요금제가 필요한가요?”

섹션 제목: “”API 요금제가 필요한가요?””

네. CLI는 LabelGrid 공개 API를 통해 연결되므로 계정에 API 접근 권한이 있어야 하며, 이는 LabelGrid API 요금제에 포함됩니다. 접근 권한을 얻는 방법은 API 개요를 참고하세요.

”CLI와 MCP 서버는 어떻게 다른가요?”

섹션 제목: “”CLI와 MCP 서버는 어떻게 다른가요?””

둘 다 같은 공개 API 위에 만들어진 공식 LabelGrid 도구입니다. CLI는 터미널과 스크립트를 위한 도구이고, MCP 서버는 Claude나 Cursor 같은 AI 어시스턴트를 위한 것으로, 자연어로 요청하면 어시스턴트가 대신 API를 호출합니다. 작업 방식에 맞는 쪽을 선택하거나 둘 다 사용하세요.

관련

섹션 제목: “관련”

도움이 필요하세요?

섹션 제목: “도움이 필요하세요?”

CLI에 대해 궁금한 점이 있으면 고객지원팀에 문의해 주세요.

아직 LabelGrid를 사용하지 않으세요?

방금 읽으신 내용은 모두 저희 플랫폼에서 이용하실 수 있어요.

LabelGrid로 할 수 있는 일 보기 →