Configurações da Cortex Code CLI

As configurações da Cortex Code CLI controlam permissões de ferramentas, conexões e comportamento de sessão. É possível definir as configurações usando uma política gerenciada (se fornecida por sua organização), arquivos de configuração, variáveis de ambiente e argumentos de linha de comando.

Arquivos de configuração

Os seguintes arquivos de configuração são usados pela Cortex Code CLI:

Arquivo

Objetivo

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

Arquivo de política gerenciada pela organização (opcional). Para locais específicos do OS, consulte Configurações gerenciadas (política da organização).

~/.snowflake/cortex/settings.json

Arquivo de configurações principal da Cortex Code CLI.

~/.snowflake/cortex/permissions.json

Preferências de permissão.

~/.snowflake/cortex/mcp.json

Configuração do servidor MCP (consulte Model Context Protocol (MCP))

~/.snowflake/config.toml

Conexões do Snowflake (consulte Cortex Code CLI). Compartilhado com a Snowflake CLI.

O layout completo do diretório de configuração principal é:

~/.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

Precedência de configurações

As configurações são aplicadas na seguinte ordem de precedência (maior para menor):

  1. Configurações gerenciadas (arquivo de política gerenciada pelo sistema, se presente). Consulte Configurações gerenciadas (política da organização).

  2. Comandos na sessão (/plan, entre outros)

  3. Argumentos de linha de comando

  4. Variáveis de ambiente

  5. Arquivos de configuração (~/.snowflake/cortex/)

  6. Valores padrão incorporados na Cortex Code CLI

settings.json

~/.snowflake/cortex/settings.json

Arquivo de configurações principal para a Cortex Code CLI.

Exemplo de conteúdo:

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

As seguintes configurações estão disponíveis:

  • compactMode: habilita a formatação de saída compacta.

  • autoUpdate: habilita as atualizações automáticas.

  • theme: define o tema da CLI (light ou dark).

permissions.json

~/.snowflake/cortex/permissions.json

Controla as permissões de acesso à ferramenta.

Exemplo de conteúdo:

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

As seguintes configurações estão disponíveis:

  • onlyAllow: lista de padrões de ferramenta permitidos.

  • defaultMode: modo de permissão padrão (ask, allow, deny).

  • dangerouslyAllowAll: permite todas as ferramentas sem avisos (não é seguro).

Configurações gerenciadas (política da organização)

As configurações gerenciadas permitem que administradores de IT apliquem políticas em toda a organização à Cortex Code CLI. Por exemplo, os administradores podem restringir quais ferramentas ou contas podem ser usadas, impor versões mínimas de CLI e desabilitar recursos de bypass.

Normalmente, essas configurações são implantadas por meio de ferramentas de gerenciamento de configuração empresariais (como MDM ou SCCM). Geralmente, os usuários não podem modificar as configurações gerenciadas, a menos que tenham privilégios de administrador/root.

Locais dos arquivos

O arquivo de configurações gerenciadas é armazenado em um caminho no nível do sistema:

Plataforma

Caminho

macOS

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

Linux e WSL

/etc/cortex/managed-settings.json

Esquema de configuração

O arquivo de configurações gerenciadas usa JSON com a seguinte estrutura:

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

Permissões

A seção permissions restringe o que os usuários podem acessar. Por exemplo, você pode permitir ou negar padrões de ferramenta e de conta.

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

Campo

Tipo

Padrão

Descrição

onlyAllow

string[]

—

Lista de permissão de padrões. Se definido, somente itens correspondentes são permitidos.

deny

string[]

—

Lista de negação de padrões. A negação tem precedência sobre a permissão.

defaultMode

"allow" ou "deny"

"deny"

Comportamento quando não há correspondência com nenhuma regra.

dangerouslyAllowAll

boolean

false

Controla se o modo bypass é permitido.

Configurações

A seção settings aplica o comportamento de tempo de execução:

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

Campo

Tipo

Padrão

Descrição

forceNoHistoryMode

boolean

false

Não forçar a persistência do histórico de conversas.

forceSandboxEnabled

boolean

false

Forçar o sandbox sempre habilitado.

forceSandboxMode

"regular" ou "autoAllow"

—

Forçar um modo sandbox específico.

Obrigatório

A seção required pode impor versões mínimas:

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

Campo

Tipo

Descrição

minimumVersion

string

Versão de CLI mínima As versões mais antigas exibem um erro e são encerradas.

Padrões

A seção defaults fornece os valores padrão. Os usuários podem substituir esses padrões somente se permitidos pela política.

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

Campo

Tipo

Descrição

connectionName

string

Nome da conexão padrão do Snowflake.

profileName

string

Perfil padrão a ser carregado.

theme

string

Tema padrão da UI (por exemplo, dark ou light).

UI

A seção ui controla a apresentação da interface do usuário:

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

Campo

Tipo

Padrão

Descrição

showManagedBanner

boolean

false

Exibir um banner indicando o estado gerenciado.

bannerText

string

—

Texto personalizado do banner gerenciado.

hideDangerousOptions

boolean

false

Ocultar opções perigosas da ajuda e da UI.

Exemplos

Configuração corporativa básica

Permita a funcionalidade padrão, mas desabilite o modo bypass e mostre um banner gerenciado.

{
  "version": "1.0",
  "permissions": {
    "dangerouslyAllowAll": false,
    "defaultMode": "allow"
  },
  "settings": {},
  "required": {
    "minimumVersion": "0.25.0"
  },
  "ui": {
    "showManagedBanner": true,
    "bannerText": "Managed by IT"
  }
}
Copy
Restringir a contas Snowflake específicas

Permita somente conexões com contas de produção e preparação.

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

Variáveis de ambiente

A Cortex Code CLI reconhece as seguintes variáveis de ambiente de configuração:

Variável

Descrição

SNOWFLAKE_HOME

Substitui o diretório padrão ~/.snowflake.

CORTEX_AGENT_MODEL

Substitui a seleção de modelo.

CORTEX_ENABLE_MEMORY

Habilita a ferramenta de memória (definida como true ou 1).

COCO_DANGEROUS_MODE_REQUIRE_SQL_WRITE_PERMISSION

Requer confirmação para operações de gravação SQL no modo bypass.

Nota

Para obter variáveis de ambiente adicionais relacionadas à permissão, consulte Segurança.

Substituições de linha de comando

As configurações da Cortex Code CLI podem ser substituídas por meio de argumentos de linha de comando como estes:

Exemplo

Descrição

cortex -c production

Especifica a conexão.

cortex --workdir /path

Define o diretório de trabalho.

cortex --continue

Continua a última sessão.

cortex --resume <session_id>

Retoma uma sessão específica.

cortex --plan

Habilita o modo de planejamento.

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

Desabilita os avisos de permissão (não é seguro).

Armazenamento de sessões

As conversas e as configurações são armazenadas em:

Local

Descrição

~/.snowflake/cortex/conversations/

Arquivos de sessão.

~/.snowflake/cortex/permissions.json

Preferências de permissão.

~/.snowflake/cortex/mcp.json

Configuração do MCP.