Cortex Code CLI 설정

Cortex Code CLI 설정은 도구 권한, 연결 및 세션 동작을 제어합니다. 관리형 정책(조직에서 제공하는 경우), 구성 파일, 환경 변수, 명령줄 인자를 사용하여 설정을 구성할 수 있습니다.

구성 파일

다음 구성 파일은 Cortex Code CLI에서 사용됩니다.

파일

목적

<admin-managed path>/managed-settings.json

조직 관리 정책 파일(선택 사항). OS별 위치는 관리형 설정(조직 정책) 섹션을 참조하세요.

~/.snowflake/cortex/settings.json

주요 Cortex Code CLI 설정 파일.

~/.snowflake/cortex/permissions.json

권한 기본 설정.

~/.snowflake/cortex/mcp.json

MCP 서버 구성(모델 컨텍스트 프로토콜(MCP) 참조).

~/.snowflake/config.toml

Snowflake 연결(Cortex Code CLI 참조). Snowflake CLI와 공유됩니다.

기본 구성 디렉터리의 전체 레이아웃은 다음과 같습니다.

~/.snowflake/cortex/        # Main Cortex Code CLI config directory
├── settings.json          # Main settings
├── mcp.json               # MCP server configs
├── permissions.json       # Saved permissions
├── hooks.json             # Global hooks
├── history                # Command history
├── conversations/         # Session files
├── cache/                 # Temporary cache
│   ├── table_cache.json   # SQL result metadata
│   └── sql_result_cache/  # Parquet files
├── logs/                  # Log files
├── memory/                # Persistent memory
├── agents/                # Custom agents
├── skills/                # Global skills
├── commands/              # Custom commands
├── hooks/                 # Hook scripts
└── remote_cache/          # Cloned repos
Copy

설정 우선 순위

설정은 다음과 같은 우선 순위(가장 높은 순서에서 가장 낮은 순서)로 적용됩니다.

  1. 관리형 설정(시스템 관리 정책 파일(있는 경우)). 관리형 설정(조직 정책) 섹션을 참조하십시오.

  2. 세션 내 명령(/plan 등)

  3. 명령줄 인자

  4. 환경 변수

  5. 구성 파일(~/.snowflake/cortex/)

  6. Cortex Code CLI에 포함된 기본값

settings.json

~/.snowflake/cortex/settings.json

Cortex Code CLI의 기본 설정 파일.

콘텐츠 예제:

{
   "compactMode": true,
   "autoUpdate": true,
   "theme": "dark"
}
Copy

다음 설정을 사용할 수 있습니다.

  • compactMode: 압축 출력 형식을 활성화합니다.

  • autoUpdate: 자동 업데이트를 활성화합니다.

  • theme: CLI 테마(light 또는``dark``)를 설정합니다.

permissions.json

~/.snowflake/cortex/permissions.json

도구 액세스 권한을 제어합니다.

콘텐츠 예제:

{
  "onlyAllow": ["read_file", "execute_sql"],
  "defaultMode": "ask",
  "dangerouslyAllowAll": false
}
Copy

다음 설정을 사용할 수 있습니다.

  • onlyAllow: 허용되는 도구 패턴을 나열합니다.

  • deny 기본 권한 모드(defaultMode, ask, allow)입니다.

  • dangerouslyAllowAll: 프롬프트 없이 모든 도구를 허용합니다(안전하지 않음).

관리형 설정(조직 정책)

관리형 설정은 IT 관리자가 Cortex Code CLI에 대한 조직 전체의 정책을 적용할 수 있도록 허용합니다. 예를 들어, 관리자는 사용할 수 있는 도구 또는 계정을 제한하고, 최소 CLI 버전을 적용하며, 우회 기능을 비활성화할 수 있습니다.

이러한 설정은 일반적으로 엔터프라이즈 구성 관리 도구(예: MDM 또는 SCCM)를 통해 배포됩니다. 사용자는 일반적으로 관리자/루트 권한이 없으면 관리형 설정을 수정할 수 없습니다.

파일 위치

관리형 설정 파일은 시스템 수준 경로에 저장됩니다.

플랫폼

경로

macOS

/Library/Application Support/Cortex/managed-settings.json

Linux 및 WSL

/etc/cortex/managed-settings.json

구성 스키마

관리형 설정 파일은 다음과 같은 구조의 JSON을 사용합니다.

{
  "version": "1.0",
  "permissions": { },
  "settings": { },
  "required": { },
  "defaults": { },
  "ui": { }
}
Copy

권한

permissions 섹션은 사용자가 액세스할 수 있는 항목을 제한할 수 있습니다. 예를 들어 도구 패턴과 계정 패턴을 허용하거나 거부할 수 있습니다.

{
  "permissions": {
    "onlyAllow": ["pattern1", "pattern2"],
    "deny": ["pattern3"],
    "defaultMode": "allow",
    "dangerouslyAllowAll": false
  }
}
Copy

