LabelGrid Command-Line Tool (CLI)

Q: Does LabelGrid have a command-line tool?

Yes. LabelGrid publishes an official command-line tool as the npm package @labelgrid/cli. Install it with npm install -g @labelgrid/cli and it adds a labelgrid command to your terminal. It requires Node.js 20 or newer. The CLI is a thin wrapper over the LabelGrid public API, so it works with the same catalog, files, analytics, and distribution actions the API offers.

Q: What can I do with the LabelGrid CLI?

You can sign in and manage tokens; search, view, create, update, and delete labels, artists, writers, publishers, releases, and tracks; upload audio, artwork, lyrics, and motion artwork; validate releases, submit them for distribution, and take them down; pull statements, transactions, royalties, and streaming analytics; view review issues and quality reports; manage webhooks; and manage Beatport enablement. Anything the LabelGrid public API allows, the CLI can do; anything the API rejects, the CLI rejects the same way.

Q: How do I authenticate the CLI?

The CLI uses a LabelGrid API token. It looks for the token in three places, in order: the LABELGRID_API_TOKEN environment variable, then a credential you store with labelgrid auth login (saved in your macOS Keychain, or in a permission-restricted file under ~/.config/labelgrid on other systems), then a --token flag. The CLI never prints token values.

Q: How is the CLI different from the MCP server?

Both are official LabelGrid tools built on the same public API. The CLI is for your terminal and scripts — you type commands or run them in automation. The MCP server is for AI assistants such as Claude and Cursor, which call the API for you in plain language. Use whichever fits your workflow, or both.

Updated July 2026.

LabelGrid publishes an official command-line tool so you can work with your account straight from the terminal or from a script. It is the npm package @labelgrid/cli, and installing it adds a labelgrid command to your machine.

The CLI is a thin wrapper over the LabelGrid public API — the same surface, the same validation, and the same permissions. Anything the public API allows, the CLI can do; anything the API rejects, the CLI rejects in exactly the same way. If you would rather work in plain language with an AI assistant, LabelGrid also publishes an MCP server built on the same API.

What you can do

Commands are organized into groups. From your terminal you can:

auth — sign in, sign out, check who you are signed in as, and revoke a token
catalog — search, view, create, update, and delete labels, artists, writers, publishers, releases, and tracks
release — validate a release, submit it for distribution, take it down, confirm review, and manage its landing page and short link
upload — add audio, artwork, lyrics, and motion artwork (each type only accepts its allowed file extensions)
download, asset, license — retrieve files and manage licenses
statement, transactions, royalties, analytics — pull statements, transactions, royalty breakdowns, and streaming analytics
review — view review issues, read quality reports, and add notes
webhook — register and manage webhooks for asynchronous notifications
beatport — manage Beatport enablement

What you need

A LabelGrid account with API access. API access is part of LabelGrid’s API plans — see the API Overview for how to get it.
An API token. Generate one in your LabelGrid dashboard under Profile → API Tokens.
Node.js 20 or newer on the computer where you run the CLI.

Install

Install the CLI globally with npm:

npm install -g @labelgrid/cli

This adds the labelgrid command. Check that it worked with:

labelgrid --version

Authentication

The CLI needs your API token. It looks for one in three places, in this order:

The LABELGRID_API_TOKEN environment variable — best for scripts and CI.
A stored credential you save once with labelgrid auth login. On macOS this is kept in your Keychain; on other systems it is saved to a permission-restricted file under ~/.config/labelgrid/.
The --token flag on an individual command.

Point the CLI at an environment variable:

export LABELGRID_API_TOKEN=your-api-token
labelgrid auth whoami

Or store the token once and let the CLI reuse it:

labelgrid auth login

The CLI never prints token values. To stop access, sign out with labelgrid auth logout or revoke the token from your dashboard, which takes effect immediately.

Output and exit codes

By default the CLI prints clean, human-readable output. For scripting, add --json to any command and it prints the raw API response so you can pipe it into other tools:

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

Commands set standard exit codes so your scripts can react to the result:

Exit code	Meaning
`0`	Success
`1`	API error (the request reached LabelGrid and was rejected)
`2`	Usage error (a mistake in the command itself)

Safety

Final and destructive commands ask you to confirm before anything is sent. Submitting a release for distribution, taking a release down, confirming review, deleting catalog items, and enabling Beatport all prompt you to type y to confirm before the CLI makes any API call.

For automation where no one is at the keyboard, add --yes to skip the prompt:

labelgrid release distribute REL123 --yes

Every account protection — validation, plan limits, and rate limits — is enforced by LabelGrid’s servers, so the CLI cannot bypass them however you run it.

Troubleshooting

command not found: labelgrid — the global install did not finish or is not on your PATH. Re-run npm install -g @labelgrid/cli and confirm Node.js 20 or newer with node --version.
Token invalid or rejected — recreate the token in your dashboard under Profile → API Tokens, then set it again with export LABELGRID_API_TOKEN=... or labelgrid auth login.
You do not see an “API Tokens” page — your account does not have API access yet. See the API Overview for how to enable it.
A command fails in a script — check the exit code (1 is an API error, 2 is a usage error) and re-run the same command with --json to read the full response.

FAQ

”Does LabelGrid have a command-line tool?”

Yes. LabelGrid publishes an official CLI as the npm package @labelgrid/cli. Install it with npm install -g @labelgrid/cli and it adds a labelgrid command to your terminal. It requires Node.js 20 or newer and is a thin wrapper over the LabelGrid public API.

”What can I do with it?”

Sign in and manage tokens; search, view, create, update, and delete labels, artists, writers, publishers, releases, and tracks; upload audio, artwork, lyrics, and motion artwork; validate releases, submit them for distribution, and take them down; pull statements, transactions, royalties, and streaming analytics; view review issues and quality reports; manage webhooks; and manage Beatport enablement.

”How do I authenticate the CLI?”

With a LabelGrid API token. The CLI looks for it in three places, in order: the LABELGRID_API_TOKEN environment variable, then a credential stored with labelgrid auth login, then a --token flag. The CLI never prints token values.

”Do I need an API plan?”

Yes. The CLI connects through the LabelGrid public API, so your account needs API access, which is part of LabelGrid’s API plans. See the API Overview for how to get access.

”How is the CLI different from the MCP server?”

Both are official LabelGrid tools on the same public API. The CLI is for your terminal and scripts; the MCP server is for AI assistants such as Claude and Cursor that call the API for you in plain language. Use whichever fits your workflow, or both.

API Overview and Quickstart — how to get API access and authenticate
Connect Your AI Assistant to LabelGrid (MCP) — the same actions, in plain language
Webhooks — asynchronous event notifications
@labelgrid/cli on npm
Documentation on GitHub — CLI reference under packages/cli

Need help?

If you have questions about the CLI, contact our support team.

Not using LabelGrid yet?

Everything you just read about is available on our platform.

See what LabelGrid can do →