CoCo CLI 참조

CoCo CLI 참조

CoCo CLI의 명령줄 참조입니다. CoCo CLI는 두 가지 모드로 작동합니다.

  • 대화형 모드(기본값): 대화형 프롬프트에서 프롬프트와 슬래시 명령을 입력하는 지속 세션을 시작. CoCo는 여러 교환에 걸쳐 대화 컨텍스트를 유지합니다.
  • 배치 모드: 명령줄이나 파일에서 단일 프롬프트를 전달. CoCo가 처리하고 대화형 세션을 시작하지 않고 종료합니다.

아래 섹션은 시작 명령, 두 모드가 공유하는 CLI 옵션, 세션에 들어가기 전에 실행하는 하위 명령, 세션 안에서 사용하는 대화형 모드 명령, 배치 모드 사용법을 다룹니다.

출처: CoCo CLI reference

본문

CoCo 시작

명령 설명
cortex 현재 디렉터리에서 시작
cortex -c production 특정 연결로 시작
cortex -w /path/to/project 특정 디렉터리에서 시작
cortex -w /new/project -c myconn 작업 디렉터리와 연결 결합
cortex --continue 마지막 세션 계속
cortex --resume <session_id> 특정 세션 재개
cortex --cloud 관리형 컨테이너에서 도구 실행

CLI 옵션

옵션 설명
-c, --connection <name> 특정 Snowflake 연결 사용
-w, --workdir <path> 파일 작업의 작업 디렉터리 설정
-m, --model <model_name> 사용할 AI 모델 지정
--mode <standard|code> 에이전트 도구 모드; code는 간결한 코딩 도구 세트 사용(Code mode 참고)
--plan 플랜 모드: 모든 작업 전 승인 요구
--auto-accept-plans 플랜 모드 요청과 확인을 프롬프트 없이 자동 수락
--bypass, --dangerously-allow-all-tool-calls 모든 도구 호출을 자동 승인하는 바이패스 모드 활성화
--allowed-tools <tools> 권한 묻지 않고 실행되는 도구(예: "Bash(git *)")
--disallowed-tools <tools> 모델 컨텍스트에서 제거되어 사용할 수 없는 도구
--continue 가장 최근 대화 재개
-r, --resume [<session_id>] ID로 특정 세션 재개, 또는 가장 최근 세션이면 last
-p, --print "<prompt>" 지정한 프롬프트 전달, 응답 출력 후 종료
--output-format stream-json JSON 출력(스크립팅용)
--effort <level> 추론 노력 수준: minimal, low, medium, high 또는 max
--max-turns <n> 대화 라운드당 최대 에이전트 턴 수
--private 이 세션을 기록에 저장하지 않음(대화 영속성과 서버 측 로깅 비활성화)
--cloud [<workspace>] Snowflake 관리형 컨테이너에서 도구 실행
--no-workspace --cloud와 함께, 임시 workspace 사용
--github <secret> --cloud와 함께, 인증된 GitHub 접근 허용
-V, --version 설치된 버전 표시
--help CLI 도움말 표시

연결은 ~/.snowflake/connections.toml에 정의되어야 합니다. 연결 설정은 CoCo CLI를 참고하세요. 세션 ID는 시작 시와 종료 시 표시되며 ~/.snowflake/cortex/conversations/에 저장됩니다.

--bypass와 --dangerously-allow-all-tool-calls는 같은 옵션의 별칭입니다. -r, --resume의 값을 생략하면 세션 이름을 지정하는 대신 재개 선택기를 엽니다. --allowed-tools로 특정 도구를 선승인하고(예: "Bash(git *)"로 모든 git 명령 승인), --disallowed-tools로 특정 도구를 모델에 아예 제공하지 않도록 방지합니다.

경고: 바이패스 모드는 모든 도구 호출을 먼저 묻지 않고 승인합니다. 에이전트가 취할 수 있는 모든 조치를 신뢰할 때만 사용하세요.

--cloud, --no-workspace, --github에 대한 자세한 내용은 CoCo CLI cloud sandbox를 참고하세요. --cloud는 선택적으로 마운트할 workspace 이름(DATABASE.SCHEMA.NAME)을 받고, --github는 GitHub 개인 접근 토큰을 담은 Snowflake 시크릿(DATABASE.SCHEMA.SECRET)의 이름을 받으며 --cloud를 암시합니다.

예시

작업 디렉터리로 시작:

cortex -w /path/to/project

특정 연결로 마지막 세션 재개:

cortex --continue -c production

일회성 프롬프트(JSON 출력):

cortex -p "List all Python files" --output-format stream-json

명령

