CLI 개요 및 환경

Revka는 단일 Rust 바이너리 revka로 제공되며, 메모리 네이티브 AI 에이전트의 전체 라이프사이클을 담당합니다. 최초 설정, 대화형 및 단발성 에이전트 세션, HTTP/WebSocket 게이트웨이와 내장 대시보드, 채널 통합, 스케줄링, OS 서비스 관리, 긴급 정지 안전 기능, 메모리 검사, 모델 카탈로그 관리, 하드웨어 제어, 진단까지 모두 포함합니다. 이 페이지는 해당 기능들의 전체 구조를 설명합니다. 명령어 그룹, 전역 플래그, Revka의 설정 디렉토리 결정 방식, 설정 스키마 내보내기, 그리고 환경 변수 전체 레퍼런스를 다룹니다.

모든 명령어는 오프라인으로 실행됩니다. 실행 중인 데몬은 게이트웨이와 통신하는 작업(예: revka pair token 또는 revka status --format exit-code)에만 필요하며, 그 외 모든 작업은 데몬 없이 동작합니다. 환경 변수가 동등한 config.toml 키를 덮어쓰기 때문에, Revka는 CI/CD 및 컨테이너 배포 환경에서 완전히 스크립트 방식으로 구성할 수 있습니다.

처음 시작하는 경우, 먼저 바이너리를 설치하고(설치), revka onboard를 실행한 뒤 빠른 시작을 따라 진행하세요.

명령어 구조

모든 호출은 동일한 형식을 따릅니다. 선택적 전역 플래그, 명령어, 선택적 서브명령어, 그리고 플래그 순서입니다.

revka [--config-dir <PATH>] <command> [subcommand] [flags]

revka onboard --api-key "sk-..." --provider openrouter
revka --config-dir /srv/revka daemon -p 8080
revka doctor traces --event tool_call --contains "shell"

설치된 버전의 특정 명령어에 대한 최신 플래그 목록은 revka --help 또는 revka <command> --help를 실행하세요.

명령어 그룹

명령어는 몇 가지 기능 그룹으로 나뉩니다. 각 항목은 해당 레퍼런스 페이지로 연결됩니다.

revka agent 대화형 채팅 및 단발성 쿼리, 세션 상태, 프로바이더/모델/온도 재정의, 주변 장치 연결.

revka gateway, daemon & service 게이트웨이, 풀 데몬 실행, 또는 Revka를 OS 서비스로 등록. 페어링 코드.

revka cron 반복, 일회성, 인터벌, 지연 에이전트 또는 셸 작업을 스케줄링.

revka channel & integrations 메시징 채널 추가, 제거, 목록 조회, 헬스 체크, 바인딩, 메시지 전송.

revka models, providers & auth 프로바이더 카탈로그 검사, 프로바이더 목록 조회, 구독 인증 프로파일 관리.

revka memory & estop 로컬 메모리 항목 검사 및 긴급 정지 상태 활성화 또는 재개.

revka skills, workflows & sop 스킬 설치, 감사, 테스트 및 내장 Operator 워크플로우 템플릿 동기화.

revka doctor, status & self-test 진단, 시스템 요약, 모델 카탈로그 탐색, 트레이스 쿼리, 자체 테스트.

revka hardware & peripheral USB 장치 검색 및 하드웨어 주변 장치 등록, 플래싱, 설정.

revka install, update, migrate, completions & ACP 사이드카 설치, 바이너리 업데이트, 런타임 마이그레이션, 셸 자동 완성, ACP 서버.

이 페이지는 모든 그룹에 공통으로 적용되는 세 가지를 다룹니다. --config-dir 플래그, revka config schema 내보내기, 그리고 환경 변수 레이어입니다. 최초 설정(revka onboard)은 별도 페이지에서 다루며, 플래그 레퍼런스는 아래에 요약되어 있고 온보딩 마법사에서 전체 내용을 확인할 수 있습니다.

오프라인 우선 설계

대부분의 서브명령어는 로컬 설정과 워크스페이스에서만 동작하며, 작업 자체에 네트워크가 필요한 경우가 아니라면 네트워크에 연결하지 않습니다.

