Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Sign in, entitlements and offline licences

    View as Markdown

    The Keryn CLI is distributed privately. A release build needs permission to scan through either a sign-in to your organization or an offline licence for contract customers. This page says how each works and what you can check from a terminal. Keryn Web needs none of it.

    Check the keryn.app download page for member download availability. If file downloads are enabled for your account, sign in to select a file. If your organization has already staged a private CLI package for you, use that package. Follow the install checks before you run it.

    keryn login

    keryn login prints a link and a code. Open the link on any device, confirm the code, and this machine is bound to your organization, team and account. The sign-in is a device sign-in: the CLI keeps a device key, a device token and a cached entitlement in its configuration directory (KERYN_CONFIG_DIR, otherwise ~/.config/keryn), each file readable only by you. keryn logout forgets it.

    keryn whoami says who the machine is signed in as. On a machine that is not signed in it says so and exits 1:

    Terminal window
    keryn whoami
    Not signed in. Run `keryn login` (or `keryn licence install <file>` for an offline licence).

    Use --json for a script. The reply names the organization, team, account, plan, features and when the entitlement expires.

    An entitlement is a signed token the Keryn service gives a device. It names the organization, team, account and device, the features and limits of the plan, and when it expires. The CLI checks the signature itself, so a changed token is refused.

    • Plans. free, team (a paid Team invoice in the last 35 days), and enterprise or government (an active contract). A payment hold drops an organization to free.
    • Offline. A device keeps working after it loses the network until its cached entitlement expires plus a grace period: 7 + 3 days on free, 7 + 7 on team, 30 + 14 on contract plans.
    • One machine. The first machine a device signs in from becomes its machine. Copying the configuration directory to another machine does not work, online or offline: the copy is refused. An organization admin can release a device to move it.
    • Usage. Local scans cost no credits. A signed-in machine reports allow-listed counts to your organization (command, size class, outcome), never your source or findings; see the privacy notice.

    A person sees the devices they paired and can end one in Account, Security. An organization admin can end one device, or every device a member paired, in Account, Members. Removing a member ends all of theirs. An ended device is refused at its next request. Admins see each device’s machine, plan and expiry in Account, Developers, and can revoke an entitlement there.

    A contract customer who cannot or will not sign in uses an offline licence. It is bound to one machine and never phones home. The licence is not Keryn Cloud access; it only lets the CLI run.

    First, on the machine, write a request. It holds the machine’s fingerprint and a device key, and no secret:

    Terminal window
    keryn licence request --org org_123 --out request.json
    Terminal window
    grep -c keryn.licence-request request.json
    1

    Second, send request.json to your Keryn contact. The licence they return runs on that machine only.

    Third, install it with keryn licence install acme.kl. It is refused when the licence names other machines, is expired, or was not signed by Keryn.

    Last, check it. On a machine with a valid licence keryn licence status prints the organization, plan, contract and expiry and exits 0. Here, with none installed, it exits 1:

    Terminal window
    keryn licence status

    If your contract prices by usage, keryn licence usage writes the counts this machine recorded under its licence, per month, by command, size class, outcome and whether Deep ran, with a digest. It contains no path, repository name or finding, and nothing is sent: you send the file to your Keryn contact yourself.

    Terminal window
    keryn licence usage --from 2026-01 --to 2026-12 --out usage-2026.json

    Without an installed licence it exits 1 and says that usage is counted here only under a licence. A signed-in machine reports to your organization instead, and the organization’s admins read it in Account, Developers.

    Command 0 1 2
    keryn login signed in, entitlement stored sign-in failed or the code expired usage error
    keryn whoami signed in not signed in usage error
    keryn licence status a valid licence is installed none, or unusable here usage error
    keryn licence install installed refused: not valid on this machine usage error
    keryn licence usage report written no usable licence usage error

    The full options are on the reference pages for login, whoami and licence.