Tutorial do Cursor Origin: configuração da CLI, espelhamento com GitHub e pull requests

O que é o Cursor Origin?

O Cursor Origin é um "forge" Git. Ele hospeda repositórios, espelha projetos do GitHub e oferece suporte a pull requests e navegação de código. Repositórios no Origin também funcionam com os agentes em nuvem e automações do Cursor.

Qual é a diferença entre Cursor Origin e GitHub?

O Origin não cobre todos os recursos do GitHub. Repositórios públicos não estão documentados, e os espelhos excluem GitHub Issues, workflows do GitHub Actions e segredos do Actions. O GitHub continua sendo a plataforma mais ampla para repositórios públicos, Issues, Actions e apps de terceiros, então hoje o Origin é o serviço mais enxuto.

A principal diferença está abaixo do fluxo Git já conhecido: o Cursor criou uma camada de armazenamento separada para lidar com o volume de branches e commits gerado por agentes. O Cursor chama esse foco de "agent scale": cargas em que muitos agentes criam branches, fazem commits e abrem pull requests no mesmo repositório.

Por que o Cursor criou seu próprio host Git?

O design de armazenamento explica por que o Cursor criou um novo host Git em vez de adicionar outra interface a um já existente.

O post de engenharia sobre o Continuity do Cursor descreve hosts Git existentes como mantendo um repositório em vários servidores e confirmando um push após a maioria concordar. O Cursor diz que esse modelo custa mais quando o sistema tem milhares de repositórios de vida curta ou pushes frequentes para um único repositório.

Como funciona o armazenamento Continuity do Cursor Origin?

O Continuity, ou "Cnt", é o sistema de armazenamento por trás do Origin. Ele grava um write-ahead log em um storage de objetos compatível com S3 como fonte de verdade. O repositório Git em disco local é um cache morno que pode ser reconstruído a partir do log.

O Continuity armazena gravações do Git como objetos. Imagem do autor.

Como o log de objetos é o registro real, o Cursor pode adicionar réplicas de leitura para repositórios movimentados e removê-las quando a demanda cair. Nos testes do Cursor, a taxa de leitura subiu à medida que réplicas eram adicionadas, até 100 réplicas. O sistema lidou com até 120 pushes por segundo em S3 padrão, mas esses números não foram validados por um benchmark independente.

Para o usuário, o efeito principal é mais simples: um repositório movimentado pode ganhar capacidade de leitura, enquanto um repositório de vida curta não precisa de uma cópia local permanente em cada servidor.

Quem pode acessar o Cursor Origin?

O Origin está disponível nos planos Pro, Teams e Enterprise, mas não nos planos gratuitos. O acesso é liberado em etapas, então ter um plano elegível não garante que a guia Codebase apareça imediatamente. No Pro você possui um namespace individual e registra o nome do seu codebase.

Admins do Enterprise podem desativá-lo para a organização. A visão geral do Cursor diz que qualquer membro da equipe pode registrar o primeiro nome de codebase, enquanto a página Codebase Settings diz que um admin da equipe deve registrá-lo. Confirme essa permissão na sua equipe antes da configuração.

O que é a CLI do Cursor Origin?

O Origin traz sua própria ferramenta de linha de comando para autenticação, repositórios, pull requests e configuração de conta.

Cursor Origin CLI vs. Cursor Agent CLI

A CLI do Origin é um binário separado, origin, da Agent CLI do Cursor, que roda como agent. 

Achei fácil confundir os nomes porque origin também é o nome convencional de um remoto Git. Neste artigo, "push para origin" significa o remoto do Git, enquanto "executar origin" significa a CLI.

Quais plataformas suportam a CLI do Origin?

A documentação do Cursor cobre macOS, Linux e Windows via WSL. No momento do meu teste, Windows significava WSL porque não havia instalador nativo.

Se você estiver acompanhando no Windows, abra o terminal do Ubuntu antes de instalar a CLI. Executar o instalador no PowerShell não faz a mesma configuração.

Comandos da CLI do Cursor Origin

A CLI do Cursor Origin atualmente tem nove grupos de comandos.

A maioria dos comandos de repositório lê o alvo do remoto Git chamado origin. A opção -R owner/repo define o alvo diretamente, útil em scripts que rodam contra vários repositórios. Os comandos ruleset apenas exibem regras de push e merge existentes; eles não as alteram.

Como instalar e fazer login na CLI do Cursor Origin

O Cursor fornece a CLI por um script shell, não via gerenciador de pacotes. O comando está na página de instalação do Cursor.

Como instalar a CLI do Cursor Origin

A instalação se resume a uma linha:

curl -fsSL https://downloads.cursor.com/origin/install.sh | sh

O instalador colocou o origin em ~/.local/bin/origin. Se o seu time revisa scripts de instalação antes de executá-los, baixe o script primeiro em vez de fazer pipe direto para sh.