이 하위 명령들은 대화형 세션을 시작하기 전이나 대신 셸에서 실행됩니다. 대화형 세션 안에 입력하는 슬래시 명령(예: /mcp)과는 구별됩니다.

update

CoCo CLI를 최신 버전으로 업데이트.

명령 설명
cortex update 최신 버전으로 업데이트
cortex --version 업데이트 후 확인

exec

exec을 사용해 CoCo CLI를 비대화형으로 실행하세요. CI/CD(지속적 통합 및 지속적 배포) 파이프라인에 유용합니다. 플랜 모드는 항상 비활성화되고 대화형 프롬프트는 자동으로 거부됩니다.

명령 설명
cortex exec "<prompt>" 프롬프트 실행 후 종료
cortex exec --file <file> 파일에서 프롬프트 읽기
cortex exec --file - 표준 입력에서 프롬프트 읽기

mcp

Model Context Protocol(MCP) 서버 연결을 명령줄에서 관리.

명령 설명
cortex mcp list 구성된 서버 나열
cortex mcp add <name> <command_or_url> [args...] 새 서버 추가
cortex mcp get <name> 구성된 서버 세부 정보 표시
cortex mcp remove <name> 서버 제거
cortex mcp reconnect [name] 서버 하나 재연결, 또는 이름을 제공하지 않으면 모든 서버 재연결
cortex mcp start 구성된 서버 시작

add 하위 명령은 다음 옵션을 받습니다.

옵션 설명
-t, --transport <type> 사용할 전송: stdio, sse 또는 http. 기본값: stdio.
-e, --env <KEY=value> 환경 변수 설정. 여러 변수는 옵션 반복.
-H, --header "<name>: <value>" HTTP 헤더 설정. 여러 헤더는 옵션 반복.
--timeout <milliseconds> 연결 타임아웃.

자세한 내용은 MCP(Model Context Protocol)를 참고하세요.

대화형 모드

대화형 모드는 -p나 exec 없이 cortex를 실행할 때 기본값입니다. CoCo는 > 프롬프트에서 자연어 프롬프트와 슬래시 명령을 입력하는 지속 세션을 엽니다. 에이전트가 요청을 처리하고(여러 도구를 사용할 수 있음) 다음 입력을 위해 프롬프트로 돌아갑니다.

이 섹션에 설명된 키보드 단축키와 슬래시 명령은 대화형 모드에서만 작동합니다. 배치 모드나 cortex exec --file에 전달한 파일 안에서는 적용되지 않습니다.

키보드 단축키

이 단축키는 대화형 프롬프트에서 그리고 에이전트가 작업하는 동안 활성입니다.

단축키 동작
Ctrl+C 현재 작업 취소
Ctrl+C Ctrl+C CoCo CLI 종료
Ctrl+L 터미널 화면 지우기(대화 유지)
위/아래 화살표 명령 기록 탐색
Tab 명령 자동 완성

슬래시 명령

슬래시 명령은 대화형 프롬프트에 입력하는 특수 명령입니다. /로 시작하며 AI 모델에 프롬프트로 보내지 않고 CoCo의 동작을 제어합니다. 슬래시 명령은 대화형 모드에서만 작동합니다.

세션 관리
명령 설명
/help 대화형 도움말 표시
/clear, /cls 화면 지우기
/new 새 세션 시작
/rename <title> 현재 세션 이름 변경
/quit, /exit CoCo CLI 종료
/resume, /r, /sessions 세션 나열 및 재개
/rewind 대화에서 n단계 뒤로 가거나 대화형으로 선택
/fork 현재 세션을 새 세션으로 포크
모델 및 모드
명령 설명
/model AI 모델 표시/선택
/plan 플랜 모드 활성화
/plan-off 플랜 모드 비활성화
/bypass 바이패스 모드 활성화(도구 호출 포함 모두 자동 승인)
/bypass-off 바이패스 모드 비활성화
/status 현재 구성 표시
Snowflake 및 데이터
명령 설명
/sql <query> SQL 쿼리 실행
/sql <query> --limit <n> 표시 행 제한
/table [<file>], /csv 테이블 뷰어 열기
/connections, /conn Snowflake 연결 관리
개발 도구
명령 설명
/sh, ! <command> 셸 명령 실행
/diff, /changes, /review git 변경 사항 검토
/worktree git 워크트리 관리
/fdbt 빠른 dbt 프로젝트 분석
/lineage dbt 계보 시각화
구성
명령 설명
/settings 설정 보기/수정
/theme 색상 테마 선택
/sandbox 샌드박스 설정 관리
/workspace 마운트된 workspace 탐색 및 전환(클라우드 전용)
/add-dir <path> 작업 디렉터리 추가
확장성
명령 설명
/skill, /skills 스킬 관리
/skill new, /skill create 새 스킬 생성
/mcp MCP 서버 상태
/hooks 훅 구성 보기
/commands, /cmds 사용자 정의 명령 관리
/agents 하위 에이전트 보기
유틸리티
명령 설명
/bashes, /shells, /tasks 백그라운드 셸 보기 및 관리
/feedback 세션 피드백 제공, 로컬에 .tgz 파일로 저장
/update CoCo 업데이트

