A CLI claude: as flags que mudam o resultado

Intermediário

Última verificação: 2026-10-07.

Todos os comandos, flags, padrões e versões mínimas abaixo vêm da referência oficial da CLI, lida em 2026-10-07. As flags surgem e mudam entre versões, e a referência afirma claramente que claude --help não lista todas as flags — então uma flag ausente do --help não está necessariamente ausente da sua build. Consulte a referência, não o texto de ajuda, e confira sua versão com claude -v.

Confirme na fonte oficial.

A maioria das pessoas aprende três coisas da linha de comando do Claude Code — claude, claude -c e claude -p — e para por aí. É um ponto justo para parar se você só o usa sentado diante dele. No momento em que você coloca o Claude Code num script, num job de CI, numa fila em segundo plano ou nas mãos de um colega, as flags deixam de ser conveniências e passam a ser a diferença entre uma execução que custa um dólar e uma que fica travada por uma hora.

Esta página não é uma segunda cópia da tabela de referência. Ela é a ordem em que vale aprender a superfície, as flags que de fato mudam o que acontece e as quatro armadilhas que já custaram tempo real às pessoas.

What you'll learn

• Os seis tipos de sessão que você pode iniciar e qual flag escolhe cada um
• O contrato de cinco flags que torna uma execução sem supervisão limitada, respondível e analisável
• Por que editar --append-system-prompt e rodar --continue de novo parece não fazer nada — a regra do prompt gravado
• Como --bare, --safe-mode e --restricted se diferenciam e qual usar em cada caso
• Conduzir sessões em segundo plano pelo shell: agents, attach, logs, respawn, rm, daemon
• Os pares de flags que as pessoas confundem: --tools vs --allowedTools vs --disallowedTools

Comece pela pergunta: que tipo de sessão é esta?

Toda outra decisão decorre desta. O Claude Code pode iniciar seis coisas materialmente diferentes, e a flag que escolhe uma delas costuma ser a primeira coisa que você digita.

Você quer	Flag	Isso lhe dá
Uma conversa que você acompanha	(nenhuma)	Sessão interativa neste terminal
Uma resposta e sair	-p / --print	Execução não interativa, saída para stdout
Trabalho que sobreviva a este terminal	--bg / --background	Uma sessão em segundo plano; imprime seu ID e como gerenciá-la
Uma branch isolada para experimentar	-w / --worktree	Um git worktree em <repo>/.claude/worktrees/<name>
Trabalho nas máquinas da Anthropic	--cloud	Uma sessão na nuvem, ou um acompanhamento enfileirado em uma existente
Conduzir esta sessão pelo celular	--rc / --remote-control	Uma sessão interativa que também pode ser controlada pelo claude.ai ou pelo app do Claude

Duas delas não podem ser combinadas: --bg e -p são mutuamente exclusivas, porque uma retorna imediatamente e a outra espera uma resposta. Se você quer um comando de shell, e não uma sessão do Claude, em segundo plano, combine --bg com --exec:

Run the test suite as a background job, not a Claude session

claude --bg --exec 'pytest -x'

E o --bg verifica a confiança do workspace para o diretório antes de começar — assim, uma sessão em segundo plano num repositório não confiável falha logo de início, e não no meio do caminho.

O contrato de cinco flags para execuções sem supervisão

Esta é a coisa de maior valor desta página. Uma execução de claude -p sem supervisão tem três jeitos de dar errado que uma sessão interativa simplesmente não tem: ela pode travar em pedidos de permissão que ninguém está lá para responder, pode entrar em loop por muito mais tempo do que você esperava e pode emitir prosa quando seu script precisava de dados. Cinco flags fecham os três.

Guided walkthrough1 of 5

1. `claude -p "query"` imprime a resposta e sai. Tudo abaixo é exclusivo do modo print, então esta flag é a porta de entrada para o resto.

A CI step that cannot hang, cannot loop forever, and cannot overspend

claude -p "Review the staged diff and list bugs" \
--permission-prompts none \
--allowedTools "Read" "Bash(git diff *)" \
--max-turns 6 \
--max-budget-usd 2.00 \
--output-format json

--max-budget-usd é uma estimativa, não a sua fatura

• O Claude Code compara o teto com a própria estimativa de custo do lado do cliente, que pode diferir do que você é cobrado.
• Quando você volta a uma conversa com --continue ou --resume, os totais restaurados de execuções anteriores não contam para o teto — então três execuções retomadas sob um teto de US$ 2 podem gastar mais de US$ 2 no total.
• Trate-o como um disjuntor para uma única execução. Para um teto real sobre uma conta ou um projeto inteiro, veja Hard Spend Caps.

Para a postura completa sobre deixar uma execução prosseguir sem um humano — o que permitir, o que mascarar, o que registrar — veja Blindando execuções autônomas e Modo headless e o Agent SDK. Para tetos no nível do provedor, Hard Spend Caps.

