Kilo Code CLI 명령어 총정리

오픈소스 코딩 에이전트 Kilo Code의 CLI(kilo)를 실무에서 쓸 때 필요한 명령어·슬래시 명령·권한 시스템·설정 파일을 한 번에 정리했습니다. Kilo CLI는 OpenCode를 포크한 구조라 설정 체계도 OpenCode와 상당 부분 호환됩니다.

이 정리는 Kilo CLI 1.0 이상 기준입니다. 1.0 미만 버전에서는 명령어 체계(구 .roo/.kilocode 설정, Memory Bank 등)가 다르니 먼저 kilo --version으로 버전을 확인하고, kilo --help / kilo help <command> --all로 실제 지원 여부를 재확인하세요. Orchestrator 모드는 지원 중단(deprecated) 예정이라 신규로는 쓰지 않는 걸 권장합니다.

1. 설치 및 버전 확인

# npm으로 설치 (권장)
npm install -g @kilocode/cli
# 그 외 설치 방법
curl -fsSL https://kilo.ai/cli/install | bash
pnpm add -g @kilocode/cli
bun add -g @kilocode/cli
brew install Kilo-Org/tap/kilo        # macOS / Linux
paru -S kilo-bin                       # Arch Linux (AUR)

# 버전 확인
kilo --version
# 최신 버전으로 업데이트
kilo upgrade
npm update -g @kilocode/cli
# 특정 버전으로 업그레이드/다운그레이드
kilo upgrade 0.1.48
# 완전 삭제 (설정/세션 유지 옵션 있음)
kilo uninstall --keep-config --keep-data

AVX 명령어 셋을 지원하지 않는 구형 CPU(Intel Xeon Nehalem, AMD Bulldozer 등)에서는 "Illegal instruction" 오류가 날 수 있습니다. 이 경우 GitHub Releases에서 -baseline 빌드(예: kilo-linux-x64-baseline.tar.gz)를 받아 바이너리를 직접 실행하세요.

2. 최초 설정 & 인증

# 처음 실행 후, 대화 중 슬래시 명령으로 프로바이더(API 키) 연결
kilo
/connect

# CLI에서 직접 로그인/인증 관리
kilo auth login              # 프로바이더 로그인 (대화형 선택)
kilo auth login --provider anthropic --method apikey
kilo auth list                # 등록된 프로바이더·자격증명 목록
kilo auth logout              # 로그아웃

Kilo는 500개 이상의 모델·60개 이상의 프로바이더를 지원하며, 자체 Kilo Gateway를 통해 마크업 없이 프로바이더 원가로 과금됩니다. API 키를 직접 등록해서 써도 되고, Kilo 계정으로 로그인해서 Gateway를 통해 써도 됩니다.

3. 기본 실행 모드

# 현재 디렉토리에서 대화형 TUI 시작
kilo
# 특정 프로젝트 경로에서 시작
kilo /path/to/project

# 프롬프트 하나만 던지고 결과 받기 (비대화형)
kilo run "signup 폼에 입력값 검증 추가해줘"
# 모델을 provider/model 형식으로 직접 지정
kilo run -m anthropic/claude-sonnet-4-20250514 "utils.ts 리팩터링해줘"
# 특정 에이전트 지정
kilo run --agent plan "캐싱 레이어 설계해줘"
# 파일을 컨텍스트로 첨부
kilo run -f src/auth.ts -f src/middleware.ts "보안 관점에서 리뷰해줘"
# JSON(raw 이벤트) 형식으로 출력 (파이프라인/스크립트용)
kilo run --format json "테스트 결과 요약해줘"

# 마지막 세션 이어서 작업 (같은 워크스페이스 기준)
kilo --continue
kilo -c
# 이어서 작업하되 새 분기로 포크
kilo run --continue --fork "에러 핸들링도 추가해줘"

# 헤드리스 서버 실행 후 원격에서 붙기
kilo serve --port 4096
kilo attach http://localhost:4096
# 서버까지 띄우고 브라우저 콘솔로 바로 열기
kilo web

--continue는 자동 모드(--auto)나 프롬프트 인자와 함께 쓸 수 없고, 해당 워크스페이스에 이전 세션이 없으면 오류로 종료됩니다.

4. 전체 최상위(top-level) 명령어