Corrigindo o erro "command not found" da CLI do Origin

Se o seu shell não encontra o origin após a instalação, adicione seu diretório ao PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Troque ~/.zshrc por ~/.bashrc no bash. É um ajuste único por máquina.

Verificando a instalação e o login

Execute origin --version e origin --help para confirmar a instalação e depois use origin auth login para abrir o fluxo de login do Cursor no navegador.

Veja como ficou a saída de verificação no WSL:

Versão e ajuda da CLI do Origin. Imagem do autor.

Em ambientes sem interface gráfica, a CLI imprime uma URL. O login também configura o helper de credenciais do Git, então remotos do Origin funcionam sem um token Git separado. Execute origin auth status depois para checar a sessão.

Usando uma chave de API do Cursor sem navegador

Para CI ou scripts, execute origin auth login --api-key <key> ou defina CURSOR_API_KEY antes de origin auth login. Mantenha a chave fora de arquivos versionados. CURSOR_AUTH_TOKEN é diferente e espera um bearer token.

Como criar, clonar e fazer push de um repositório no Cursor Origin

Depois de fazer login, você pode criar um repositório pela web ou pela CLI. O push usa comandos Git padrão.

Criando um repositório com origin repo create

Em cursor.com/codebase, selecione New, informe um nome e escolha a visibilidade Internal ou Private. 

Pela CLI, origin repo create my-project usa o namespace da sua conta. Inclua um owner, como em origin repo create acme/my-project, para o namespace do time. A flag opcional --default-branch altera o padrão do servidor, main.

O comando origin repo clone acme/my-project clona o repositório por HTTPS com o login salvo pela CLI.

Fazendo push do seu primeiro commit para o Origin

Após o primeiro push, o repositório aparece no Codebase:

Repositório com push e exibido no Codebase. Vídeo do autor.

Para um repositório novo e vazio, clone, adicione um arquivo e faça push:

git clone https://origin.cursor.com/{owner}/{repo}.git
cd {repo}
echo "# {repo}" > README.md
git add .
git commit -m "Initial commit"
git push -u origin main

Se o Git reportar um erro de permissão em .git/config.lock sob /mnt no WSL, clone em ~ em vez disso. Isso resolveu o erro no meu teste.

Depois do push, abra o Codebase e confirme se o commit apareceu. A guia Code mostra a árvore de arquivos e o histórico de commits. Pressione T para Ir para o arquivo ou use o campo de busca para pesquisar no código.

Fazendo push de um repositório Git existente para o Origin

Se você já tem um projeto com histórico Git, execute primeiro git remote -v. O comando abaixo só se aplica quando o repositório ainda não tem um remoto chamado origin:

git remote add origin https://origin.cursor.com/{owner}/{repo}.git
git push -u origin main

Se origin já aponta para o GitHub, use outro nome de remoto, como cursor, em vez de substituir a URL existente. Os comandos da CLI do Origin não inferem o repositório a partir desse nome, então passe -R owner/repo ao executá-los.

Como espelhar um repositório do GitHub no Cursor Origin

Um espelho copia um projeto existente do GitHub para o Origin e mantém os dois serviços conectados.

Requisitos para espelhamento do GitHub no Cursor Origin

Você vai precisar de acesso ao Origin, do app do Cursor no GitHub conectado à organização ou conta dona do repositório, e acesso de administrador ao repositório no GitHub. Acesso de escrita não é suficiente.

Como iniciar um espelho do GitHub no Cursor Origin

Em cursor.com/codebase, selecione Sync from GitHub, escolha a organização e o repositório e confirme. A alternativa na CLI é origin repo create-mirrored owner/repo, descrita na documentação de espelhamento do Cursor.

O que o Cursor Origin espelha do GitHub

O Origin espelha dados Git, mas não todos os recursos do GitHub:

O GitHub Actions continua rodando no GitHub. Integrações com Depot e Buildkite se aplicam a repositórios hospedados no Origin, não a cópias espelhadas.

Quando o GitHub permanece como fonte de verdade

Enquanto um repositório estiver espelhado, pushes feitos pelo Origin são repassados ao GitHub. Detach from GitHub, na área de Settings do repositório, torna a cópia do Origin independente sem alterar o repositório no GitHub.

Como abrir e revisar um pull request no Cursor Origin

Os pull requests do Origin usam a mesma sequência de criar branch, fazer push e revisar encontrada em outros hosts Git. Nosso guia de como funcionam os pull requests explica essa sequência.

Criando uma branch e fazendo uma alteração

Crie e faça push da branch de trabalho:

git checkout -b my-change
echo "Example change" >> README.md
git add README.md
git commit -m "Add example change"
git push -u origin my-change

O Git fez a sua parte; o próximo comando é do Origin.

Abrindo um pull request com a CLI do Origin