A família do prompt de sistema, e a armadilha dentro dela

Cinco flags moldam o prompt de sistema. Quatro definem o texto dele; a quinta decide se a conversa mantém o texto com o qual começou.

Flag	O que faz
--system-prompt	Substitui todo o prompt padrão pelo seu texto
--system-prompt-file	Substitui pelo conteúdo de um arquivo
--append-system-prompt	Acrescenta seu texto ao prompt padrão
--append-system-prompt-file	Acrescenta o conteúdo de um arquivo ao prompt padrão
--system-prompt-snapshot	off reconstrói o prompt a cada requisição; on (o padrão) reutiliza o gravado

A escolha entre acrescentar e substituir é uma escolha de identidade. Acrescentar mantém a orientação de ferramentas, as instruções de segurança e as convenções de código padrão do Claude Code, e coloca suas regras por cima — certo para instruções por execução, formatação de saída ou contexto do projeto. Substituir descarta tudo isso, inclusive a orientação de ferramentas, o que só é adequado quando a superfície realmente não é um assistente de código: um agente que não programa, num pipeline que ninguém observa. Se você substitui, é responsável por tudo o que a tarefa ainda precisa.

Você pode combiná-las. Passar uma flag de acrescentar junto com uma de substituir substitui o padrão e depois acrescenta seu texto. A partir da v2.1.283 você também pode passar uma flag junto com a sua própria forma de arquivo — --append-system-prompt e --append-system-prompt-file — e o Claude Code usa as duas, com o conteúdo do arquivo primeiro, independentemente da ordem em que você as digitou.

A armadilha: uma conversa retomada reutiliza o prompt com o qual nasceu

• O Claude Code constrói o prompt de sistema uma vez, na primeira requisição de uma conversa, e o grava na sessão.
• Até a conversa ser compactada, toda requisição seguinte usa esse prompt gravado — inclusive depois de --resume ou --continue.
• Então você edita o texto do --append-system-prompt, roda claude --continue de novo e nada muda. A flag não está quebrada; a conversa ainda está usando a gravação.
• O texto novo passa a valer quando a conversa é compactada, ou numa conversa totalmente nova.
• Para iterar na redação entre execuções com --continue, passe --system-prompt-snapshot off e o prompt é reconstruído a cada requisição. Requer v2.1.257 ou posterior.

Há mais um truque que vale conhecer num prompt de substituição que mistura instruções estáveis com contexto por execução. Coloque entre eles uma linha contendo apenas __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__: o Claude Code divide na primeira linha assim e a remove, de modo que a parte de cima continua em cache enquanto a de baixo muda. Requer v2.1.275 ou posterior. Por que isso importa para a sua fatura é o assunto de Prompt Caching.

E para cargas de trabalho com scripts e vários usuários, --exclude-dynamic-system-prompt-sections move o contexto por usuário, como o local da memória automática, do prompt de sistema para a primeira mensagem do usuário — assim a mesma tarefa em máquinas diferentes compartilha um único prefixo em cache. Aplica-se apenas ao prompt padrão e é ignorada quando você define --system-prompt ou --system-prompt-file.

Três flags que desligam coisas, e não são a mesma coisa

As pessoas as usam de forma intercambiável e depois se perguntam por que o sintoma não se moveu. Elas resolvem três problemas diferentes.

	--bare	--safe-mode	--restricted
O problema que resolve	A inicialização é lenta demais para uma chamada em script	Minha configuração está quebrada e não sei qual parte	Um harness de avaliação não pode tocar nesta máquina compartilhada
CLAUDE.md, skills, comandos, subagentes, plugins, MCP, memória automática	Não são descobertos	Não são carregados	Só as configurações gerenciadas e --settings são carregadas
Ferramentas embutidas	Bash, leitura de arquivo, edição de arquivo	Funcionam normalmente	As ferramentas que executam comandos/código e o WebFetch são removidos, a menos que citados individualmente em --tools
Acesso a arquivos	Normal	Normal	Confinado aos diretórios de trabalho
bypassPermissions	Permitido	Permitido	Recusado
Política gerenciada	Aplica-se	Continua se aplicando, inclusive hooks de política e a linha de status	Aplica-se
Efeito colateral	Define CLAUDE_CODE_SIMPLE	Define CLAUDE_CODE_SAFE_MODE	Recusa criar sessões na nuvem

Leia a tabela como uma progressão de intenção: --bare é sobre velocidade, --safe-mode é sobre diagnóstico, --restricted é sobre contenção. Um detalhe útil: skills num diretório que você passa com --add-dir ainda carregam com --bare, e é assim que você mantém exatamente uma capacidade numa execução, de resto, despida.