• 데몬 불필요 — onboard, agent, config schema, cron CRUD, memory, estop, skills, workflows, completions, doctor, 그리고 하드웨어/주변 장치 명령어는 모두 독립적으로 실행됩니다.
• 데몬 필요 — 게이트웨이를 호출하는 작업, 예를 들어 revka pair token(HTTP로 페어링 코드 교환)과 revka status --format exit-code(구성된 게이트웨이에 GET /health 요청).
• 자동 완성은 부수 효과가 없습니다. revka completions <shell>은 stdout에만 출력하며, 설정을 로드하거나 로그를 남기지 않으므로 셸 초기화 스크립트에서 직접 source해도 안전합니다.
• 오프라인 CI 유효성 검사. revka self-test --quick은 네트워크 체크(게이트웨이 헬스, 메모리 왕복)를 건너뛰므로 에어갭 또는 CI 환경에 적합합니다. 테스트가 하나라도 실패하면 0이 아닌 종료 코드를 반환합니다.

전역 플래그: --config-dir

--config-dir는 모든 명령어에 대한 설정 디렉토리를 재정의합니다. 유일한 진정한 전역 플래그이며, 반드시 서브명령어 앞에 위치해야 합니다.

revka --config-dir /custom/path daemon

• --config-dir를 설정하면 프로세스의 REVKA_CONFIG_DIR 환경 변수도 함께 설정되므로, Revka가 생성하는 모든 자식 프로세스도 동일한 디렉토리를 참조합니다.
• 빈 문자열은 오류와 함께 거부됩니다.
• 호출 전에 REVKA_CONFIG_DIR를 내보내는 것과 동일합니다.

설정 디렉토리 결정 방식

--config-dir를 전달하지 않은 경우, Revka는 세 단계 우선순위 체계를 통해 로드할 config.toml을 결정합니다.

1. REVKA_WORKSPACE — 설정된 경우 이 워크스페이스 디렉토리가 절대 우선순위를 가지며, 설정 디렉토리는 이로부터 파생됩니다.
2. ~/.revka/active_workspace.toml — revka onboard가 작성하는 영속 마커 파일로, 선택된 워크스페이스를 가리킵니다. 이 파일 덕분에 실행 간에 워크스페이스 경로가 유지됩니다.
3. 기본값 — ~/.revka/config.toml.

REVKA_CONFIG_DIR(또는 이를 뒷받침하는 --config-dir 플래그)는 전체 설정 디렉토리를 재정의하며, 설정 파일이 로드되기 전에 적용됩니다.

주의

Homebrew 설치는 기본적으로 /opt/homebrew/var/revka/를 사용하는데, 이는 수동 설치 시 사용하는 ~/.revka/ 디렉토리와 다릅니다. revka onboard는 작성하는 설정이 서비스가 실행되는 경로와 다를 경우 경고를 표시합니다. 서비스로 실행하기 전에 워크스페이스를 복사하거나 링크하세요. 자세한 내용은 macOS 라이프사이클 페이지를 참조하세요.

config.toml의 전체 섹션과 키 목록은 설정 개요를 참조하세요.

revka onboard 플래그 레퍼런스

revka onboard는 처음 실행하는 명령어입니다. 터미널 환경과 전달한 플래그에 따라 대화형 마법사 또는 비대화형 빠른 설정 중 하나를 자동으로 선택합니다. 전체 사용 방법은 온보딩 마법사 페이지에 있으며, 플래그 목록은 다음과 같습니다.

플래그	설명
--force	확인 없이 기존 설정을 덮어씁니다(프로바이더 전용 업데이트 모드 대신 전체 마법사 실행).
--reinit	전체 설정 디렉토리를 타임스탬프 접미사로 백업한 후 처음부터 온보딩합니다. --channels-only와 함께 사용할 수 없습니다.
--channels-only	빠른 채널 복구 마법사만 실행합니다. --api-key, --provider, --model, --memory, --force, --quick과 함께 사용할 수 없습니다.
--api-key <KEY>	프로바이더 API 키. 빠른(스크립트 가능) 설정을 활성화합니다.
--provider <ID>	프로바이더 이름(예: openrouter, anthropic, openai). 빠른 설정을 활성화합니다.
--model <MODEL_ID>	모델 재정의. 빠른 설정을 활성화합니다.
--memory <kumiho|none>	빠른 설정의 메모리 백엔드 선택.
--quick	대화형 프롬프트를 건너뛰고 기본값으로 빠른 설정을 사용합니다.
--lang <en|ko>	마법사 UI 언어. REVKA_LANG과 $LANG을 재정의합니다.

