Sobrescritas de configuração

O Jarvis Code CLI tem três lugares onde parâmetros de execução podem ser influenciados: o arquivo de configuração, as opções de linha de comando e as variáveis de ambiente. A relação entre eles não é um simples "quem tem prioridade maior vence" — os três atendem cenários diferentes e têm escopos que não se sobrepõem:

• Arquivo de configuração guarda preferências de longo prazo (modelo, chaves, controle de loop etc.); vale a cada inicialização
• Opções de linha de comando fazem mudanças pontuais para a execução atual; são descartadas ao sair
• Variáveis de ambiente tratam principalmente a localização do diretório de dados, a troca de endpoint OAuth e um pequeno número de interruptores de execução — não são um mecanismo geral de fallback para campos de configuração

Essa distinção importa: muita gente executa export JARVIS_API_KEY=xxx no shell esperando que o CLI use o valor automaticamente, mas ele não usa. Veja Credenciais de provedor abaixo para entender por quê.

Os três papéis das variáveis de ambiente

As variáveis de ambiente se dividem em três categorias por função e não podem ser reduzidas a uma única ordem linear de prioridade:

1. Localizar o arquivo de configuração: JARVIS_CODE_HOME define o diretório raiz de dados, tornando o caminho do arquivo de configuração $JARVIS_CODE_HOME/config.toml. Essa etapa acontece antes de toda a demais resolução e não é um fallback para parâmetros individuais.
2. Interruptores de execução: um pequeno conjunto de variáveis, como JARVIS_DISABLE_TELEMETRY, desliga diretamente o subsistema correspondente — mesmo que o config.toml tenha telemetry = true, definir essa variável com um valor verdadeiro desativa a telemetria. A semântica é "desligar adicionalmente", não "sobrescrita comum".
3. Endpoints de execução e diagnóstico: variáveis como JARVIS_CODE_OAUTH_HOST, JARVIS_CODE_BASE_URL e JARVIS_LOG_LEVEL são lidas quando os subsistemas de OAuth ou de log são inicializados. Para a lista completa, veja Variáveis de ambiente.

Prioridade para parâmetros comuns de execução

Para parâmetros comuns de execução, como alias de modelo, Plan mode (modo de planejamento), YOLO mode e diretórios de skills, a prioridade, da maior para a menor, é:

1. Opções de linha de comando (-m, --plan, --yolo etc.): valem apenas para a execução atual
2. Arquivo de configuração do usuário (~/.jarvis-code/config.toml): guarda preferências de longo prazo

Um pequeno número de variáveis de ambiente sobrescreve explicitamente campos específicos do arquivo de configuração — por exemplo, JARVIS_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT tem prioridade sobre [background].keep_alive_on_exit. Essas exceções estão anotadas em Variáveis de ambiente e nas descrições dos campos correspondentes em Arquivos de configuração.

WARNING

Parâmetros comuns de execução não caem para variáveis de ambiente do shell. O api_key e o base_url de provedor são lidos apenas do config.toml (incluindo a subtabela [providers.<name>.env]) e não caem para variáveis de shell exportadas com export. A única exceção é o canal explícito JARVIS_MODEL_* — veja Definir um modelo por variáveis de ambiente.

Hoje o CLI lê um único arquivo de configuração no nível de usuário e não tem um mecanismo de arquivo de configuração por projeto. Para isolar configuração entre projetos diferentes, aponte JARVIS_CODE_HOME para diretórios de dados distintos — veja Cenários comuns abaixo.

Credenciais de provedor

As credenciais de provedor (api_key, base_url) seguem regras de resolução próprias, separadas da cadeia de prioridade dos parâmetros comuns.

Para um único provedor, as credenciais são resolvidas nesta ordem:

1. [providers.<name>].api_key — chave escrita diretamente no arquivo de configuração; prioridade máxima
2. A chave correspondente dentro da subtabela [providers.<name>.env] (JARVIS_API_KEY, ANTHROPIC_API_KEY etc.) — consultada apenas quando api_key está vazio
3. Se ambos estiverem ausentes — a inicialização falha com um erro indicando que o provedor está sem credenciais

O base_url é resolvido do mesmo jeito: primeiro [providers.<name>].base_url, depois a chave *_BASE_URL em [providers.<name>.env].

A subtabela [providers.<name>.env] é apenas uma seção TOML do arquivo de configuração — ela não escreve nada no ambiente do shell. Só é consultada quando o campo direto correspondente (api_key / base_url) está vazio.

Para a lista completa de nomes de chave de credencial, veja Variáveis de ambiente: nomes de chave de credencial de provedor.

Opções de linha de comando

Opções passadas na inicialização têm a prioridade mais alta e valem apenas para a sessão atual:

Opção	Efeito
-S, --session [id]	Retoma uma sessão específica; entra em seleção interativa quando nenhum id é informado
-c, --continue	Retoma a última sessão do diretório de trabalho atual
-y, --yolo	Aprova automaticamente chamadas de ferramenta comuns; o agente ainda pode fazer perguntas
--auto	Inicia no modo de permissão auto: totalmente autônomo, o agente não faz perguntas
--plan	Inicia no Plan mode
-m, --model <model>	Usa um alias de modelo específico nesta sessão
-p, --prompt <prompt>	Executa em modo não interativo: roda um único prompt e sai
--output-format <format>	Formato de saída do modo -p: text ou stream-json
--skills-dir <dir>	Substitui os diretórios de skills descobertos automaticamente (repetível; vale só para esta sessão)
--agent <name>	Inicia a nova sessão com o perfil de agente informado
--agent-file <path>	Carrega um arquivo de agente com a prioridade mais alta e inicia a nova sessão com ele
--add-dir <dir>	Adiciona um diretório de workspace extra a esta sessão (repetível)

Regras de exclusão mútua (a inicialização falha se violadas):

• --output-format só pode ser usado com -p
• --prompt não pode ser combinado com --yolo, --auto ou --plan
• --prompt não pode ser combinado com --session quando nenhum id é informado
• --continue e --session não podem ser usados juntos
• --yolo e --auto não podem ser usados juntos
• --agent e --agent-file não podem ser usados juntos, e nenhum deles pode ser combinado com --continue ou --session

TIP

O --skills-dir é uma substituição pontual que só afeta a execução atual. Para adicionar diretórios de busca de forma persistente, escreva extra_skill_dirs no config.toml (veja Agent Skills).

Cenários comuns

Ambiente de teste isolado — use um diretório de dados separado para não poluir a configuração e as sessões principais:

JARVIS_CODE_HOME="$PWD/.jarvis-sandbox" jarvis

Chave de teste pontual — como as credenciais de provedor são lidas apenas do arquivo de configuração, escreva uma chave de teste na subtabela env:

[providers.kimi.env]
JARVIS_API_KEY = "sk-test"

Pular aprovação em tarefas em lote:

jarvis --yolo -p "Renomeie em lote os arquivos a seguir..."

Entrar no Plan mode temporariamente (para torná-lo permanente, defina default_plan_mode = true no arquivo de configuração):

jarvis --plan

Próximos passos

• Arquivos de configuração — referência completa de todos os campos configuráveis
• Variáveis de ambiente — lista completa e descrição de JARVIS_CODE_HOME e variáveis relacionadas