LabelGrid Command-Line Tool (CLI)

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 validation and the same permissions. Every command maps to an API call, so anything the API rejects, the CLI rejects in exactly the same way, and no CLI command can do something your token is not allowed to do. It covers the command groups listed below rather than every endpoint the API publishes; for a corner of the API with no matching command yet, call the endpoint directly. 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

1. A LabelGrid account with API access. API access is part of LabelGrid’s API plans — see the API Overview for how to get it.
2. An API token. Generate one in your LabelGrid dashboard under Profile → API Tokens.
3. 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:

1. The LABELGRID_API_TOKEN environment variable — best for scripts and CI, where the value comes from your CI provider’s secret store.
2. 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/.
3. The --token flag on an individual command — the fallback of last resort.

On your own machine, the safest option is to store the token once. Run labelgrid auth login with no arguments and it prompts you to paste the token with the input hidden, so the value never appears on screen or in your shell history:

labelgrid auth login

Every later command reuses the stored credential, so you never type the token again:

labelgrid auth whoami

Caution

Avoid putting the token directly on a command line — as a --token value or in export LABELGRID_API_TOKEN=.... Anything you type is saved to your shell history file, and command-line arguments are visible to other users on the same machine through the process list. Prefer labelgrid auth login, and in CI inject LABELGRID_API_TOKEN from the provider’s secret store rather than writing it into a script.

For unattended setup where nothing can prompt, pipe the token into labelgrid auth login from a secret manager instead of passing it as an argument:

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

The CLI never prints token values. To stop access, sign out with labelgrid auth logout — which removes the stored credential from that machine — or revoke the token from your dashboard, which immediately stops that token working everywhere. Other tokens on your account keep working; revoke each one you want to retire.

Note

Generate and manage tokens in your dashboard under Profile → API Tokens. If you do not see that page, your account does not have API access yet — see the API Overview.

---

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 store it again with 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. Prefer labelgrid auth login — it prompts for the token with the input hidden, so the value never reaches your shell history or the process list. 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.

---

Related

• 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

Building a release flow for an AI agent?

The GitHub project also ships a ready-made agent skill that teaches an AI assistant the full release workflow using the MCP server and the CLI — see skills/labelgrid-release.

---

Need help?

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