revka onboard                                         # TTY에서 대화형 마법사
revka onboard --quick                                 # 빠른 설정 강제 실행
revka onboard --api-key "sk-..." --provider openrouter
revka onboard --channels-only                         # 채널 복구만 실행
revka onboard --reinit                                # 기존 설정 백업 후 새로 시작

REVKA_INTERACTIVE=1은 TTY 없이도 대화형 마법사를 강제 실행하며, REVKA_AUTOSTART_CHANNELS=1은 온보딩 완료 후 채널을 자동으로 시작합니다.

revka config schema — JSON 스키마 내보내기

revka config schema는 전체 config.toml 계약에 대한 기계 가독 **JSON Schema(draft 2020-12)**를 stdout으로 출력합니다. 스키마는 사용 가능한 모든 키, 타입, 기본값, 설명을 문서화하므로 설정 형식의 신뢰할 수 있는 레퍼런스입니다.

revka config schema                 # stdout에 출력
revka config schema > schema.json   # 도구 활용을 위해 저장

가장 일반적인 사용 사례는 에디터 유효성 검사입니다. 내보낸 파일을 에디터의 JSON 스키마 지원에 연결하면 config.toml 편집 시 자동 완성과 인라인 유효성 검사를 사용할 수 있습니다. 예를 들어 VS Code에서는 다음과 같이 설정합니다.

.vscode/settings.json

{
  "evenBetterToml.schema.associations": {
    ".*/config\\.toml$": "./schema.json"
  }
}

이 명령어는 읽기 전용 오프라인 명령어로, 설정을 로드하지 않고 데몬도 필요하지 않습니다.

환경 변수

환경 변수는 파일을 수정하지 않고 동등한 config.toml 필드를 덮어씁니다. 따라서 CI/CD 및 컨테이너에서 Revka를 구성하는 자연스러운 방법입니다. 환경 변수는 설정 파일이 로드된 후 apply_env_overrides 단계에서 적용됩니다.

.env 로딩 동작

env 재정의 단계가 실행되기 전에, Revka는 활성 워크스페이스(<workspace>/.env)의 .env 파일을 자동으로 로드합니다.

1. 설정 파일이 로드됩니다(config.toml은 위에서 설명한 방식으로 결정됩니다).
2. 워크스페이스 .env 파일이 있으면 한 줄씩 파싱됩니다. 빈 줄과 # 주석은 건너뛰며, 각 KEY=VALUE는 프로세스 환경에 설정됩니다. 단, 해당 키가 아직 설정되지 않은 경우에만 적용됩니다. 이미 환경에 존재하는 키는 .env 값보다 우선합니다.
3. KUMIHO_SERVICE_TOKEN에 대한 최종 폴백: .env 로딩 후에도 설정되지 않은 경우, Revka는 Kumiho CLI 인증 파일 ~/.kumiho/kumiho_authentication.json의 control_plane_token 필드에서 값을 읽습니다. 정상적인 온보딩 과정에서는 토큰이 워크스페이스 .env에 작성되므로 이 폴백보다 우선합니다.
4. apply_env_overrides가 실행되어 결과 환경을 로드된 설정 위에 레이어링합니다.

참고

기억해야 할 우선순위는 다음과 같습니다. 명시적 셸 환경 > 워크스페이스 .env > config.toml. REVKA_CONFIG_DIR는 특별합니다. 어떤 설정을 로드할지 결정하기 때문에 설정 파일이 로드되기 전에 읽힙니다.

프로바이더 키 우선순위

프로바이더 API 키는 여러 소스에서 결정됩니다. 순서는 다음과 같습니다.

1. config.toml의 명시적 api_key.
2. 프로바이더별 환경 변수(예: OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY, XAI_API_KEY, MOONSHOT_API_KEY, GLM_API_KEY, ZAI_API_KEY, 그리고 Revka가 인식하는 기타 *_API_KEY 변수).
3. 일반 REVKA_API_KEY(또는 레거시 API_KEY).

백엔드별 프로바이더 환경 변수와 OAuth/구독 프로바이더에 대해서는 revka models, providers & auth와 프로바이더 카탈로그를 참조하세요.

참고

레거시 프로바이더 변수 PROVIDER는 설정의 기본값이 여전히 openrouter(기본값)인 경우에만 설정 기본값을 재정의합니다. REVKA_PROVIDER는 설정되어 있으면 항상 우선합니다.

