A terminal has no license dialog
A desktop app can open a window and ask for a key. A CLI runs in a shell, over SSH, in a container or in a pipeline, often with no keyboard attached. Plan three entry points:
yourtool activate KEYfor a person at a terminal. It calls/v1/licenses/activatewith a device name and a fingerprint, then writes the key, theinstance.idand the token to a file.YOURTOOL_LICENSE_KEYas an environment variable for scripts, containers and CI.yourtool licenseoryourtool statusto show who the license is for, when it was last checked, and how many devices it has used. Support teams will ask for this output.
Store the file in the platform’s config location: $XDG_CONFIG_HOME or ~/.config on Linux, ~/Library/Application Support on macOS, %APPDATA% on Windows. Set the file mode to 0600.
The CI problem
On a laptop, one activation lasts for years. In CI, every job may start on a fresh machine with no state. If each run calls activate, the third job uses the last free device slot and the fourth fails with “This license key has reached the activation limit.” A fingerprint does not help, because each runner is a different machine.
The License API gives you a way out. validate takes an optional instance_id. Without it, the call reports the license’s status and does not need an activation, so it takes no seat. A CI path can therefore look like this:
| Where the tool runs | Call | Takes a device slot? |
|---|---|---|
| A developer’s laptop | activate once, then validate with the instance_id |
Yes, one per machine |
| A shared build server | The same as a laptop, if the server is long-lived | Yes, one |
| Ephemeral CI runner | validate with the key only |
No |
This trades something. A key that is only validated can be pasted into any number of runners, so the device limit stops counting them. If that bothers you, sell a CI license as a separate product with its own price and meaning, or put the CI key in a secret that only your customer’s admins can read. Expect the rate limits too: the License API allows 60 requests a minute per key and 120 a minute per IP address, and many runners share one egress address. Check once per job, not once per command, and cache the answer in the job’s workspace.
A minimal check
This script exits 0 when the license is valid, 2 when it is not, and 3 when Clavem cannot be reached, so a calling script can choose what to do. It needs curl and jq.
#!/bin/sh
key="${YOURTOOL_LICENSE_KEY:?set YOURTOOL_LICENSE_KEY}"
out=$(mktemp)
code=$(curl -s -o "$out" -w '%{http_code}' --max-time 8 \
https://clavem.io/v1/licenses/validate -d license_key="$key") || exit 3
case "$code" in
200) jq -e '.valid == true' "$out" >/dev/null && exit 0 || exit 2 ;;
404) exit 2 ;;
*) exit 3 ;;
esac
A known key answers 200 whether or not it is valid, so read valid, not only the status code. A 404 means the key is unknown, and 429 or 5xx means “could not check”. Treat that third outcome as “keep going on the stored token”, not as “unlicensed”. Your tool should do the same in code, using the signed token for the offline path; see offline verification.
Air-gapped and offline use
A command-line tool can run on a server with no outbound access, which a desktop app rarely does. A signed token lets the tool work without any call to Clavem until refresh_by, 14 days after the token was issued. After that, you decide: ask the user to connect once, or accept the expired window for a stated grace period. Say which in your documentation, because a nightly job that stops with a license error at 3 a.m. is a support ticket.
Delivering and updating the binary
Most CLIs reach users through a package manager, a curl | sh installer or a download page. A paid tool can also fetch its own updates from Clavem. Upload each build with a platform label such as linux-amd64 or darwin-arm64. The update subcommand asks GET /v1/releases/:productId/latest?platform=... with the key in the X-License-Key header, compares versions, requests the file link when the user confirms, and replaces itself. A valid key gets a signed link that lasts one hour; see releases and downloads. If your package manager already ships updates, keep the check in the tool and leave file delivery to the package manager.
Recommended setup
| Setting | Suggested value | Why |
|---|---|---|
| License type | Annual subscription, or perpetual with paid major versions | Pick the one that covers your ongoing support cost |
| Device limit | 3 for personal keys | Laptop, desktop and a server or two |
| Trial | 14 days, or a free tier with limits | Developers install before they ask |
| Updates | yourtool update against the releases endpoint |
No browser needed |
Doing this with Clavem
Create a product, connect Stripe and map your Stripe product. Each purchase issues a key and an order page. The Go, Rust and Python guides show the full flow. The article on licensing a CLI tool covers the product decisions.
Guides to follow
- Device activation in Go
- Offline license verification in Rust
- Software updates in Python
- License key validation in Node.js
Questions
How does a user enter a license key in a command-line tool?
Give the tool an activate command that takes the key, calls the License API and writes the key, the instance id and the signed token to a file in the user's config directory. An environment variable is the usual alternative for scripts and CI.
How do I license a CLI used in CI?
Validate with the key alone and skip the instance id. A validate call without instance_id does not take a device slot, so ephemeral runners do not exhaust the device limit. Cache the result for the length of the job.