Comandos de repositório inferem o alvo a partir do remoto Git chamado origin. Execute origin pr create ou passe -R owner/repo para definir o repositório diretamente. O comando cria um rascunho por padrão; passe --status open para abrir um PR pronto para revisão.

Revisando um pull request no Cursor Origin

A CLI inclui origin pr list, origin pr view, origin pr diff e origin pr checks. Sem app de CI configurado, origin pr checks imprimiu No checks reported. e saiu com código 1 no meu teste.

Esse código de saída importa em scripts shell que usam set -e, pois uma aba Checks vazia pode interromper o script mesmo que o pull request esteja ok.

Revisão de pull request com quatro abas. Imagem do autor.

Na visualização web, todo pull request tem quatro abas: Activity, Commits, Checks e Files Changed, além de solicitações de reviewers, comentários em linha e um botão de merge. A página web exibe conflitos de merge, e origin pr status --conflict-status os reporta no terminal.

O terminal também suporta origin pr merge. Pull requests criados em um repositório hospedado no Origin ficam no Origin, enquanto a atividade em um repositório espelhado é enviada de volta ao GitHub.

Acesso de equipe e permissões de repositório no Cursor Origin

As permissões do Origin existem nos níveis de codebase e de repositório.

Configurações da codebase vs. configurações do repositório

As configurações da codebase são de toda a equipe: quem pode ativar o Origin, criar repositórios e instalar apps. As configurações do repositório valem para um único repositório e cobrem General, Permissions, Rules and Protections e Apps, embora a documentação do Cursor alerte que as telas de Permissions e Rules estão sendo redesenhadas.

Se alguém da equipe consegue usar o Origin, mas não consegue abrir um repositório específico, verifique as permissões desse repositório em vez das configurações da equipe.

Repositórios Internal vs. Private

Existem dois tipos de repositórios com acesso restrito:

• Internal repositories ficam visíveis para membros da equipe com acesso à codebase. 
• Private repositories ficam visíveis apenas para membros com acesso concedido diretamente ou via permissões da codebase. Ao alternar um repositório para private, quem fez a mudança permanece como admin.

Como verificar o acesso a um repositório no Cursor Origin

O comando origin repo list mostra todos os repositórios visíveis para a conta atual. Para revisar quem pode acessar um repositório, abra Settings e depois Permissions.

Boas práticas no Cursor Origin

Três pontos são muito importantes ao trabalhar com o Origin:

• Antes de deletar ou reconfigurar um repositório, confirme o valor completo de owner/repo e inspecione seus remotos. 

• Evite -y até verificar o alvo. 

• As páginas de permissões do Cursor entram em conflito, então confira a documentação atual antes de automatizar mudanças de acesso.

Cursor Origin vs. GitHub: comparação de recursos

O Origin é ligado ao fluxo de trabalho de agentes do Cursor, enquanto o GitHub cobre um ecossistema de repositórios mais amplo.

Hospedagem Git, pull requests e CI/CD

Em vez de repetir cada seção, aqui vai a versão curta da divisão de recursos:

A linha sobre agentes é a que precisa de contexto.

Cursor Origin vs. GitHub para fluxos com agentes

Ambas as plataformas permitem que agentes trabalhem contra repositórios. O Origin mantém esse loop dentro do Cursor; o GitHub oferece isso pelo painel Agents e ferramentas do Copilot, incluindo a CLI com disponibilidade geral.

Quando usar Cursor Origin, GitHub ou ambos

• Use o Origin quando o repositório for internal ou private, a maior parte do trabalho com agentes já acontecer no Cursor e seu deploy ou CI puder rodar com Vercel, Depot ou Buildkite.
• Mantenha o GitHub como host principal quando o projeto for público, Issues e Actions fizerem parte do dia a dia ou a equipe depender do marketplace de apps do GitHub.
• Use os dois quando quiser a navegação de código e o fluxo de agentes do Origin sem mover o repositório-fonte. Um espelho mantém pushes e atividade de pull requests vinculados ao GitHub enquanto disponibiliza o mesmo código no Origin.

Considerações finais

Saí de uma instalação nova do WSL até abrir um pull request no Origin usando o mesmo fluxo de branch, commit e push que uso no GitHub. A CLI não mudou como o Git funciona; as diferenças do Origin apareceram na hospedagem, permissões e espelhamento.

Depois de usar, eu trataria o Origin como um complemento do GitHub, não um substituto completo. O espelhamento é a porta de entrada mais prática para um repositório existente porque o GitHub pode continuar como autoridade. Projetos públicos e fluxos com muito uso de Actions ainda têm pouca razão para migrar.

Para se aprofundar, nosso guia de Cursor Automations cobre tarefas de agentes que rodam contra um repositório existente. Nosso guia sobre o que é GitHub e como usar explica o fluxo do GitHub em mais detalhes.