핵심 레퍼런스

변수	재정의 대상	설명
REVKA_CONFIG_DIR	--config-dir 플래그	설정 및 워크스페이스 디렉토리. 설정 로드 전에 읽힙니다.
REVKA_WORKSPACE	workspace_dir	활성 워크스페이스 디렉토리(설정 디렉토리가 여기서 파생됩니다).
REVKA_API_KEY / API_KEY	api_key	일반 프로바이더 API 키.
REVKA_PROVIDER / PROVIDER (레거시)	default_provider	프로바이더 ID. PROVIDER는 설정이 openrouter인 경우에만 우선합니다.
REVKA_MODEL / MODEL	default_model	모델 ID.
REVKA_MODEL_PROVIDER / MODEL_PROVIDER	default_provider	Codex 앱 서버 스타일 별칭.
REVKA_TEMPERATURE	default_temperature	부동소수점 0.0–2.0.
REVKA_GATEWAY_PORT / PORT	gateway.port	게이트웨이 수신 포트.
REVKA_GATEWAY_HOST / HOST	gateway.host	게이트웨이 바인드 호스트.
REVKA_REQUIRE_PAIRING	gateway.require_pairing	불리언.
REVKA_ALLOW_PUBLIC_BIND	gateway.allow_public_bind	불리언.
REVKA_WEB_ROOT	gateway.web_root	대시보드 에셋의 파일 시스템 경로.
REVKA_LANG	language	마법사/UI 언어(en, ko).
REVKA_LOCALE	locale	도구 설명 로케일(더 넓은 범위, 예: zh-CN, ja-JP).
REVKA_EXTRA_HEADERS	extra_headers	형식: Name:Value,Name2:Value2.
REVKA_PROVIDER_TIMEOUT_SECS	프로바이더 HTTP 타임아웃	정수(초 단위).
RUST_LOG	트레이싱 로그 필터	예: debug, info, revka=trace.

온보딩 동작

변수	효과
REVKA_INTERACTIVE	1로 설정하면 TTY 없이도 대화형 온보딩 마법사를 강제 실행합니다.
REVKA_AUTOSTART_CHANNELS	1로 설정하면 온보딩 완료 후 즉시 채널을 시작합니다.

스킬

변수	재정의 대상	설명
REVKA_OPEN_SKILLS_ENABLED	skills.open_skills_enabled	1/0/true/false/yes/no/on/off.
REVKA_OPEN_SKILLS_DIR	skills.open_skills_dir	스킬 디렉토리 경로.
REVKA_SKILLS_ALLOW_SCRIPTS	skills.allow_scripts	스킬 내 스크립트 파일 허용.
REVKA_SKILLS_PROMPT_MODE	skills.prompt_injection_mode	full 또는 compact.

추론 및 웹 검색

변수	재정의 대상	설명
REVKA_REASONING_ENABLED / REASONING_ENABLED	reasoning.enabled	확장 사고 토글.
REVKA_REASONING_EFFORT / REVKA_CODEX_REASONING_EFFORT	추론 노력	프로바이더별 설정.
REVKA_WEB_SEARCH_ENABLED / WEB_SEARCH_ENABLED	웹 검색 활성화	불리언.
REVKA_WEB_SEARCH_PROVIDER / WEB_SEARCH_PROVIDER	웹 검색 프로바이더	문자열.
REVKA_BRAVE_API_KEY / BRAVE_API_KEY	Brave Search API 키	문자열.
REVKA_SEARXNG_INSTANCE_URL / SEARXNG_INSTANCE_URL	SearXNG 인스턴스	URL.
REVKA_WEB_SEARCH_MAX_RESULTS / WEB_SEARCH_MAX_RESULTS	최대 결과 수	정수.
REVKA_WEB_SEARCH_TIMEOUT_SECS / WEB_SEARCH_TIMEOUT_SECS	검색 타임아웃	정수.

스토리지 및 프록시

