keygen-cli
A Rust CLI for keygen.sh. One binary, three deployments
(Cloud / self-hosted CE / self-hosted EE), and a stable JSON envelope built for
agents. Every command emits the same { ok, data, meta?, error? } shape under
--json, and exit codes are documented and stable.
Setup
brew install okooo5km/tap/keygen-cli # installs `keygen` and the `kg` alias
keygen --version
Other paths (pre-built tarballs, cargo install, source) live in
references/installation.md.
Authenticate
keygen login # interactive: deployment → host → account → token
keygen whoami # confirm identity + detected capabilities
Tokens land in the OS keyring (Keychain on macOS, Secret Service on Linux,
Credential Manager on Windows). For CI and ephemeral shells, set
KEYGEN_TOKEN=... instead — that path skips the keyring entirely. Switch
deployments with --profile <name> or KEYGEN_PROFILE.
Core invocation pattern
Every resource exposes the same CRUD surface. Resource-specific actions
(validate, suspend, publish, ...) sit on the same subcommand tree.
keygen <resource> list [--filter k=v] [--limit N] [--page N] [--sort field]
keygen <resource> get <id>
keygen <resource> create [--from-file body.json | --set attrs.x=y --metadata k=v]
keygen <resource> update <id> [--from-file body.json | --set ...]
keygen <resource> delete <id> --yes
Two examples:
keygen license list --filter status=ACTIVE --json
keygen license create --json --policy pol_abc --user usr_def --set attrs.name="Acme"
--json (a gh-style shortcut for --output json) always emits the canonical
envelope. Exit codes: 0 ok, 1 user, 2 server, 3 network, 4 auth, 5
capability. Full envelope schema in
references/ai-envelope.md.
Self-discovery
Two commands let an agent learn the full surface area without reading docs:
keygen schema --format json # entire command tree (subcommands + flags)
keygen explain error <CODE> # diagnose any keygen.sh error code
Use schema when you need to verify a flag exists or look up a subcommand.
Use explain whenever an envelope returns error.code — it returns the
canonical cause, fix, and a suggested next command.
Permission tiers
Three tiers govern which operations need human approval. The full per-command
list is in references/permissions.md; apply
the rules below verbatim.
Tier 1 — auto-run
Read-only inspection. Run freely, no confirmation required.
list, get on every resource.
whoami, doctor, schema, explain, config get, profile list.
*-log list / *-log get (request-log, event-log).
webhook event list / webhook event get.
Tier 2 — dry-run, then confirm
Mutating but reversible (or low-blast-radius). On the first invocation,
add --dry-run --json, show the user the request envelope (method + URL +
body), and proceed only after the user agrees.
create and update on every resource.
license validate, machine activate, machine ping, process spawn,
process ping.
license usage incr|decr|reset.
license check-out, license check-in, machine check-out.
artifact download, artifact upload (when uploading a brand-new file).
webhook endpoint test, webhook event retry.
release upgrade (read-only computation, but billable on Cloud — confirm).
Tier 3 — explicit approval, no shortcuts
Destructive or irreversible. Never pass --yes until the user has verbally
agreed to the exact command and target id. Restate the command and its
blast radius first.
delete on every resource.
license suspend, license reinstate, license renew, license revoke,
license transfer.
release publish, release yank, artifact yank.
user ban, user unban, user reset-password, user update-password.
process kill.
token regenerate.
- Any mutation aimed at a profile whose name contains
prod / production,
or the unnamed default profile when the host is api.keygen.sh.
Risk heuristics
Before running a Tier 2 or Tier 3 operation, raise the concern first if any
of these hold:
- The active profile looks like production (
prod, production, or the
default profile pointing at api.keygen.sh).
- The batch covers five or more resource ids.
- A write request lacks
--idempotency-key and the user has not opted into
retries being unsafe.
- The user asked for
delete / revoke without a recent get of the target.
- The command is EE-only (
event-log, request-log, env) but keygen doctor reports CE/Cloud — surface the capability mismatch instead of
hitting the API.
- Running
<resource> list --filter <relation>=<id> against a self-hosted
CE deployment without first running keygen doctor. Some CE versions
ignore relation filters silently; doctor's filters_relation check
surfaces the gap before you trust a result set.
Common patterns
# Issue a perpetual license for a known policy + user.
keygen license create --json \
--policy pol_abc --user usr_def \
--set attrs.name="Acme — Pro 2026" --metadata seat=enterprise
# Activate a machine and then ping it.
keygen machine activate --json --license lic_xyz --fingerprint $(uname -n)
keygen machine ping --json <machine_id>
# Cut a release and upload its binary.
keygen release create --json --product prod_abc --set attrs.version=1.4.0
keygen artifact upload --json --release rel_xyz --file ./dist/app-1.4.0.dmg
Walk-throughs:
examples/create-license.md,
examples/offline-verify.md.
Where to dig deeper
1---2name: keygen-cli3description: |4 keygen-cli — manage keygen.sh from the command line: products, policies, licenses,5 machines, releases, artifacts, webhooks, users, and tokens. Works against keygen.sh6 Cloud, self-hosted CE, and self-hosted EE. Use this skill whenever the user mentions:7 keygen.sh, license management, software licensing, license key, license activation,8 activate machine, suspend license, revoke license, renew license, release artifact9 upload, webhook endpoint, entitlement, policy, product token, offline license verify.10 All write operations require explicit human approval — see references/permissions.md11 for the three-tier rule set.12version: 0.3.113license: MIT14homepage: https://github.com/okooo5km/keygen-cli15author: okooo5km16metadata:17 source: https://skillmd.com/skills/okooo5km/keygen-cli18 binary: keygen19 alias: kg20 requires:21 bins: ["keygen"]22 install:23 - kind: brew24 formula: okooo5km/tap/keygen-cli25 bins: ["keygen", "kg"]26 - kind: cargo27 crate_git: https://github.com/okooo5km/keygen-cli28 references:29 installation: ./references/installation.md30 commands: ./references/commands.md31 permissions: ./references/permissions.md32 envelope: ./references/ai-envelope.md33 tui: ./references/tui.md34 recipes: ./references/recipes.md35---3637# keygen-cli3839A Rust CLI for [keygen.sh](https://keygen.sh). One binary, three deployments40(Cloud / self-hosted CE / self-hosted EE), and a stable JSON envelope built for41agents. Every command emits the same `{ ok, data, meta?, error? }` shape under42`--json`, and exit codes are documented and stable.4344## Setup4546```bash47brew install okooo5km/tap/keygen-cli # installs `keygen` and the `kg` alias48keygen --version49```5051Other paths (pre-built tarballs, `cargo install`, source) live in52[`references/installation.md`](./references/installation.md).5354## Authenticate5556```bash57keygen login # interactive: deployment → host → account → token58keygen whoami # confirm identity + detected capabilities59```6061Tokens land in the OS keyring (Keychain on macOS, Secret Service on Linux,62Credential Manager on Windows). For CI and ephemeral shells, set63`KEYGEN_TOKEN=...` instead — that path skips the keyring entirely. Switch64deployments with `--profile <name>` or `KEYGEN_PROFILE`.6566## Core invocation pattern6768Every resource exposes the same CRUD surface. Resource-specific actions69(validate, suspend, publish, ...) sit on the same subcommand tree.7071```bash72keygen <resource> list [--filter k=v] [--limit N] [--page N] [--sort field]73keygen <resource> get <id>74keygen <resource> create [--from-file body.json | --set attrs.x=y --metadata k=v]75keygen <resource> update <id> [--from-file body.json | --set ...]76keygen <resource> delete <id> --yes77```7879Two examples:8081```bash82keygen license list --filter status=ACTIVE --json83keygen license create --json --policy pol_abc --user usr_def --set attrs.name="Acme"84```8586`--json` (a `gh`-style shortcut for `--output json`) always emits the canonical87envelope. Exit codes: `0` ok, `1` user, `2` server, `3` network, `4` auth, `5`88capability. Full envelope schema in89[`references/ai-envelope.md`](./references/ai-envelope.md).9091## Self-discovery9293Two commands let an agent learn the full surface area without reading docs:9495```bash96keygen schema --format json # entire command tree (subcommands + flags)97keygen explain error <CODE> # diagnose any keygen.sh error code98```99100Use `schema` when you need to verify a flag exists or look up a subcommand.101Use `explain` whenever an envelope returns `error.code` — it returns the102canonical cause, fix, and a suggested next command.103104## Permission tiers105106Three tiers govern which operations need human approval. The full per-command107list is in [`references/permissions.md`](./references/permissions.md); apply108the rules below verbatim.109110### Tier 1 — auto-run111112Read-only inspection. Run freely, no confirmation required.113114- `list`, `get` on every resource.115- `whoami`, `doctor`, `schema`, `explain`, `config get`, `profile list`.116- `*-log list` / `*-log get` (request-log, event-log).117- `webhook event list` / `webhook event get`.118119### Tier 2 — dry-run, then confirm120121Mutating but reversible (or low-blast-radius). On the **first** invocation,122add `--dry-run --json`, show the user the request envelope (method + URL +123body), and proceed only after the user agrees.124125- `create` and `update` on every resource.126- `license validate`, `machine activate`, `machine ping`, `process spawn`,127 `process ping`.128- `license usage incr|decr|reset`.129- `license check-out`, `license check-in`, `machine check-out`.130- `artifact download`, `artifact upload` (when uploading a brand-new file).131- `webhook endpoint test`, `webhook event retry`.132- `release upgrade` (read-only computation, but billable on Cloud — confirm).133134### Tier 3 — explicit approval, no shortcuts135136Destructive or irreversible. Never pass `--yes` until the user has verbally137agreed to the *exact* command and target id. Restate the command and its138blast radius first.139140- `delete` on every resource.141- `license suspend`, `license reinstate`, `license renew`, `license revoke`,142 `license transfer`.143- `release publish`, `release yank`, `artifact yank`.144- `user ban`, `user unban`, `user reset-password`, `user update-password`.145- `process kill`.146- `token regenerate`.147- Any mutation aimed at a profile whose name contains `prod` / `production`,148 or the unnamed default profile when the host is `api.keygen.sh`.149150## Risk heuristics151152Before running a Tier 2 or Tier 3 operation, raise the concern *first* if any153of these hold:154155- The active profile looks like production (`prod`, `production`, or the156 default profile pointing at `api.keygen.sh`).157- The batch covers five or more resource ids.158- A write request lacks `--idempotency-key` and the user has not opted into159 retries being unsafe.160- The user asked for `delete` / `revoke` without a recent `get` of the target.161- The command is EE-only (`event-log`, `request-log`, `env`) but `keygen162 doctor` reports CE/Cloud — surface the capability mismatch instead of163 hitting the API.164- Running `<resource> list --filter <relation>=<id>` against a self-hosted165 CE deployment without first running `keygen doctor`. Some CE versions166 ignore relation filters silently; doctor's `filters_relation` check167 surfaces the gap before you trust a result set.168169## Common patterns170171```bash172# Issue a perpetual license for a known policy + user.173keygen license create --json \174 --policy pol_abc --user usr_def \175 --set attrs.name="Acme — Pro 2026" --metadata seat=enterprise176177# Activate a machine and then ping it.178keygen machine activate --json --license lic_xyz --fingerprint $(uname -n)179keygen machine ping --json <machine_id>180181# Cut a release and upload its binary.182keygen release create --json --product prod_abc --set attrs.version=1.4.0183keygen artifact upload --json --release rel_xyz --file ./dist/app-1.4.0.dmg184```185186Walk-throughs:187[`examples/create-license.md`](./examples/create-license.md),188[`examples/offline-verify.md`](./examples/offline-verify.md).189190## Where to dig deeper191192- [`references/installation.md`](./references/installation.md) — every install path.193- [`references/commands.md`](./references/commands.md) — full resource × action matrix.194- [`references/permissions.md`](./references/permissions.md) — authoritative tier list.195- [`references/ai-envelope.md`](./references/ai-envelope.md) — JSON shape + exit codes.196- [`references/tui.md`](./references/tui.md) — `keygen tui` keybindings and panels.197- [`references/recipes.md`](./references/recipes.md) — task-oriented cookbook198 (support, audit, release, batch ops, offline verify, troubleshooting).