세션 저장소

항목 설명
~/.snowflake/cortex/conversations/ 세션 파일
~/.snowflake/cortex/settings.json 일반 설정
~/.snowflake/cortex/permissions.json 권한 선호

구성 세부 정보는 CoCo CLI Settings를 참고하세요.

명령 세부 정보

/sql: SQL 쿼리 실행

기본 쿼리:

/sql SELECT * FROM users

행 제한 포함:

/sql SELECT * FROM large_table --limit 1000

여러 줄 쿼리(Ctrl+J로 줄바꿈):

/sql SELECT
  customer_id,
  SUM(amount) as total
FROM orders
GROUP BY customer_id

결과는 테이블 뷰어(Ctrl+T)에서 자동으로 열립니다.

/worktree: Git 워크트리

Git 워크트리를 사용하면 앞뒤로 전환하지 않고 여러 브랜치에서 동시에 작업할 수 있습니다. CoCo는 기본적으로 프로젝트 디렉터리 아래(.worktrees/ 하위 디렉터리 또는 git 구성에 따라 기본 checkout 옆)에 워크트리를 만듭니다.

명령 설명
/worktree create feature-branch 새 워크트리 생성
/worktree list 모든 워크트리 나열
/worktree switch feature-branch 워크트리로 전환
/worktree delete feature-branch 워크트리 삭제

/sandbox: 샌드박스 제어

CoCo의 샌드박스는 셸 명령을 제한된 환경에 격리해 작업 디렉터리 밖의 파일을 수정하거나 민감한 시스템 리소스에 접근하지 못하게 합니다. 이는 CoCo 특화 보안 기능입니다. 컨테이너 샌드박스는 Docker를 사용하고, 런타임 샌드박스는 OS 수준 제한(macOS 샌드박스 또는 Linux 네임스페이스)을 사용합니다.

명령 설명
/sandbox 대화형 선택기
/sandbox on 컨테이너 샌드박스 활성화
/sandbox off 컨테이너 샌드박스 비활성화
/sandbox status 샌드박스 상태 표시
/sandbox runtime on OS 샌드박스 활성화
/sandbox runtime off OS 샌드박스 비활성화
/sandbox mode auto 샌드박스 명령 자동 허용
/sandbox mode regular 모든 명령에 프롬프트

머신이 아닌 Snowflake 관리형 컨테이너에서 도구를 실행하려면 --cloud로 CoCo CLI를 시작하세요. CoCo CLI cloud sandbox를 참고하세요.

/mcp: MCP 서버

/mcp는 하위 명령을 받지 않습니다. 구성된 모든 서버를 나열하고 세션 안에서 서버를 시작, 중지, 재연결, 인증, 편집, 제거할 수 있는 대화형 뷰어를 엽니다. 비대화형 관리를 위해서는 위의 mcp에서 설명한 cortex mcp 하위 명령을 사용하세요.

배치 모드

배치 모드는 대화형 세션을 시작하지 않고 단일 프롬프트를 실행합니다. CoCo가 요청을 처리하고 결과를 출력한 뒤 종료합니다. 스크립팅, CI/CD 파이프라인, 왕복 대화가 필요 없는 일회성 질문에 유용합니다.

인라인 프롬프트에는 -p를, 파일 또는 stdin의 프롬프트에는 cortex exec를 사용하세요. 대화형 프롬프트가 없으므로 슬래시 명령은 배치 모드에서 작동하지 않습니다.

명령 설명
cortex -p "<prompt>" 단일 프롬프트 실행 후 종료
cortex exec --file request.txt 파일에서 프롬프트 읽기
cortex --output-format stream-json -p "<prompt>" JSON 출력
cortex -c prod --workdir /app -p "..." 컨텍스트 제어

종료 코드

CoCo CLI는 성공 시 0, 실패 시 0이 아닌 값을 반환합니다. 특정 0이 아닌 코드를 오류 범주에 안정적으로 매핑한다는 보장은 없으므로 스크립트는 0인지 0이 아닌지만 테스트해야 합니다. 오류 세부 정보는 표준 오류에 기록됩니다.

구성 및 설정

CoCo CLI 업데이트

CoCo CLI는 새 버전이 나오면 스스로 업데이트합니다. cortex update를 실행해 최신 버전으로 수동 업데이트할 수도 있습니다. cortex update <version>을 실행하면 지정한 버전을 설치합니다.