변수	재정의 대상	설명
REVKA_STORAGE_PROVIDER	storage.provider	문자열.
REVKA_STORAGE_DB_URL	storage.db_url	연결 URL.
REVKA_STORAGE_CONNECT_TIMEOUT_SECS	스토리지 연결 타임아웃	정수.
REVKA_PROXY_ENABLED	proxy.enabled	불리언.
REVKA_HTTP_PROXY / HTTP_PROXY	HTTP 프록시 URL	URL.
REVKA_HTTPS_PROXY / HTTPS_PROXY	HTTPS 프록시 URL	URL.
REVKA_ALL_PROXY / ALL_PROXY	전체 트래픽 프록시(SOCKS5)	URL.
REVKA_NO_PROXY / NO_PROXY	프록시 제외 목록	쉼표로 구분.
REVKA_PROXY_SCOPE	proxy.scope	environment / revka / services.
REVKA_PROXY_SERVICES	프록시 서비스	쉼표로 구분된 서비스 키.

보안 및 채널 시크릿

변수	재정의 대상	설명
REVKA_AUDIT_SIGNING_KEY	감사 서명 키	32바이트 hex(64자).
REVKA_WHATSAPP_APP_SECRET	WhatsApp 채널 앱 시크릿	문자열.
REVKA_NEXTCLOUD_TALK_WEBHOOK_SECRET	Nextcloud Talk 웹훅 시크릿	문자열.

Kumiho 그래프 메모리

변수	설명
KUMIHO_SERVICE_TOKEN	Kumiho 인증 토큰. 워크스페이스 .env에서 로드되거나, 설정되지 않은 경우 ~/.kumiho/kumiho_authentication.json에서 자동으로 주입됩니다.
KUMIHO_LOCAL_SERVER_ENDPOINT	Kumiho CE gRPC 엔드포인트. CE(Community Edition) 모드가 활성화되면 자동으로 설정됩니다.
KUMIHO_UPSTASH_REDIS_URL	Kumiho CE용 Redis URL. CE 모드가 활성화되면 자동으로 설정됩니다.

전체 메모리 설정에 대해서는 Kumiho 그래프 메모리와 Kumiho 설정을 참조하세요.

CE 모드 자동 주입(KUMIHO_*)

[kumiho].mode = "local_ce"(셀프호스팅 Community Edition)로 설정된 경우, Revka는 api_url을 CE 기본값 http://127.0.0.1:9190으로 지정하고, Kumiho MCP 클라이언트를 위한 CE 엔드포인트 환경을 자동으로 주입하므로 직접 설정할 필요가 없습니다.

• KUMIHO_LOCAL_SERVER_ENDPOINT — CE 서버 엔드포인트로 설정됩니다.
• KUMIHO_UPSTASH_REDIS_URL(또는 UPSTASH_REDIS_URL) — CE용 Redis URL로, 기본값은 redis://127.0.0.1:6379입니다.

CE 모드는 토큰 불필요, 루프백 전용, 단일 사용자 방식입니다. MCP 클라이언트의 토큰 우선순위는 KUMIHO_SERVICE_TOKEN이 KUMIHO_AUTH_TOKEN보다 우선합니다. 서비스 토큰(Revka 온보딩이 작성)을 먼저 읽고, 없으면 KUMIHO_AUTH_TOKEN으로 폴백합니다. revka doctor는 CE 헬스 엔드포인트(/api/_live, /api/_health)를 탐색하여 Neo4j, 이벤트 스트림, 임베딩이 접근 가능한지 확인합니다. CE 백엔드 시작 및 유효성 검사에 대해서는 Kumiho 설정을 참조하세요.

예제

CI / scriptable

# Non-interactive bootstrap, config written under a custom directory
REVKA_CONFIG_DIR=/srv/revka \
REVKA_API_KEY="sk-..." \
REVKA_PROVIDER="openrouter" \
  revka onboard --quick

# Offline validation suitable for CI
revka self-test --quick

Container / daemon

REVKA_GATEWAY_HOST=0.0.0.0 \
REVKA_GATEWAY_PORT=8080 \
REVKA_ALLOW_PUBLIC_BIND=true \
  revka daemon

# Lightweight health probe (Docker HEALTHCHECK)
revka status --format exit-code

Debugging

RUST_LOG=revka=debug revka daemon
revka --config-dir /srv/revka doctor

다음 단계

온보딩 마법사 revka onboard의 전체 사용 방법, 모드, 설정 보호.

설정 개요 config.toml의 모든 섹션, 키, 기본값, 환경 변수 재정의.

revka doctor, status & self-test 진단, 시스템 요약, 트레이스 검사.

revka gateway, daemon & service 런타임 실행 및 OS 서비스로 등록.