CLI
Kisenon 플랫폼을 위한 드롭인 neonctl 형태 클라이언트.
keon은 Kisenon 플랫폼을 위한 드롭인 neonctl 형태 클라이언트입니다.
macOS / Linux에 설치
curl -fsSL https://kisenon.com/install.sh | sh플랫폼을 감지하고, 일치하는 keon-<os>-<arch> 바이너리를 다운로드하며,
/dl/latest/manifest.json에 대해 sha256을 검증하고, ~/.local/bin에 설치합니다
(/usr/local/bin이 쓰기 가능하면, 예: root, 그쪽에 설치). 디렉터리가 PATH에 없으면
셸 rc 파일에 추가합니다. 스크립트는 POSIX sh이며 bash가 필요 없습니다.
Windows에 설치
기본 채널은 winget입니다:
winget install Seiraiyu.Keon또는 설치 스크립트를 직접 실행하세요:
irm https://kisenon.com/install.ps1 | iex%LOCALAPPDATA%\keon에 설치하고 사용자 PATH에 추가합니다.
설치 프로그램 환경 변수
모든 변수를 두 스크립트가 다 읽는 것은 아닙니다 — Scripts 열을 보세요.
curl | sh에서는 sh 쪽에 설정하세요:
curl -fsSL https://kisenon.com/install.sh | KEON_INSTALL_DIR=/opt/bin sh.
| Variable | Scripts | Default | |
|---|---|---|---|
KEON_INSTALL_VERSION | 둘 다 | latest | 릴리스를 고정합니다(예: v0.1.56). |
KEON_INSTALL_DIR | 둘 다 | ~/.local/bin (sh), %LOCALAPPDATA%\keon (PowerShell) | 설치 디렉터리. /usr/local/bin 대체 경로도 건너뜁니다. |
KEON_INSTALL_NO_PATH | 둘 다 | — | 1이면 PATH 수정을 건너뜁니다. |
KEON_INSTALL_HOST | 둘 다 | https://kisenon.com | 다운로드 호스트. https://여야 합니다. |
KEON_CONFIG_DIR | 둘 다 | ~/.config/keon | host 파일을 쓰는 위치. Windows에서는 KEON_HOST_FILE이 우선합니다. |
KEON_HOST_FILE | install.ps1 전용 | ~/.config/keon/host | host 파일 경로. |
KEON_API_URL_DEFAULT | 둘 다 | https://kisenon.com | 설치 시 host 파일에 기록되는 API 호스트. |
KEON_UNINSTALL | 둘 다 | 미설정 | 1이면 바이너리와 PATH 블록을 제거합니다. 자격 증명은 남습니다. |
KEON_INSTALL_FORCE | install.sh 전용 | 미설정 | 1이면 설치된 버전이 같아도 다시 내려받습니다. install.ps1에는 버전 일치 건너뛰기가 아예 없어 매번 다시 내려받으므로, 이 변수가 강제할 대상이 없습니다. |
첫 로그인
keon login
keon mekeon login은 루프백 OAuth 흐름을 실행합니다 — 키를 붙여 넣지 않아도
됩니다. 임의의 포트에서 로컬 리스너를 시작하고, 브라우저에서 콘솔의 인증
페이지를 열며, 리디렉션을 기다립니다. 인증하면 CLI가 일회성 코드를 POST /v1/cli/exchange에서 활성 조직으로 범위가 지정된
수명이 긴 nsk_ 접두사 API 키로 교환합니다.
키는 ~/.config/keon/credentials.json에 모드 0600으로 저장됩니다. CLI는
결과로 나온 키만 유지합니다 — OAuth 코드, state, 또는 제공자 토큰은 절대
보관하지 않습니다. keon logout은 파일을 제거하고
서버 측 키 폐기를 시도합니다(최선 노력: 실패해도 경고 후 0으로 종료); 설정 → API 키에서도 언제든지 폐기할 수
있습니다. 전체 흐름은 인증을 참조하세요.
Windows에서는 파일이 %USERPROFILE%\.config\keon\credentials.json에 있습니다.
모드 0600은 적용되지 않으며, 파일에는 프로필의 ACL — 당신의 사용자, SYSTEM,
Administrators만 — 이 적용됩니다.
자주 쓰는 명령
keon projects list
keon branches list --project <id>
keon connection-string <branch> --project <id>keon connection-string은 기본 출력 형식과 관계없이 직접 연결 URI만 출력합니다
(psql "$(keon connection-string main --project <id>)"가 그대로 동작합니다). --pooled는
풀러 URI를 출력하며, 엔드포인트에 풀러가 없으면 pooler_not_enabled로 1을 반환하고
종료합니다. -o json은 {"connection_string": "…"}를 반환합니다.
프로젝트를 삭제하면 그 브랜치와 엔드포인트도 삭제됩니다 — --cascade를
전달하세요. 그렇지 않으면 main 외의 브랜치가 있을 때 API가
409 has_branches를 반환합니다:
keon projects delete <id> --cascade동일한 --cascade 플래그가 keon branches delete <id>에도 적용됩니다.
keon status
keon statusCLI가 유효한 자격 증명을 가지고 있는지 보고합니다. 키를 /v1/auth/whoami로
검증하므로, 취소되거나 만료된 키는 오래된 성공 대신 authenticated: false로
보고됩니다. 본문에는 항상 .authenticated와 latencyMs가 들어가며, api_url,
user, token_id는 저장된 자격 증명을 사용할 때 채워집니다.
스크립트가 분기해야 하는 것은 종료 코드입니다:
| Exit | |
|---|---|
0 | 인증됨 — 키가 /v1/auth/whoami로 검증되었습니다. |
1 | 인증되지 않음 — 자격 증명이 없거나 cp가 401/403을 반환했습니다. |
2 | 판단 불가 — 연결 거부, DNS 실패, 타임아웃 또는 5xx. |
2가 1이 아닌 것은 의도적입니다. 컨트롤 플레인에 도달할 수 없다는 사실이 자격
증명이 잘못됐다는 증거는 아니며, keon status && deploy.sh는 두 경우 모두 멈춰야
합니다. 종료 코드는 직접 읽으세요 — keon status를 다른 명령으로 파이프하면
파이프라인의 종료 코드로 바뀝니다.
에이전트 워크플로
keon은 프로젝트와 브랜치뿐 아니라 에이전트 안전 표면을 다룹니다:
keon sandbox— 에이전트 샌드박스를 구동합니다: 에이전트를 위한 임시 캡처 앤 프로모트 데이터베이스 환경.keon ledger— 프로모트 원장을 읽고 캡처/프로모트 증명을 검증합니다.keon ip-allow— 프로젝트의 IP 허용 목록을 관리합니다.
다른 최상위 명령으로는 orgs, endpoints, databases, roles,
snapshots, operations, usage, 그리고 audit가 있습니다. 전체
집합은 keon --help를 실행하세요.
출력 형식
기본값은 JSON입니다. 테이블의 경우: keon config set output table을
사용하거나, 명령별로 --output table을 전달하세요.
Claude 스킬 설치
keon install --skills./.claude/skills/keon/에 SKILL.md + 참조 문서를 떨어뜨려 Claude 에이전트가
설정 단계 없이 CLI를 구동할 수 있게 합니다.
문제 해결
macOS: "developer cannot be verified"
Gatekeeper 속성이 설정된 채 브라우저로 바이너리를 다운로드한 경우에만
발생합니다(install.sh는 이 속성을 설정하지 않습니다). 다음으로 속성을 제거하세요:
xattr -d com.apple.quarantine $(which keon)Windows: SmartScreen 경고
"More info" → "Run anyway"를 클릭하세요. 머신당 한 번입니다. winget install Seiraiyu.Keon으로 설치하면 이 프롬프트를 피할 수 있습니다.
Windows 빌드의 SmartScreen 평판은 시간이 지나면서 쌓입니다.
Windows: winget upgrade가 패키지가 "수정되었다"고 표시하는 경우
0.1.59 이하의 keon update가 winget으로 설치한 바이너리를 교체했다면
winget upgrade Seiraiyu.Keon은 Unable to remove Portable package as it has been
modified로 실패합니다. winget은 설치 시 원본 파일의 해시를 기록해 두고, 변경된 파일을
덮어쓰기를 거부합니다. 한 번만 검사를 무시하세요.
winget upgrade Seiraiyu.Keon --force그 후에는 winget list와 keon --version이 다시 일치합니다. 현재 keon은 winget
설치의 자체 업데이트를 거부하므로 이 문제는 재발하지 않습니다.
macOS: 서명된 바이너리
install.sh가 받는 keon-macos-universal만 서명 및 공증되어 있습니다.
아키텍처별 keon-macos-arm64와 keon-macos-x64는 서명되지 않았습니다.
macOS: Gatekeeper 검증에는 네트워크 연결이 필요합니다
keon-macos-universal은 공증되어 있지만 공증 티켓을 스테이플할 수는 없습니다. stapler는 번들과 컨테이너(.app, .pkg, .dmg)에만 티켓을 붙일 수 있고, 순수 Mach-O 실행 파일에는 붙일 수 없기 때문입니다. 따라서 Gatekeeper는 티켓을 온라인으로 조회하며, 오프라인이거나 Apple의 공증 서비스를 차단하는 Mac은 다운로드를 검증할 수 없습니다.
이는 일반적인 CLI 사용에는 영향을 주지 않습니다. Gatekeeper의 격리 검사는 execve가 아니라 LaunchServices(Finder에서 더블클릭)를 통해 실행되므로, 터미널에서 실행한 바이너리는 스테이플 여부와 관계없이 차단되지 않습니다. curl 및 install.sh 경로는 격리 속성을 아예 설정하지 않습니다.