Como usar o Cursor CLI: guia passo a passo

Para usar o Cursor CLI, instale com curl https://cursor.com/install -fsS | bash, faça login com agent login, entre na pasta de um projeto e rode agent. Você descreve uma tarefa; o agente do Cursor lê seu código, edita arquivos e executa comandos depois que você aprova. Para scripts e CI, agent -p "sua tarefa" executa um único prompt sem a interface interativa.

Esse é o ciclo básico. Este guia cobre o resto: os três modos, o print mode, modelos, arquivos de regras, servidores MCP, permissões, como o CLI consome a cota do seu plano do Cursor, os limites dele e como usá-lo ao lado de outros CLIs de programação. Tudo aqui se baseia na documentação oficial do Cursor em outubro de 2026.

O que é o Cursor CLI

O Cursor CLI leva o agente do editor Cursor para o terminal. Ele usa a mesma conta, os mesmos modelos, as mesmas regras e as mesmas configurações de MCP do editor, então, se sua equipe já usa o Cursor, o CLI se comporta como todo mundo espera. Ele roda em qualquer lugar com um terminal: um servidor acessado por SSH, um runner de CI ou um painel ao lado de outro agente.

Uma observação sobre o nome: o comando se chamava cursor-agent. Em janeiro de 2026, o Cursor tornou agent o comando principal, e cursor-agent continua funcionando como alias. Guias e ferramentas antigos que chamam cursor-agent não quebram; este guia usa agent.

Se você ainda está decidindo entre o Cursor e um agente feito para o terminal, Claude Code vs Cursor compara os dois. Este post parte do princípio de que você escolheu o Cursor e quer usá-lo pelo terminal.

Passo 1: instale o Cursor CLI

Confira a instalação:

agent --version

Se o shell não encontrar agent, adicione ~/.local/bin ao seu PATH e abra um terminal novo. O CLI se atualiza sozinho por padrão; para atualizar à mão, basta agent update.

Passo 2: faça login

agent login     # abre o navegador
agent status    # mostra com qual conta você está logado
agent logout

Numa máquina sem navegador, defina NO_OPEN_BROWSER=1 e o agent login mostra a URL em vez de abri-la. Para CI e scripts, crie uma chave de API no painel do Cursor, em API Keys, e passe-a pela variável de ambiente CURSOR_API_KEY ou com --api-key.

Passo 3: a sessão interativa

Inicie o agente num projeto, com ou sem um primeiro prompt:

cd my-project
agent
agent "add input validation to the signup form"

O CLI tem três modos, e Shift+Tab alterna entre eles:

Um bom hábito para qualquer coisa que não seja trivial: comece no Plan, alinhe a abordagem e depois mude para o Agent para ele implementar. Mais algumas coisas que você vai usar todo dia:

• @ escolhe arquivos para anexar à mensagem.
• Ctrl+R permite revisar as mudanças que o agente fez.
• Shift+Enter (ou Ctrl+J) adiciona uma quebra de linha; seta para cima percorre suas mensagens anteriores.
• Comandos de shell esperam um y/n antes de rodar.
• /model troca de modelo; /clear começa um chat novo; /summarize resume um chat longo.
• Ctrl+D duas vezes sai.

Os chats ficam salvos. agent ls lista todos, agent resume (ou --continue) volta ao mais recente e --resume="chat-id" abre um específico. Dentro da sessão, /resume, /fork e /rewind fazem o que o nome diz.

Dois extras valem a pena conhecer. Se você começar uma mensagem com &, a conversa passa para um Cursor Cloud Agent, que continua trabalhando enquanto você está fora; você retoma em cursor.com/agents. E -w (ou --worktree nome) roda o agente num novo worktree do Git em ~/.cursor/worktrees/, sem mexer na sua cópia de trabalho atual.

Passo 4: print mode para scripts e CI

O print mode executa um único prompt e encerra. Assim você pode usar o CLI em scripts, hooks do Git e pipelines de CI:

# Uma pergunta somente leitura, resposta em texto simples
agent -p "summarize what changed in src/billing since the last release"

# Aplicar mudanças (sem --force elas só são propostas)
agent -p --force "add JSDoc comments to every exported function in src/utils"

# Saída legível por máquina para outra ferramenta
agent -p --output-format json "list the TODO comments in this repo"

As flags que importam aqui:

• --force (alias --yolo) deixa o agente gravar arquivos e executar comandos sem perguntar, a menos que uma regra de bloqueio impeça. É a chave que faz o print mode realmente mudar alguma coisa.
• --output-format aceita text (padrão), json ou stream-json. Combine stream-json com --stream-partial-output para receber o texto enquanto ele é gerado.
• --trust confia no workspace sem perguntar; --approve-mcps aprova os servidores MCP configurados.
• --model e --workspace definem o modelo e a pasta.

O Cursor também documenta como rodar o CLI no GitHub Actions. Se for usar --force no CI, trate como qualquer agente sem supervisão: uma chave de API com escopo restrito, um runner descartável e mudanças que chegam numa branch para revisão.

Passo 5: escolha um modelo

agent models                   # modelos que sua conta pode usar
agent --model <model-id>       # começar com um modelo específico

Dentro da sessão, /model abre o seletor e /model grok filtra a lista. Se você não indicar um modelo, o CLI usa o que está configurado na sua conta. Os modelos que aparecem dependem do seu plano (veja a seção de preços abaixo): todos os planos pagos incluem os modelos próprios do Cursor, enquanto os de terceiros exigem Premium ou superior.

Passo 6: regras, AGENTS.md e CLAUDE.md

O Cursor CLI usa o mesmo sistema de regras do editor. As regras ficam em .cursor/rules, e o CLI também lê AGENTS.md e CLAUDE.md na raiz do projeto e os aplica como regras. Desde a versão de outubro de 2026, arquivos AGENTS.md em subpastas valem quando o agente edita arquivos dentro dessas pastas.

# Project rules

- Package manager: pnpm. Run `pnpm test` before you finish a task.
- TypeScript strict mode; no `any` in new code.
- Never edit files in src/generated/.

Se vários agentes trabalham no mesmo repositório, AGENTS.md é o arquivo que todos leem, então é o lugar certo para as regras compartilhadas. agent generate-rule cria uma nova regra do Cursor de forma interativa. O que vale colocar nesses arquivos está em Como escrever CLAUDE.md e AGENTS.md.

Passo 7: servidores MCP

Servidores MCP dão novas ferramentas ao agente: um navegador, um rastreador de issues, um banco de dados. O Cursor CLI lê o mesmo mcp.json do editor: .cursor/mcp.json para o projeto e ~/.cursor/mcp.json para todos os projetos. O que você configurou no editor já está disponível no CLI.

agent mcp list                 # servidores configurados e o status deles
agent mcp list-tools <id>      # ferramentas que um servidor oferece
agent mcp login <id>           # login num servidor que usa OAuth
agent mcp disable <id>         # desativar sem remover

Dentro da sessão, /mcp list mostra o mesmo. Cada servidor adiciona suas ferramentas ao contexto do agente, então deixe ativos só os que você precisa.

Passo 8: permissões e configuração

As configurações globais ficam em ~/.cursor/cli-config.json (no Windows, %USERPROFILE%\.cursor\cli-config.json). Um projeto pode adicionar um .cursor/cli.json que contém apenas permissões. Os dois são JSON puro, sem comentários.

{
  "permissions": {
    "allow": ["Shell(git)", "Shell(ls)", "Read(src/**/*.ts)", "Write(package.json)", "Mcp(datadog:*)"],
    "deny": ["Shell(rm)", "Read(.env*)", "Write(**/*.key)"]
  }
}

Cada entrada indica uma ferramenta e um padrão: Shell(...), Read(...), Write(...), WebFetch(domínio) e Mcp(servidor:ferramenta). O bloqueio vence a permissão. O arquivo global também define o modo de aprovação (allowlist, auto-review ou unrestricted), as configurações de sandbox e se os commits ganham uma linha “Made with Cursor”.

Como o Cursor CLI se liga ao seu plano do Cursor

Não existe uma assinatura separada para o CLI. Ele usa sua conta do Cursor e, em outubro de 2026, o Cursor é vendido como parte da The X Subscription, junto com Grok e X. Cada plano pago tem uma única cota de uso para os modelos próprios do Cursor (Grok 4.7, Grok 4.6, Grok 4.5 e Composer 2.5). O editor, o CLI, os Cloud Agents e os apps do Grok consomem dela, e ela se renova toda semana.

O que isso significa no uso do CLI:

• Cada modelo consome a cota num ritmo diferente. O uso restante e a próxima renovação aparecem nas configurações do editor e no painel de uso.
• Claude, GPT e Gemini não entram na cota. No Premium e acima, você paga por eles desde a primeira requisição, pelo preço de tabela da API, com crédito pré-pago. Plus e Free não podem usá-los.
• O Plus não tem Cloud Agents nem Auto. Passar a conversa para um Cloud Agent com & exige Premium ou superior.
• Os planos antigos continuam funcionando. Pro, Pro+, Ultra, Start e assentos Teams Standard ou Premium contam como planos legados e mantêm suas duas cotas mensais e o uso sob demanda.

Limites que vale conhecer

• O Shell Mode tem tempo limite de 30 segundos. /shell executa comandos diretamente, mas não consegue manter servidores rodando nem lidar com prompts interativos, e o cd não persiste entre comandos.
• O print mode é cauteloso por padrão. Sem --force, ele propõe as mudanças em vez de gravá-las, o que pega quase todo mundo de surpresa na primeira vez.
• Os arquivos de configuração são JSON estrito. Um comentário ou uma vírgula sobrando no cli-config.json quebra o arquivo.
• Um chat por terminal. O CLI tem worktrees e Cloud Agents, mas nenhuma visão embutida que mostre vários agentes locais ao mesmo tempo.

Erros comuns

• command not found: agent. ~/.local/bin não está no seu PATH.
• Uma ferramenta ainda chama cursor-agent. Tudo bem, o alias continua. Só a documentação passou a usar agent.
• O modelo que você quer não aparece na lista. É um modelo de terceiros e seu plano é Free ou Plus.
• As regras são ignoradas. Confira se AGENTS.md ou CLAUDE.md está na raiz do projeto, ou se a regra em .cursor/rules se aplica aos arquivos editados.
• O CI trava num pedido de aprovação. Adicione --trust, use CURSOR_API_KEY e passe --approve-mcps se houver servidores MCP configurados.

Rodando o Cursor CLI ao lado de outros CLIs

Se sua equipe já vive no Cursor, o Cursor CLI é uma boa escolha: os mesmos modelos, regras e servidores MCP no editor e no terminal. Se você quer pontos de extensão profundos no terminal, como hooks, skills e plugins, o Claude Code é mais forte nisso. E se está pensando em deixar o Cursor de vez, Melhores alternativas ao Cursor apresenta as opções com honestidade.

Muita gente acaba rodando o Cursor CLI ao lado do Claude Code, do Codex ou do Gemini CLI, cada um na sua tarefa. Em terminais soltos, isso significa uma aba por agente e worktrees com -w para mantê-los separados. O AgentVera é um app de desktop que roda esses CLIs lado a lado em terminais reais, com as suas próprias instalações e logins. O suporte ao Cursor funciona assim:

• Cada agente tem o próprio chat. Um chat vazio é criado para cada novo agente do Cursor (cursor-agent create-chat) e o agente sempre volta a ele, então vários agentes do Cursor trabalham no mesmo projeto sem se atrapalhar. O editor do Cursor não precisa estar aberto.
• Seu login, seus modelos. É usado o login do próprio Cursor CLI; se o modelo ficar vazio, vale o das configurações do Cursor.
• Regras, não prompt de função. O Cursor CLI não tem flag para instruções extras, então o campo Função do agente não chega ao Cursor. Coloque instruções permanentes no AGENTS.md ou em arquivos de regras.
• MCP num só lugar. Os servidores MCP adicionados no AgentVera e o navegador do AgentVera entram como um plugin local e são aprovados para a execução.
• Grade, contas e servidores. Rode o Cursor na grade do Workspace ao lado de outros agentes, com revisão de código automática ao fim de cada turno. Em Configurações → Contas você pode colocar várias contas do Cursor numa ordem de reserva, e um agente do Cursor também pode rodar num servidor SSH salvo.

Para experimentar, baixe o AgentVera.

Resumindo

Para usar o Cursor CLI, instale, rode agent login e inicie agent num projeto. Mude para o Plan com Shift+Tab antes de mudanças grandes, use agent -p --force em scripts e mantenha suas regras no AGENTS.md ou em .cursor/rules e suas ferramentas no mcp.json. Quanto você pode usar é o seu plano do Cursor que decide, então escolha os modelos pensando na cota semanal.