# Como usar o Cursor CLI: guia passo a passo

URL: https://agentvera.dev/pt/blog/how-to-use-cursor-cli/ · Publicado: 2026-10-29

Como usar o Cursor CLI: instale o comando agent, faça login, alterne entre os modos Agent, Plan e Ask, automatize com o print mode e configure modelos, regras e MCP.

**Resumo:**

- Instale o Cursor CLI com um comando curl (no Windows, com uma linha de PowerShell), faça login com agent login e rode agent no seu projeto. O nome antigo, cursor-agent, continua funcionando como alias.
- agent abre uma sessão interativa com os modos Agent, Plan e Ask. agent -p executa uma única tarefa para scripts e CI; adicione --force para aplicar as mudanças e --output-format json para saída legível por máquina.
- O CLI consome a cota do seu plano do Cursor e usa as mesmas regras do editor (.cursor/rules, AGENTS.md, CLAUDE.md) e o mesmo mcp.json, então sua configuração do Cursor vem junto.

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](/pt/blog/claude-code-vs-cursor/ "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

| Plataforma | Comando |
| --- | --- |
| macOS, Linux, WSL | `curl https://cursor.com/install -fsS \| bash` |
| Windows (PowerShell) | `irm 'https://cursor.com/install?win32=true' \| iex` |

Confira a instalação:

```bash
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

```bash
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:

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

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

| Modo | O que faz | Como trocar |
| --- | --- | --- |
| Agent | O padrão. Edita arquivos e executa comandos. | Padrão |
| Plan | Define a abordagem com você antes de mexer no código. | Shift+Tab, `/plan`, `--plan` ou `--mode=plan` |
| Ask | Somente leitura. Explora o código e responde perguntas. | `/ask` ou `--mode=ask` |

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:

```bash
# 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

```bash
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.

```markdown
# 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](/pt/blog/claude-md-agents-md/ "Como escrever CLAUDE.md e AGENTS.md").

## Passo 7: servidores MCP

[Servidores MCP](/pt/blog/what-is-mcp-server/ "O que é um servidor 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.

```bash
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.

```json
{
  "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.

| Plano | Preço por mês | Uso incluído | Modelos de terceiros |
| --- | --- | --- | --- |
| Free | US$ 0 | Limitado | Não |
| Plus | US$ 8 | Básico | Não |
| Premium | US$ 30 | 4 vezes o Plus | Preço de tabela da API a partir de crédito pré-pago |
| Super | US$ 100 | 15 vezes o Plus | Preço de tabela da API a partir de crédito pré-pago |
| Ultra | US$ 200 | 50 vezes o Plus | Preço de tabela da API a partir de crédito pré-pago |
| Teams | US$ 30, 100 ou 200 por assento | Conforme o nível do assento | Preço de tabela da API mais a tarifa por token do Cursor |

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](/pt/blog/best-cursor-alternatives/ "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](/pt/agents/cursor-agent/ "Cursor no AgentVera") 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](/pt/features/workspace/ "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](/pt/features/account-switching/ "Troca de conta") numa ordem de reserva, e um agente do Cursor também pode rodar num servidor SSH salvo.

Para experimentar, [baixe o AgentVera](/pt/download/ "Baixar 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.

## Perguntas frequentes

**O comando do Cursor CLI é agent ou cursor-agent?** Os dois funcionam. Em outubro de 2026, agent é o comando principal e cursor-agent continua como alias para scripts e ferramentas antigos. Confira a instalação com agent --version.

**O Cursor CLI é gratuito?** Instalar o CLI é gratuito, e ele funciona no plano Free do Cursor com uso limitado. Os planos pagos incluem uma cota semanal para os modelos próprios do Cursor, compartilhada entre o editor, o CLI e os Cloud Agents. Modelos de terceiros como Claude, GPT e Gemini exigem Premium ou superior e são cobrados pelo preço de tabela da API a partir de crédito pré-pago.

**O Cursor CLI lê AGENTS.md e CLAUDE.md?** Sim. Além das regras em .cursor/rules, o CLI lê AGENTS.md e CLAUDE.md na raiz do projeto e os aplica como regras. Arquivos AGENTS.md em subpastas valem quando o agente edita arquivos dentro dessas pastas.

**Por que agent -p não altera meus arquivos?** Sem --force (ou o alias --yolo), o print mode só propõe as mudanças em arquivos em vez de aplicá-las. Use agent -p --force em scripts que precisam gravar arquivos, e só em repositórios e máquinas onde você se sente à vontade para permitir isso.

**Preciso ter o editor do Cursor instalado ou aberto?** Não. O Cursor CLI é instalado à parte e funciona sozinho em qualquer terminal no macOS, Linux, WSL ou Windows. Ele compartilha sua conta, suas regras e suas configurações de MCP com o editor, mas não precisa que ele esteja aberto.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/