CLI

The keygrant command works with KeyGrant licenses from a terminal or a build pipeline. It is the @keygrant/cli package, version 0.5.3.

npm install --global @keygrant/cli
# Paste a secret API key when it askskeygrant login
# Your products and their license modelskeygrant products

Install and run

Run it with npx, or install it globally. It needs Node.js 22 or later.

npx @keygrant/cli --help# ornpm install --global @keygrant/clikeygrant --help

• keygrant --help lists the commands, and keygrant <command> --help gives every option of one.
• keygrant --version prints the version.
• The licenses in a command may also be spelled license, licences or licence.

One file, nothing to install

From version 0.5.0 each release also has the command as one file for each platform, with nothing to install, not even Node.js. Each file has a .sha256 beside it, on the release page of keygrantdev/keygrant-cli.

• Linux: x64 and arm64, glibc 2.28 or later, so not Alpine.
• macOS: Apple silicon and Intel.
• Windows: x64.

It keeps no key: set KEYGRANT_API_KEY, as a build pipeline does.

From 0.5.1 the macOS files are signed with a Developer ID and notarized by Apple, and from 0.5.2 the Windows file is signed too. Each release after 0.5.0 says in its notes whether its macOS files are notarized and its Windows file signed. Version 0.5.0's are neither: macOS may stop the file the first time (xattr -d com.apple.quarantine <file> lets it run), and Windows may ask before running it.

Signing in

The command uses one of your account's secret API keys (kg_live_... or kg_test_...), from the dashboard's API keys screen, never your dashboard sign-in.

• KEYGRANT_API_KEY, when set, is used before a kept key.
• A kg_test_ key issues and reaches test licenses only; a release needs a kg_live_ key. See Server endpoints for what each kind of key reaches.
• pubkey needs no API key, and verify works offline.

Commands

Examples

# A release scriptkeygrant release "$VERSION" --product my-app
# The key set to build into the appkeygrant pubkey my-app > src/keygrant-keys.json
# A test license whose device limit is already reached, to see how the app handles itkeygrant licenses test --product my-app --scenario device-limit
# Check a lease the app stored, offlinekeygrant verify ./lease.txt --key src/keygrant-keys.json --product my-app
# Save the license file of a key sold as a file, to send it yourselfkeygrant licenses file MYAPP-AAAA-BBBB-CCCC-DDDD --out ./files/ada.kglicense
# Check a license file or key file a buyer was sent, offline: its kind, product, licensee, versions,# file id and the key that signed it (the key set must hold every key that ever signed a file)keygrant verify ./my-app-license.kglicense --key src/keygrant-keys.json --product my-app
# Give a customer 500 more exports, once, however often the command runskeygrant licenses uses MYAPP-AAAA-BBBB-CCCC-DDDD exports --add 500 --idempotency-key support-ticket-4812
# Spend 3 renders for a customer from your own server, once per renderkeygrant licenses use MYAPP-AAAA-BBBB-CCCC-DDDD renders 3 --id render-9f2c1a77-0001
# Let only the buyer activate a new device on a key: their email, then a code emailed to itkeygrant licenses user-lock MYAPP-AAAA-BBBB-CCCC-DDDD code

Products, releases and keys

Look up your products, report a release and fetch a product's public keys.

keygrant products

keygrant products [--product <id>] prints your products, with the meters their apps spend and their license models' ids, which --model takes.

• Each product shows its API ID, key prefix and current version, and "key pickup on" when its apps may restore a license by an emailed code (from 0.5.3).
• A model whose keys are sent as a file says so after what it sells (as a key file, as a license file).
• A model that counts uses shows its meters: the code, its uses, "a period" when they come back each billing period, and its own offline allowance. A top-up shows the uses a unit adds (+500 exports).
• When a model locks who can activate its keys, a column says who can, for each model.

keygrant release

keygrant release <version> --product <id> moves the product's current version up to this version's major (2.4.0 is 2), never down.