필드

타입

기본값

설명

onlyAllow

string[]

—

패턴의 허용 목록입니다. 설정된 경우 일치하는 항목만 허용됩니다.

deny

string[]

—

패턴의 거부 목록입니다. 거부가 허용보다 우선합니다.

defaultMode

"allow" 또는 "deny"

"deny"

일치하는 규칙이 없을 때의 동작입니다.

dangerouslyAllowAll

boolean

false

우회 모드의 허용 여부를 제어합니다.

설정

settings 섹션은 런타임 동작을 적용합니다.

{
  "settings": {
    "forceNoHistoryMode": true,
    "forceSandboxEnabled": true,
    "forceSandboxMode": "regular"
  }
}
Copy

필드

타입

기본값

설명

forceNoHistoryMode

boolean

false

대화 기록 지속성을 강제로 적용하지 않습니다.

forceSandboxEnabled

boolean

false

샌드박스가 항상 활성화되도록 합니다.

forceSandboxMode

"regular" 또는 "autoAllow"

—

특정 샌드박스 모드를 강제 적용합니다.

필수

required 섹션은 최소 버전을 적용할 수 있습니다.

{
  "required": {
    "minimumVersion": "0.25.0"
  }
}
Copy

필드

타입

설명

minimumVersion

string

최소 CLI 버전입니다. 이전 버전에서는 오류가 표시되고 종료됩니다.

기본값

defaults 섹션은 기본값을 제공합니다. 사용자는 정책에서 허용하는 경우에만 이러한 기본값을 재정의할 수 있습니다.

{
  "defaults": {
    "connectionName": "prod",
    "profileName": "corporate",
    "theme": "dark"
  }
}
Copy

필드

타입

설명

connectionName

string

기본 Snowflake 연결 이름입니다.

profileName

string

로드할 기본 프로필입니다.

theme

string

기본값 UI 테마(예: dark 또는``light``)입니다.

UI

ui 섹션은 사용자 인터페이스 표시를 제어합니다.

{
  "ui": {
    "showManagedBanner": true,
    "bannerText": "[Secure] Managed by Corporate IT",
    "hideDangerousOptions": true
  }
}
Copy

필드

타입

기본값

설명

showManagedBanner

boolean

false

관리 상태를 나타내는 배너를 표시합니다.

bannerText

string

—

관리형 배너의 사용자 지정 텍스트입니다.

hideDangerousOptions

boolean

false

도움말 및 UI에서 위험한 옵션을 숨깁니다.

예

기본 회사 설정

기본 기능을 허용하지만 우회 모드를 비활성화하고 관리형 배너를 표시합니다.

{
  "version": "1.0",
  "permissions": {
    "dangerouslyAllowAll": false,
    "defaultMode": "allow"
  },
  "settings": {},
  "required": {
    "minimumVersion": "0.25.0"
  },
  "ui": {
    "showManagedBanner": true,
    "bannerText": "Managed by IT"
  }
}
Copy
특정 Snowflake 계정으로 제한

프로덕션 및 스테이징 계정에 대한 연결만 허용합니다.

{
  "version": "1.0",
  "permissions": {
    "dangerouslyAllowAll": false,
    "onlyAllow": [
      "account(mycompany-prod)",
      "account(mycompany-staging)"
    ],
    "defaultMode": "allow"
  }
}
Copy

환경 변수

Cortex Code CLI는 다음 구성 환경 변수를 인식합니다.

변수

설명

SNOWFLAKE_HOME

기본 ~/.snowflake 디렉터리를 재정의합니다.

CORTEX_AGENT_MODEL

모델 선택을 재정의합니다.

CORTEX_ENABLE_MEMORY

메모리 도구를 활성화합니다(true 또는 ``1``로 설정).

COCO_DANGEROUS_MODE_REQUIRE_SQL_WRITE_PERMISSION

우회 모드에서 SQL 쓰기 작업에 대한 확인이 필요합니다.

참고

추가적인 권한 관련 환경 변수는 :doc:`보안 </user-guide/cortex-code/security>`을 참조하세요.

명령줄 재정의

Cortex Code CLI 설정은 다음을 포함한 명령줄 인자를 통해 재정의할 수 있습니다.

예

설명

cortex -c production

연결을 지정합니다.

cortex --workdir /path

작업 디렉터리를 설정합니다.

cortex --continue

마지막 세션을 계속합니다.

cortex --resume <세션_ID>

특정 세션을 재개합니다.

cortex --plan

계획 모드를 활성화합니다.

cortex --dangerously-allow-all-tool-calls

권한 프롬프트를 비활성화합니다(안전하지 않음).

세션 저장소

대화 및 설정은 다음 위치에 저장됩니다.

location

설명

~/.snowflake/cortex/conversations/

세션 파일입니다.

~/.snowflake/cortex/permissions.json

권한 기본 설정.

~/.snowflake/cortex/mcp.json

MCP 구성입니다.