명령어	기능
kilo [project]	해당 경로에서 TUI 시작
kilo run [message]	메시지와 함께 비대화형 실행
kilo attach <url>	실행 중인 kilo 서버에 접속
kilo serve	헤드리스 서버 실행
kilo web	서버 실행 + 웹 인터페이스 오픈
kilo acp	Agent Client Protocol 서버 실행 (에디터 연동용)
kilo mcp	MCP 서버 추가/목록/OAuth 인증 관리
kilo auth	프로바이더/자격증명 관리 (login, logout, list)
kilo agent	에이전트 생성(create) 및 목록(list) 조회
kilo models [provider]	사용 가능한 모델 목록 (비용 등 메타데이터 포함 가능)
kilo roll-call <filter>	정규식으로 필터링한 모델들을 일괄 연결성·지연시간 테스트
kilo profile	Kilo 계정 프로필 확인
kilo stats	토큰 사용량·비용 통계 확인 (기간/도구/모델/프로젝트별 필터)
kilo session	세션 목록 조회(list), 삭제(delete)
kilo export [sessionID]	세션 데이터를 JSON으로 내보내기 (민감정보 마스킹 옵션)
kilo import <file>	JSON 파일 또는 공유 URL에서 세션 가져오기
kilo github	GitHub 에이전트 설치(install)/실행(run)
kilo pr <number>	GitHub PR 브랜치를 체크아웃하고 바로 kilo 실행
kilo remote	실시간 세션 릴레이용 원격 연결 활성화
kilo daemon	로컬 kilo 데몬 시작/상태확인/중지/재시작
kilo console	로컬 Kilo Console(설정용 웹 UI) 열기/중지
kilo db	세션 DB용 SQLite 셸/쿼리/마이그레이션 도구
kilo config check	설정 파일의 경고·오류 검사
kilo plugin <module>	npm 모듈 형태의 플러그인 설치 및 설정 반영
kilo debug	LSP·ripgrep·파일시스템·스냅샷 등 진단 도구 모음
kilo upgrade / uninstall	버전 업그레이드 / 완전 제거
kilo help [command]	전체 CLI 레퍼런스 출력 (--all로 전체, md/text 형식 선택)
kilo completion	셸 자동완성 스크립트 생성

각 명령어의 세부 옵션은 kilo <command> --help로 바로 확인할 수 있고, 전체 옵션을 한 번에 보려면 kilo help --all을 사용하세요.

5. 슬래시 명령어 총정리 (대화형 모드 전용)

세션 관리

명령어	별칭	기능
/sessions	/resume, /continue	세션 전환
/new	/clear	새 세션 시작
/share / /unshare	-	세션 공유 / 공유 해제
/rename	-	세션 이름 변경
/timeline	-	특정 메시지 지점으로 이동
/fork	-	특정 메시지에서 세션 분기
/compact	/summarize	세션 컨텍스트 요약/압축
/undo / /redo	-	직전 메시지 되돌리기 / 다시 적용
/copy	-	최신 에이전트 응답 복사
/copy-session	-	세션 전체 대화 복사
/export	-	세션 대화 내보내기
/timestamps	/toggle-timestamps	타임스탬프 표시/숨김
/thinking	/toggle-thinking	추론(thinking) 블록 표시/숨김

에이전트 & 모델 / 프로바이더

명령어	기능
/models	사용할 모델 전환
/agents	사용할 에이전트(모드) 전환
/mcps	연결된 MCP 서버 켜기/끄기 토글
/connect	프로바이더(API 자격증명) 최초 연결/추가

시스템 / Kilo Gateway

명령어	별칭	기능
/status	-	현재 세션 상태 확인
/themes	-	테마 전환
/editor	-	외부 에디터로 열기
/exit	/quit, /q	세션 종료
/profile	/me, /whoami	Kilo Gateway 프로필 확인
/teams	/team, /org, /orgs	Kilo Gateway 팀(조직) 전환
/remote	-	Cloud Agent 원격 접속용 리모트 모드 토글

내장 명령 & 로컬 코드 리뷰

명령어	기능
/init	프로젝트용 AGENTS.md 생성/업데이트
/review	스테이징/언스테이징/추적되지 않은 변경사항 리뷰 (인자 없을 때 기본 동작)
/review uncommitted [지침]	커밋되지 않은 변경사항을 추가 지침과 함께 리뷰
/review branch [base] [지침]	현재 브랜치를 base와 비교해서 리뷰
/review <commit-hash>	특정 커밋 리뷰
/review <PR URL 또는 번호>	PR 리뷰

6. 에이전트(모드) 구조

Kilo는 작업 성격에 따라 서로 다른 "에이전트"로 전환해서 씁니다. Orchestrator는 지원 중단 예정이며, Code/Plan/Debug처럼 풀 툴 액세스를 가진 에이전트가 이제 네이티브로 서브에이전트를 호출할 수 있어 별도 오케스트레이터가 필요 없습니다.

Code (기본값)

자연어 지시로 여러 파일에 걸쳐 코드를 생성·수정. 셸 명령 실행 가능.

Plan

코드를 작성하기 전에 구조·구현 계획을 먼저 세움. 구 Architect에 대응.

Ask