• A build script may run it on every release, a hotfix on an old line included.
• The current version caps what upgrade protection keeps (see Current version).
• It needs a kg_live_ key, and refuses a kg_test_ one.
• It prints the current version after the call; --json prints the API's answer, { "product", "currentMajor" }.

See POST /v1/products/:slug/releases.

keygrant pubkey

keygrant pubkey <product id> [--signing-only] prints { "keys": [ ... ] }: every key a build should carry, each with its id (kid). It is the set an app embeds (see GET /pubkey).

• Embed the whole set, so a lease verifies on either side of a key switch.
• --signing-only prints the key that signs, alone: what a build carries after a signing key leaked.
• It needs no API key.
• --json prints the API's answer, { "publicJwk", "keys" }.

Licenses

Issue, find, change and revoke licenses, free their devices and make test licenses.

keygrant licenses issue

keygrant licenses issue --product <id> (--model <model id> | --type <type>) issues a key, or several as one sale. It prints each key on a line of its own.

A kg_test_ key issues test licenses. See POST /v1/licenses.

keygrant licenses get, list and checkout

keygrant licenses get <key> prints the license: its model, state, who can activate it, how it was delivered, expiry, devices, versions and entitlements. --json prints the API's answer, { "license": { ... } }.

keygrant licenses list lists licenses, newest first, as a table, and prints the cursor of the next page when there is one.

keygrant licenses checkout <cs_... or txn_...> prints the license a Stripe Checkout Session or a Paddle transaction minted (every key, for a sale of several), or why there is none:

• not yet: the webhook that makes it can take a few seconds;
• the checkout upgraded a key;
• the sale was held (see Held sales);
• the sale was refunded.

keygrant licenses extend, versions, device-limit and seat-release

Each prints the license as it now stands. --json prints the API's answer.

keygrant licenses user-lock

keygrant licenses user-lock <key> <off|email|code> sets who can activate a new device on the key, in place of its model's. It prints the license as it now stands; --json prints the API's answer. From version 0.5.0.

• Only a new device is ever asked: devices already activated keep working.
• Your app sends the email and the code when it activates.
• These cannot be locked: a key with no email (email-required), a test license (user-lock-test-key) and a key sent as an offline license file (user-lock-license-file).
• KeyGrant emails no code for a product that sends its own customer email, so a new device on a code key is told try-again and cannot activate: use email there, or let KeyGrant send the product's email.
• A key file carries the buyer's email, so where KeyGrant sends the product's email, use code for a key sent as one.
• keygrant licenses get says when a key's lock is never asked, so anyone can activate it.

See Who can activate and POST /v1/licenses/:key/user-lock.

keygrant licenses revoke, devices and free-device

keygrant licenses test

keygrant licenses test --product <id> [--scenario <state>] makes a test license in a state your app must handle, as the dashboard's Create test license does. It prints the key on its first line, then the license.

• It is signed with the product's real key and marked as a test, so it works in the build you ship.
• It lasts 30 days at most, is never emailed, and your account holds 25 at once. See Testing your integration.

Meters

A license model can count uses of what it sells: 1,000 exports for good, or 50 renders each month a subscription is paid (see Metered uses). Each thing counted is a meter, with a code your app passes to use(). Your app spends its own meters through the SDK; the command line is for you.

keygrant licenses meters

keygrant licenses meters <key> prints each meter of a license:

• left: what is left;
• total: the uses it holds, added ones included;
• used, and what was added on top;
• offline: the allowance a device may spend while KeyGrant cannot be reached ((default) when the key sets none of its own);
• resets: never, or each billing period and where this one ends;
• overage, when any meter has some: spent past the total, which only reports from offline can make.

keygrant licenses get shows the same in a line, and keygrant products lists a product's meters. --json prints the API's answer.

keygrant licenses uses

keygrant licenses uses <key> <meter> changes one meter, with exactly one of these:

• --add and --reset send an idempotency key: see Retries of your own.
• A set is its own retry: run again, it changes nothing more. A removal run again answers unknown-meter, the meter being gone already.
• The app sees a change at its next check-in.
• It prints what was done and the license as it now stands; --json prints the API's answer.

