CLI

keon is a drop-in neonctl-shape client for the Kisenon platform.

Install on macOS / Linux

curl -fsSL https://kisenon.com/install.sh | sh

Detects your platform, downloads the matching keon-<os>-<arch> binary, verifies the sha256 against /dl/latest/manifest.json, and installs into ~/.local/bin — or /usr/local/bin if that directory is writable (e.g. as root). It adds the directory to PATH in your shell rc file if it is not already there. The script is POSIX sh; bash is not required.

Install on Windows

The primary channel is winget:

winget install Seiraiyu.Keon

Or run the install script directly:

irm https://kisenon.com/install.ps1 | iex

It installs into %LOCALAPPDATA%\keon and adds that to your user PATH.

Installer environment variables

Not every variable is read by both scripts — the Scripts column says which. With curl | sh, set them on the sh side: curl -fsSL https://kisenon.com/install.sh | KEON_INSTALL_DIR=/opt/bin sh.

First login

keon login
keon me

keon login runs a loopback OAuth flow — no pasting keys. It starts a local listener on a random port, opens your browser to the console's authorize page, and waits for the redirect. After you authorize, the CLI exchanges the one-shot code at POST /v1/cli/exchange for a long-lived nsk_-prefixed API key, scoped to your active organization.

The key is persisted at ~/.config/keon/credentials.json with mode 0600. On Windows the file is %USERPROFILE%\.config\keon\credentials.json; mode 0600 does not apply there, and the file carries your profile's ACL — your user, SYSTEM and Administrators only. The CLI keeps only the resulting key — never the OAuth code, state, or any provider token. keon logout removes the file and tries to revoke the key server-side (best-effort: it warns and still exits 0 if the revoke fails); you can also revoke it any time from Settings → API keys. See Auth for the full flow.

Common commands

keon projects list
keon branches list --project <id>
keon connection-string <branch> --project <id>

keon connection-string prints the bare direct URI (so psql "$(keon connection-string main --project <id>)" works), whatever your output default is. --pooled prints the pooler URI instead and exits 1 with pooler_not_enabled if the endpoint has no pooler. -o json returns {"connection_string": "…"}.

Deleting a project also deletes its branches and endpoints — pass --cascade, or, if the project has any branch besides main, the API returns 409 has_branches:

keon projects delete <id> --cascade

The same --cascade flag applies to keon branches delete <id>.

keon status

keon status

Reports whether the CLI holds a working credential. It validates the key against /v1/auth/whoami, so a revoked or expired key reports authenticated: false rather than a stale success. The body always carries .authenticated and latencyMs; api_url, user and token_id are filled in when a stored credential is in use.

The exit code is the part a script should branch on:

2 is deliberately not 1: an unreachable control plane is not proof that your credential is bad, and keon status && deploy.sh must stop in both cases. Read the exit code directly — piping keon status into another command replaces it with the pipeline's.

Agent workflows

keon covers the agent-safe surface, not just projects and branches:

• keon sandbox — drive agent sandboxes: ephemeral, capture-and-promote database environments for agents.
• keon ledger — read the promote ledger and verify capture/promote attestations.
• keon ip-allow — manage a project's IP allowlist.

Other top-level commands include orgs, endpoints, databases, roles, snapshots, operations, usage, and audit. Run keon --help for the full set.

Output format

Default is JSON. For tables: keon config set output table, or pass --output table per command.

Install the Claude skill

keon install --skills

Drops a SKILL.md + reference docs into ./.claude/skills/keon/ so a Claude agent can drive the CLI without a setup turn.

Troubleshooting

macOS: "developer cannot be verified"

Only happens when the binary was downloaded via a browser with the Gatekeeper attribute set — install.sh does not set it. Strip it:

xattr -d com.apple.quarantine $(which keon)

Windows: SmartScreen warning

Click "More info" → "Run anyway". Once per machine. Installing via winget install Seiraiyu.Keon avoids the prompt. SmartScreen reputation on Windows builds over time.

Windows: winget upgrade says the package "has been modified"

winget upgrade Seiraiyu.Keon fails with Unable to remove Portable package as it has been modified if a keon update from 0.1.59 or earlier replaced the winget-installed binary. winget recorded the original file's hash at install time and refuses to overwrite a changed one. Override the check once:

winget upgrade Seiraiyu.Keon --force

After that, winget list and keon --version agree again. Current keon refuses to self-update a winget install, so this does not recur.

macOS: which binary is signed

Only keon-macos-universal — the one install.sh fetches — is signed and notarized. The per-architecture keon-macos-arm64 and keon-macos-x64 binaries are not.

macOS: Gatekeeper needs network access to validate

keon-macos-universal is notarized, but the notarization ticket cannot be stapled to it: stapler attaches tickets to bundles and containers (.app, .pkg, .dmg), not to a bare Mach-O executable. Gatekeeper therefore resolves the ticket online, and a Mac that is offline or blocks Apple's notarization service cannot validate the download.

This does not affect normal CLI use. Gatekeeper's quarantine check runs through LaunchServices — double-clicking in Finder — not through execve, so a binary launched from a terminal is never blocked, stapled or not. The curl and install.sh paths do not set the quarantine attribute at all.

File a bug

github.com/Seiraiyu/Kisenon/issues