자동 업데이트를 비활성화하려면 ~/.snowflake/cortex/settings.json을 편집하고 "autoUpdate": false를 추가하세요.

연결 수동 추가

연결을 정의하기 위해 ~/.snowflake/connections.toml 파일을 수동으로 만들거나 편집하려면 다음 단계를 따르세요.

  • ~/.snowflake/connections.toml 파일이 없으면 만듭니다. 
    mkdir -p ~/.snowflake
touch ~/.snowflake/connections.toml
  • chmod 명령으로 당신만 읽고 쓸 수 있도록 권한을 설정합니다. 
    chmod 600 ~/.snowflake/connections.toml
  • 텍스트 편집기(여기서는 nano)로 파일을 엽니다. 
    nano ~/.snowflake/connections.toml
  • 연결을 정의하는 다음 줄을 추가합니다. myaccount 자리에 연결 이름을 입력하고 자리 표시자 값을 Snowflake 계정 세부 정보로 바꾸세요. 브라우저 기반 SSO(외부 브라우저 인증) 또는 PAT(프로그래밍 방식 접근 토큰)를 사용하세요. PAT는 Snowsight에서 얻을 수 있습니다(인증용 프로그램형 액세스 토큰 사용 참고). 선택한 인증 방법에 따라 authenticator 값 또는 password 값만 포함하세요. 
    [myaccount]
account = "<ACCOUNT>"
user = "<USERNAME>"
authenticator = "externalbrowser"  # For browser-based SSO; omit for PAT
password = "<PAT>"                 # For PAT authentication; omit for SSO
warehouse = "<WAREHOUSE>"
role = "<ROLE>"
database = "<DATABASE>"
schema = "<SCHEMA>"
  • 저장하고 파일을 닫습니다.

셸 완성 설정

셸이 CoCo CLI 명령과 옵션을 자동 완성하게 하려면 다음 방법 중 하나를 사용하세요.

팁: 어떤 셸을 사용 중인지 확실하지 않으면 터미널에서 echo $(basename $SHELL)을 실행하세요. 출력된 이름이 계정의 기본 셸이며, 수동으로 다른 셸을 시작했다면 정확하지 않을 수 있습니다.

가장 빠른 방법은 CoCo CLI가 완성 스크립트를 설치하게 하는 것입니다. 다음 명령을 실행해 현재 셸에 설치하거나, --all을 추가해 지원되는 모든 셸에 설치하세요.

cortex completion install

특정 셸에 설치하려면 --shell을 전달합니다.

cortex completion install --shell zsh

또는 스크립트를 직접 생성해 셸이 기대하는 위치에 작성하세요.

셸 명령
bash cortex completion generate --shell bash > ~/.bash_completion.d/cortex
zsh cortex completion generate --shell zsh > ~/.zsh/completions/_cortex
fish cortex completion generate --shell fish > ~/.config/fish/completions/cortex.fish

완성 스크립트를 설치하거나 생성한 후 exec $SHELL로 셸을 다시 시작하세요.

디렉터리 구조

CoCo CLI는 홈 디렉터리 아래에 구성과 상태를 다음과 같이 저장합니다. 필요할 때 파일과 디렉터리를 만들므로 새 설치에는 모두 존재하지 않을 수 있습니다.

~/.snowflake/cortex/
   ├── settings.json          # Main configuration (includes hook configuration)
   ├── mcp.json               # MCP server configs
   ├── hooks.json             # Global hook configuration
   ├── conversations/         # Session history
   ├── skills/                # Global skills
   ├── commands/              # Custom commands
   ├── profiles/              # Team profiles
   └── cache/                 # Temporary cache

문제 해결

다음은 설치 및 설정 중 발생할 수 있는 일반적인 오류 메시지입니다.

명령을 찾을 수 없음

설치 디렉터리 ~/.local/bin이 PATH 환경 변수에 포함되어 있는지 확인하세요. 예를 들어 bash를 사용한다면 다음 명령을 실행합니다.

export PATH="~/.local/bin:$PATH"
echo 'export PATH="~/.local/bin:$PATH"' >> ~/.bashrc

권한 거부됨

cortex 실행 파일에 실행 권한이 있는지 확인하세요. 다음 명령을 실행합니다.

chmod +x ~/.local/bin/cortex

연결 오류

연결 파일 ~/.snowflake/connections.toml이 존재하고 유효한 연결 정보가 있는지 확인하세요.

cat ~/.snowflake/connections.toml

-c 옵션으로 연결을 명시적으로 지정해 cortex 명령을 호출해 보세요. 예를 들어:

cortex -c myaccount

더 알아보기