See Meters: /v1/licenses/:key/meters.

keygrant licenses use

keygrant licenses use <key> <meter> [n] [--id <id>] spends n uses from your own backend, such as a cloud render the key pays for. Your secret key is the proof, so no device is asked.

• It is exact and whole or none: when fewer than n are left it exits 1 with used-up and how many are.
• It is refused for a revoked key (license-revoked) and an expired one (license-expired).
• An error that may have spent all the same (exit 5) names the id it made.
• It prints what it spent, what is left and the spend's id.

License files and key files

A license model can deliver a key as a file (.kglicense) instead of typed text. The buyer is emailed the file when they buy.

• A key file carries the key: an app that takes it activates the key online as it would a typed one.
• A license file licenses the app offline, for good, on any number of computers.

What each kind means is under Delivered as in License models.

keygrant licenses file

keygrant licenses file <key> saves the key's file: as it was kept while the key says the same, otherwise signed again with the current signing key. It prints where it went.

• Each call is in the license's history.
• It writes the file readable by you alone on macOS and Linux.
• KeyGrant refuses a key delivered typed (not-a-file-license), a key with no email address (no-licensee), a revoked key (license-revoked) and an offline file's key that ends (license-expires).

See POST /v1/licenses/:key/file.

keygrant verify

keygrant verify <lease | license file | - | file> --key <file> checks a lease, a license file or a key file against a key set, exactly as an SDK does, with no network. It exits 0 for a valid lease or file and 1 for one that is not.

• A lease: give the lease itself, - for standard input, or a file holding it (the token, or JSON with a lease).
• A license file or key file: give its path, - for its text on standard input, or its token alone. A file whose name ends in .kglicense, or a token whose header says it is a license file's, is read as one.

A lease is checked for, in this order:

1. its signature, by the key it names (each key in turn for a lease that names none);
2. its claims;
3. its expiry.

It prints what the lease grants, and a metered key's meters with what was left of each when the lease was signed.

A license file is read as an app reads it:

1. the text must be valid UTF-8 with one token (notes on lines starting with # are ignored);
2. the key id it names must be in the key set;
3. its signature must be by that key;
4. its claims must be a license file's.

It prints the file's kind, product, licensee, key, versions (an offline file), file id and the id of the key that signed it. The key set from keygrant pubkey holds every key that ever signed a file, so a file signed before a key rotation still verifies.

Dates

A date option takes any of these forms.

extend --days counts from the later of now and the license's current expiry. A timed license still waiting for its first activation has no expiry to move yet.

For scripts

Every command takes --json and prints what the API answered.

• A command's --help says when it prints an object of its own: login, logout, verify, licenses file, a filtered products, and every page of licenses list --all.
• When something fails, --json prints the error on standard error, as { "error": "<code>", ... } with "status" when KeyGrant answered, and nothing else there.
• Without it, an API error prints as keygrant: <code>: <sentence>, and a usage error as keygrant: <sentence>. When a command was named, a line follows saying to run that command's --help.

When KeyGrant answers 429

• The command waits as long as the answer says, says so on standard error (not under --json), and tries once more. A second 429 exits 4 with the wait.
• A 429 asking for more than two minutes is not waited out: it exits 4 at once.
• --no-retry exits 4 at once instead.
• KeyGrant counts a request before it does anything, so the retry never does a thing twice.

The limits themselves are in Rate limits.

Retries of your own

• licenses issue, licenses test, and licenses uses with --add or --reset, send an idempotency key: one made for each run, or yours with --idempotency-key. Running the same command again with the same key makes or changes nothing more: an issue or a test answers the license first made.
• When one of them fails in a way that may have gone through all the same (exit 5: KeyGrant could not be reached, or failed), the error names the key it made (idempotencyKey under --json). Run the command again with --idempotency-key and that key.
• licenses extend sends the new expiry as an instant, so running it again with --to changes nothing more.
• licenses uses and licenses use retry safely too: see keygrant licenses uses and keygrant licenses use.

Options every command takes