Clavem

How to license a CLI tool without breaking CI, containers or scripts

A CLI tool runs unattended, many times a day, on machines that appear and vanish. License it with an activation for people's own computers and a validate-only check for CI runners and containers, cache the result, and return distinct exit codes so scripts can tell a license problem from a network problem.

What makes a CLI tool different

A desktop app is opened by a person, on one machine, a few times a day. A command-line tool is different in four ways that matter for licensing.

  • It runs without a person watching, so there is nobody to type a key or read an error.
  • It runs often. A tool called from a build script can start hundreds of times an hour.
  • It runs on machines that do not last: CI runners, containers, throwaway cloud instances.
  • Other programs read its output and exit code.

Each of these breaks a design copied from a desktop app. The rest of this article fixes them one at a time, with code that I ran against the demo key at clavem.io and against test tokens signed with a throwaway key pair.

Pick the check by where the tool runs

Where it runs How to check Why
A person’s own computer Activate once with instance_name set to the host name, then validate with the saved instance_id The seat is meant to be used, and the customer can free it on the device page
A shared build server Validate with the key only One server, no need to count it as a person’s device
CI runners and containers Validate with the key only, plus a cache A runner that activates holds a seat after it is gone
An air-gapped machine Verify a stored token offline No network to call

The distinction is in the request. validate takes license_key and an optional instance_id. Leave out instance_id and Clavem checks the key itself without tying it to a device. Activation is what creates a seat, and the default device limit is 3, so three ephemeral CI runners that activate are enough to lock a customer out of their own laptop.

What a validate-only check returns

This is the real response from the demo key, form-encoded, as of 19 November 2026:

{
  "valid": true,
  "error": null,
  "license_key": {
    "id": 1, "status": "active", "key": "S1GNE-TDEM0-7K4QX-9WZ2P-H5RB8",
    "activation_limit": 3, "activation_usage": 1,
    "created_at": "2026-11-18T23:19:24.740Z", "expires_at": null, "test_mode": false
  },
  "instance": null,
  "meta": { "product_id": 1, "product_name": "Inkwell", "customer_email": "ada@example.com", "...": "..." },
  "token": "sgt1.eyJ2IjoxLCJsaWQiOjEsInBpZCI6MSwi..."
}

The response headers include cache-control: no-store and access-control-allow-origin: *. The token is a fresh signed statement of the same result, and it is the thing worth caching.

The code

This module has no dependencies and needs Node 20 or later. It stores the key in a file with mode 0600, checks online when it can, and falls back to the token.

// license.mjs (excerpt)
export async function check(licenseKey, saved = load()) {
  try {
    const { status, body } = await call('validate', {
      license_key: licenseKey,
      ...(saved?.instanceId ? { instance_id: saved.instanceId } : {}), // CI passes none
    });
    if (status === 200) {
      if (saved) save({ ...saved, token: body.token });
      return body.valid ? 'licensed' : 'invalid';
    }
    if (status === 404) return 'invalid'; // unknown key, or this machine was removed
  } catch { /* offline, timeout */ }
  // Rate limited, down or offline: trust the stored token while it is fresh.
  return saved && fresh(verifyToken(saved.token), licenseKey) ? 'licensed' : 'needs-network';
}

The fresh function applies the checks from the offline verification page: the signature, v, pid, valid, exp and refresh_by. It also compares the token’s kh claim with the first 16 hex characters of the SHA-256 of the key, normalized to upper case. That binds a token to a key.

Here is what the module printed when I ran it with no network, against tokens signed by a throwaway key:

valid token, fresh             signature ok   licensed: true
payload edited after signing   signature BAD  licensed: false
past refresh_by (stale)         signature ok   licensed: false
license expired (valid:false)  signature ok   licensed: false
token for another product      signature ok   licensed: false
check() offline, saved good    licensed
check() offline, saved stale   needs-network
check() offline, tampered      needs-network
kh matches the typed key: true   lower-case typed key: true   a different key: false