파일을 건드리지 않고 코드베이스에 대한 질문에 답변. 탐색·학습용.

Debug

에러를 읽고 원인을 추적해서 수정안을 제안.

공식 CLI/VSCode 확장에는 별도의 "Review 에이전트"가 내장되어 있지 않습니다. 코드 리뷰는 Code 에이전트나 커스텀 에이전트, 또는 위에서 소개한 /review 슬래시 명령(로컬 코드 리뷰 워크플로)으로 처리합니다.

# CLI에서 에이전트 목록 확인
kilo agent list
# 커스텀 서브에이전트 생성 (읽기/grep/glob만 허용하는 보안 리뷰어 예시)
kilo agent create \
  --path .kilo \
  --description "보안 취약점 리뷰 전용 에이전트" \
  --mode subagent \
  --tools "read,grep,glob"

커스텀 에이전트는 YAML 프론트매터가 있는 마크다운 파일로도 정의할 수 있습니다. 파일명(확장자 제외)이 곧 에이전트 이름이 됩니다.

<code"># .kilo/agent/reviewer.md
---
description: 코드 품질과 베스트 프랙티스를 리뷰
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
permission:
  edit: deny
  bash: deny
---
당신은 코드 리뷰어입니다. 다음을 분석하세요:
- 코드 품질과 베스트 프랙티스
- 잠재적 버그와 엣지 케이스
- 성능에 미치는 영향
- 보안 고려사항
직접 수정하지 말고 건설적인 피드백만 제공하세요.

7. 권한(Permission) 시스템

Kilo는 각 도구 호출을 allow(자동 실행) / ask(승인 요청) / deny(차단) 셋 중 하나로 판정합니다. 전역 설정과 세부 규칙을 조합해서 씁니다.

<code"># kilo.jsonc
{
  "$schema": "https://app.kilo.ai/config.json",
  "permission": {
    "*": "ask",
    "bash": "allow",
    "edit": "deny"
  }
}

# 더 세밀하게: 도구별로 패턴 매칭 규칙 지정 (뒤에 오는 규칙이 우선)
{
  "$schema": "https://app.kilo.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny",
      "grep *": "allow"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/content/docs/*.mdx": "allow"
    },
    "external_directory": {
      "~/projects/personal/**": "allow"
    }
  }
}

패턴은 *(0개 이상의 임의 문자), ?(임의의 문자 1개) 와일드카드를 지원하고, ~ 또는 $HOME으로 홈 디렉토리를 참조할 수 있습니다. external_directory 규칙을 쓰면 작업 디렉토리 밖 경로도 read/edit/glob/grep 등 도구가 접근하도록 허용할 수 있습니다. Ask/Plan 모드에서는 external_directory allow 규칙이 있어도 그 모드가 원래 막는 쓰기·변경 작업까지 열어주지는 않습니다.

대화형 모드에서 실행 승인 요청은 계층적으로 표시됩니다. 예를 들어 git status --short --branch 실행을 승인할 때 "Run Command"뿐 아니라 "Always run git", "Always run git status" 등 더 넓은 패턴으로도 승인할 수 있고, 선택한 패턴만 permission.bash에 allow 규칙으로 저장됩니다.

8. 자동/비대화형 실행 (CI 연동)

# 완전 자동 모드로 실행 (모든 승인 프롬프트 생략)
kilo run --auto "기능 X를 구현해줘"

# GitHub Actions 예시
# - name: Run Kilo Code
#   run: kilo run "새 기능을 구현해줘" --auto

# 명시적으로 거부되지 않은 것만 자동 승인 (완전 자동보다는 한 단계 보수적, 여전히 위험할 수 있음)
kilo run --dangerously-skip-permissions "린트 에러 고쳐줘"

--auto는 모든 권한 프롬프트를 비활성화하고 에이전트가 확인 없이 모든 작업을 실행하도록 합니다. 자동 모드에서 에이전트가 후속 질문을 하면 "사용자가 결정할 수 없으니 자율적으로 판단하라"는 응답이 자동으로 전달되고, 작업이 끝나거나 타임아웃되면 CLI가 자동 종료됩니다.

종료 코드	의미
0	성공 (작업 완료)
124	타임아웃 (제한 시간 초과)
1	오류 (초기화 또는 실행 실패)

9. 설정 파일 & 위치

범위	경로
전역	~/.config/kilo/kilo.json[c] (레거시 opencode.json[c]도 인식)
프로젝트	./kilo.json[c], ./.kilo/ 내부 설정 (레거시 ./.kilocode/도 인식)
TUI 설정(테마·알림·단축키)	~/.config/kilo/tui.jsonc (프로젝트 단위는 .kilo/tui.json[c])

프로젝트 설정이 전역 설정보다 우선 적용됩니다.

<code"># kilo.jsonc 주요 옵션
{
  "$schema": "https://app.kilo.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "provider": {
    "anthropic": {
      "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" }
    }
  },
  "instructions": ["CONTRIBUTING.md", ".cursor/rules/*.md"],
  "formatter": true,
  "lsp": false,
  "mcp": { /* MCP 서버 설정 */ }
}

