Keygen CLI

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

• references/installation.md — every install path.
• references/commands.md — full resource × action matrix.
• references/permissions.md — authoritative tier list.
• references/ai-envelope.md — JSON shape + exit codes.
• references/tui.md — keygen tui keybindings and panels.
• references/recipes.md — task-oriented cookbook (support, audit, release, batch ops, offline verify, troubleshooting).