CLI

keon é um cliente drop-in no formato neonctl para a plataforma Kisenon.

Instalar no macOS / Linux

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

Detecta sua plataforma, baixa o binário keon-<os>-<arch> correspondente, verifica o sha256 contra /dl/latest/manifest.json, e instala em ~/.local/bin — ou em /usr/local/bin se esse diretório for gravável (ex.: como root). Se o diretório não estiver no PATH, o script o adiciona ao arquivo rc do seu shell. O script é POSIX sh; bash não é necessário.

Instalar no Windows

O canal primário é o winget:

winget install Seiraiyu.Keon

Ou execute o script de instalação diretamente:

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

Ele instala em %LOCALAPPDATA%\keon e adiciona o diretório ao PATH do usuário.

Variáveis de ambiente do instalador

Nem toda variável é lida pelos dois scripts — a coluna Scripts diz quais. Com curl | sh, defina-as do lado do sh: curl -fsSL https://kisenon.com/install.sh | KEON_INSTALL_DIR=/opt/bin sh.

Primeiro login

keon login
keon me

keon login executa um fluxo de OAuth por loopback — sem colar chaves. Ele inicia um listener local em uma porta aleatória, abre seu navegador na página de autorização do console, e aguarda o redirecionamento. Após você autorizar, a CLI troca o código de uso único em POST /v1/cli/exchange por uma chave de API de vida longa com prefixo nsk_, escopada à sua organização ativa.

A chave é persistida em ~/.config/keon/credentials.json com modo 0600. A CLI mantém apenas a chave resultante — nunca o código de OAuth, o estado, ou qualquer token do provedor. keon logout remove o arquivo e tenta revogar a chave no servidor (best-effort: se falhar, avisa e ainda sai com 0); você também pode revogá-la a qualquer momento em Settings → API keys. Veja Autenticação para o fluxo completo.

No Windows o arquivo é %USERPROFILE%\.config\keon\credentials.json; o modo 0600 não se aplica lá, e o arquivo carrega a ACL do seu perfil — somente seu usuário, SYSTEM e Administrators.

Comandos comuns

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

keon connection-string imprime só a URI direta (assim psql "$(keon connection-string main --project <id>)" funciona), qualquer que seja o formato de saída padrão. --pooled imprime a URI do pooler e sai com 1 e pooler_not_enabled se o endpoint não tiver pooler. -o json retorna {"connection_string": "…"}.

Excluir um projeto também exclui seus branches e endpoints — passe --cascade; senão, a API retorna 409 has_branches quando o projeto tem algum branch além do main:

keon projects delete <id> --cascade

A mesma flag --cascade se aplica a keon branches delete <id>.

keon status

keon status

Informa se a CLI tem uma credencial que funciona. A chave é validada contra /v1/auth/whoami, então uma chave revogada ou expirada informa authenticated: false em vez de um sucesso desatualizado. O corpo sempre traz .authenticated e latencyMs; api_url, user e token_id são preenchidos quando uma credencial armazenada está em uso.

O código de saída é o que um script deve testar:

2 não é 1 de propósito: um control plane inalcançável não prova que sua credencial está ruim, e keon status && deploy.sh precisa parar nos dois casos. Leia o código de saída direto — mandar keon status por um pipe o substitui pelo do pipeline.

Fluxos de agente

O keon cobre a superfície segura para agentes, não apenas projetos e branches:

• keon sandbox — conduz sandboxes de agente: ambientes de banco de dados efêmeros de captura-e-promoção para agentes.
• keon ledger — lê o ledger de promoção e verifica atestados de captura/promoção.
• keon ip-allow — gerencia a allowlist de IP de um projeto.

Outros comandos de nível superior incluem orgs, endpoints, databases, roles, snapshots, operations, usage e audit. Execute keon --help para o conjunto completo.

Formato de saída

O padrão é JSON. Para tabelas: keon config set output table, ou passe --output table por comando.

Instalar a skill do Claude

keon install --skills

Coloca um SKILL.md + docs de referência em ./.claude/skills/keon/ para que um agente Claude possa conduzir a CLI sem um turno de configuração.

Solução de problemas

macOS: "developer cannot be verified"

Só acontece quando o binário foi baixado por um navegador com o atributo do Gatekeeper definido — o install.sh não o define. Remova-o:

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

Windows: aviso do SmartScreen

Clique em "More info" → "Run anyway". Uma vez por máquina. Instalar via winget install Seiraiyu.Keon evita o prompt. A reputação do SmartScreen nas builds do Windows se constrói com o tempo.

Windows: winget upgrade diz que o pacote "foi modificado"

winget upgrade Seiraiyu.Keon falha com Unable to remove Portable package as it has been modified se um keon update da versão 0.1.59 ou anterior substituiu o binário instalado pelo winget. O winget registrou o hash do arquivo original na instalação e se recusa a sobrescrever um arquivo alterado. Ignore a verificação uma vez:

winget upgrade Seiraiyu.Keon --force

Depois disso, winget list e keon --version voltam a concordar. O keon atual se recusa a se autoatualizar em uma instalação do winget, então isso não se repete.

macOS: qual binário é assinado

Só o keon-macos-universal — o que o install.sh baixa — é assinado e notarizado. Os binários por arquitetura, keon-macos-arm64 e keon-macos-x64, não são.

macOS: o Gatekeeper precisa de acesso à rede para validar

O keon-macos-universal é notarizado, mas o tíquete de notarização não pode ser grampeado: o stapler anexa tíquetes a bundles e contêineres (.app, .pkg, .dmg), não a um executável Mach-O puro. Por isso o Gatekeeper resolve o tíquete on-line, e um Mac off-line ou que bloqueie o serviço de notarização da Apple não consegue validar o download.

Isso não afeta o uso normal da CLI. A verificação de quarentena do Gatekeeper passa pelo LaunchServices — duplo clique no Finder — e não pelo execve, então um binário iniciado a partir de um terminal nunca é bloqueado, grampeado ou não. Os caminhos curl e install.sh não definem o atributo de quarentena.

Abrir um bug

github.com/Seiraiyu/Kisenon/issues