--safe-mode é o primeiro a usar quando algo se comporta mal e você não sabe se é o Claude Code ou a sua própria configuração — inclusive quando você tenta descobrir se uma personalização é o que dispara o fallback automático de modelo. Combine-o com claude doctor, que imprime diagnósticos somente leitura da instalação e das configurações sem iniciar sessão alguma. (O comando /doctor dentro da sessão é outra coisa: ele também pode aplicar correções.) Mais depuração partindo do sintoma em Solução de problemas do Claude Code. --restricted requer v2.1.248 ou posterior.

Conduzindo sessões em segundo plano pelo shell

Depois que você inicia sessões com --bg, o terminal vira um plano de controle. Todo o ciclo de vida tem um comando, e nada disso exige abrir a UI interativa.

Guided walkthrough1 of 6

1. Abre a visão de agentes para monitorar e despachar sessões paralelas em segundo plano. Para scripts, `--json` imprime as sessões ativas como um array JSON, e `--json --all` inclui as concluídas. `--cwd <path>` restringe às sessões iniciadas sob aquele diretório. Abrir a visão em si precisa de um terminal interativo; a forma JSON não.

A contrapartida disso de dentro de uma sessão — como o trabalho vai para o segundo plano e o que se mantém quando isso acontece — está em Tarefas em segundo plano, /loop e agendamento.

Os pares de flags que as pessoas erram

Seis confusões que vale antecipar

• --tools restringe quais ferramentas embutidas existem. --allowedTools diz quais chamadas pulam o pedido de permissão. --disallowedTools nega chamadas. São três trabalhos diferentes, e passar o errado é a causa mais comum de “por que ainda está me perguntando”.
• --tools não afeta as ferramentas MCP de forma alguma. Para removê-las também, adicione --disallowedTools "mcp__*".
• Um nome simples em --disallowedTools remove a ferramenta do contexto do Claude; uma regra com escopo como Bash(rm *) deixa a ferramenta disponível e nega apenas as chamadas correspondentes.
• --dangerously-skip-permissions inicia em bypassPermissions. --allow-dangerously-skip-permissions só adiciona esse modo ao ciclo do Shift+Tab, para você começar em modo plan e trocar depois. A segunda é quase sempre a que você realmente queria.
• --add-dir concede acesso a arquivos, mas o Claude Code não descobre a maior parte da configuração de .claude/ nesses diretórios. Adicionar um diretório não é o mesmo que adotar a configuração dele.
• --desktop não aceita prompt nem outras flags além de --verbose e das flags de --debug, porque o app Desktop inicia a sessão por conta própria. Requer v2.1.285 ou posterior.

Um pequeno detalhe de qualidade de vida: se você errar um subcomando, o Claude Code sugere a correspondência mais próxima e sai sem iniciar uma sessão — claude udpate imprime Did you mean claude update? em vez de abrir uma conversa que você não queria.

Teste-se

Check yourself

0/3

1. 1Seu job noturno roda `claude -p` dentro de um app do Agent SDK cujo callback `canUseTool` pergunta a uma pessoa, e à noite ele trava até o timeout. Qual flag provavelmente está faltando?
2. 2Você ajusta o texto do --append-system-prompt, roda `claude --continue` de novo e o comportamento não muda. Por quê?
3. 3Uma personalização está quebrando sua sessão e você não sabe qual. Qual flag a isola mantendo suas ferramentas e permissões funcionando normalmente?

Pressione Enter ou Espaço para virar o cartão. Use as setas esquerda e direita para navegar entre os cartões.Termo exibido.

1 / 8

Key takeaways

• Escolha primeiro o tipo de sessão — a flag que o define restringe todas as outras que você pode passar.
• Uma execução sem supervisão precisa de cinco flags, não de uma: -p, --permission-prompts none, --max-turns, --max-budget-usd e um formato de saída estruturado.
• Trate --max-budget-usd como um disjuntor para uma execução, não como teto da fatura. É uma estimativa do lado do cliente e os totais retomados escapam dela.
• As conversas gravam o prompt de sistema na primeira requisição. Se uma edição do prompt parece ignorada, é por isso — use --system-prompt-snapshot off enquanto itera.
• --bare é velocidade, --safe-mode é diagnóstico, --restricted é contenção. Usar a errada desperdiça uma tarde.
• --help é incompleto por projeto. A referência da CLI é a fonte da verdade, e as versões mínimas importam — confira claude -v antes de culpar uma flag.

Próximos passos

• Modo headless e o Agent SDK — o que construir quando uma chamada -p avulsa não basta mais
• settings.json: o sistema de configuração — o lar permanente das flags que você vive redigitando
• Solução de problemas do Claude Code — depuração partindo do sintoma, começando por --safe-mode

Compartilhe esta página

• X
• LinkedIn
• Reddit
• Hacker News