주요 키: model(기본 모델, provider_id/model_id 형식), provider(프로바이더별 API 키·베이스URL·커스텀 모델), permission(권한 규칙), instructions(추가로 읽어들일 지침 파일 경로), formatter/lsp(포매터·언어서버 on/off 또는 세부 설정), disabled_providers/enabled_providers.

환경 변수로도 오버라이드 가능합니다: KILO_PROVIDER(활성 프로바이더 지정), kilocode 프로바이더는 KILOCODE_<FIELD>, 그 외 프로바이더는 KILO_<FIELD> 형식(예: KILO_API_KEY → apiKey).

10. AGENTS.md & 프로젝트 컨텍스트

AGENTS.md는 Kilo Code, Cursor, Windsurf 등 여러 AI 코딩 도구가 공통으로 지원하는 표준 규칙 파일입니다. 존재하면 항상 자동으로 로드되며(개별적으로 끌 수 없음), 우선순위를 더 높이고 싶으면 instructions 설정 키나 에이전트별 프롬프트를 사용합니다. 구버전의 Memory Bank(.kilocode/rules/memory-bank/의 context.md/brief.md/history.md)를 쓰고 있었다면, 그 내용을 AGENTS.md로 옮기는 마이그레이션이 권장됩니다.

<code"># 대화 중 AGENTS.md 생성/업데이트
/init

11. MCP 서버 연동

<code"># MCP 서버 추가 (대화형 진행)
kilo mcp add
# 연결된 MCP 서버와 상태 목록
kilo mcp list
# OAuth 기반 MCP 서버 인증
kilo mcp auth 
kilo mcp auth list
# 인증 해제 / 연결 디버깅
kilo mcp logout 
kilo mcp debug 

# 대화 중에는 슬래시 명령으로 토글
/mcps

12. 세션 관리 & 원격 접속

<code"># 세션 목록 (최근 N개, 검색, 전체 프로젝트)
kilo session list -n 10 --search "auth" --all
# 세션 삭제
kilo session delete 
# 세션 내보내기/가져오기
kilo export  --sanitize
kilo import ./session.json

# Cloud Agents 웹에서 로컬 세션을 원격으로 이어받기
/remote
# 또는 기본값으로 상시 활성화
# ~/.config/kilo/config.json
# { "remote_control": true }

원격 모드를 켜면 같은 Kilo 계정에 접근할 수 있는 누구든 내 컴퓨터로 메시지를 보낼 수 있습니다. 신뢰할 수 있는 환경에서만 활성화하세요.

13. 진단 / 디버깅 도구

<code"># 실제 적용 중인 설정 확인
kilo debug config
kilo config check

# 파일시스템/검색 관련 디버깅
kilo debug rg tree
kilo debug rg search "TODO" --glob "*.ts"
kilo debug file tree src/

# 에이전트 설정 상세 확인
kilo debug agent code

# 전역 경로(데이터/설정/캐시/상태) 확인
kilo debug paths
# 시작 시간 프로파일링
kilo debug startup

14. 유용한 조합 정리

상황	추천 명령/설정
처음 설치 후 프로바이더 연결	kilo 실행 → /connect
설계부터 하고 코드는 나중에	kilo run --agent plan "..."
코드베이스 탐색만, 파일은 건드리지 않기	/agents로 Ask 전환
CI/CD에서 완전 자동 실행	kilo run --auto "..."
PR을 로컬로 가져와 바로 작업	kilo pr <PR번호>
푸시 전에 로컬에서 코드 리뷰	/review 또는 /review branch main
토큰 사용량·비용 파악	kilo stats --days 30 --models
설정이 꼬였을 때	kilo config check, kilo debug config
외부 도구(GitHub 등) 연동	kilo mcp add 후 kilo mcp list로 확인
휴대폰/웹에서 로컬 세션 확인	/remote 후 Cloud Agents 대시보드 접속

마무리

Kilo CLI는 Codex CLI와 달리 500개 이상 모델을 자유롭게 오가며 쓰는 게 핵심 특징이고, 권한 시스템도 allow/ask/deny 세 값과 와일드카드 패턴으로 비교적 단순하게 설계되어 있습니다. 처음엔 /connect로 프로바이더를 연결하고 Code 에이전트 기본값으로 시작한 뒤, AGENTS.md와 permission 설정을 프로젝트에 맞게 다듬어가는 흐름을 추천합니다.