Against production, a validate-only call with the demo key returned licensed in about 150 ms from my machine in Switzerland, and an unknown key returned invalid in about 100 ms. Those timings are one run each, not a benchmark, but they show why you do not want to pay that on every invocation.

Cache so that you do not call every time

Two limits make caching necessary. The License API allows 120 requests per 60 seconds per IP address and 60 per 60 seconds per license key, and a request has to pass both. A customer who starts 80 parallel CI jobs at once, all using the same key, will see HTTP 429 on the last 20 of them. And each call adds a round trip to a tool that people expect to start instantly.

A workable rule:

  1. Store the last result and its time next to the token.
  2. If the result is younger than a few hours, accept it without a call.
  3. Otherwise call validate, and on a network error or HTTP 429 or 503 fall back to the token.
  4. If the token is past its refresh_by time, which is 14 days after issue, return needs-network.

For a build farm, put the cache on a shared volume or have a first job write the result for the later jobs in the same pipeline.

Exit codes and output

Scripts react to exit codes, so give each outcome its own. These are a convention, not a standard, but they are easy to document:

Outcome Exit code What to print on stderr
Licensed 0 Nothing
No key found 3 No license key. Run: mytool license activate KEY
Key invalid, expired or revoked 4 The error text from the API
Device limit reached 5 The error text, plus the URL of the device page
Cannot reach the service and no fresh token 75 Cannot check the license. Try again when online.

Code 75 is EX_TEMPFAIL from the sysexits.h convention, which tells a script that retrying later might work. Keep license messages on stderr so they never corrupt output that another program parses.

Fail open or closed

When the service cannot be reached and the token is stale, you must choose. For a paid developer tool, a short grace period usually beats failing a customer’s deployment pipeline because of your outage or theirs. A tool that blocks a production release because a licensing call timed out will be uninstalled quickly. The 14-day refresh_by window is already a generous grace, and you can accept a stale token with a warning for a few more days before refusing.

Commands that must always work

Do not gate --help, --version or the license subcommands. A person who runs mytool --help to find out how to enter a key, or a script that runs mytool --version to check the install, should never be told the license is missing. Put the check in front of the commands that do the paid work, and let everything else answer instantly. The same goes for a tool that is piped into another: check once at start, not once per line of input.

Air-gapped machines

Some customers run your tool where nothing reaches the internet. The signed token handles them. Fetch a token on a connected machine with validate, copy it across, and let the tool verify it with the public key compiled into the binary. The token is good for 14 days from issue, so an air-gapped customer needs a way to bring a fresh one regularly. Tell them that up front, and consider a longer-term arrangement, such as a separate agreement, for sites that cannot connect at all.

Where to keep the key

On a laptop, ~/.config/mytool/license.json with mode 0600 is normal. On a server or in CI, accept MYTOOL_LICENSE_KEY from the environment and do not write it anywhere. Never print the key in logs or in a --verbose dump. A key is a credential: whoever has it can use up the device limit.

Doing this with Clavem

Clavem’s License API needs no secret, so there is nothing sensitive in the tool itself, and the signed token lets the tool keep working offline. A seller can also create a key for a CI-only customer by hand with the management API and set a high device limit, or -1 for unlimited, if the customer’s contract allows many machines. See machine fingerprinting pitfalls for why hardware ids are shaky on containers, and the guides for a Python version of the same flow.

Questions

Should a CI runner activate the license?

No. A runner that activates takes a device seat and keeps it after the job ends. Call validate with only the license key, which checks the key without creating an activation, and cache the result for the length of the job or longer.

Where should a CLI tool keep the license key?

In a file under the user's config directory with owner-only permissions, or in an environment variable for CI. A command-line tool usually has no access to a graphical keychain on a server, so the file is the practical choice.

How often should the tool call the license API?

Not on every invocation. Check online when the stored result is older than a few hours, and rely on the signed token between checks. The License API allows 60 requests per minute for one license key, which a busy build farm can reach.

Sources

  1. sysexits(3) manual page, EX_TEMPFAIL is 75 (as of November 2026)