Como Instalar a CLI do Gemini no Ubuntu: Tutorial Completo Passo a Passo

Pré-requisitos

Antes de iniciar a instalação do Gemini CLI no Ubuntu, prepare o seguinte:

• Versão do Ubuntu: 20.04 LTS ou mais recente (22.04, 24.04 e 26.04 são totalmente suportados).
• Acesso administrativo: Privilégios sudo para gerenciamento de pacotes.
• Conexão à internet: Necessária para baixar o Node.js, pacotes npm e autenticação. }- Conta do Google: Necessária para fazer login via OAuth e acessar os modelos Gemini.
• Hardware recomendado: Pelo menos 4 GB de RAM e 2 núcleos de CPU para desempenho suave durante sessões interativas.

Conhecimento básico presumido: Você sabe como abrir um terminal e executar comandos básicos do apt e bash.

Passo 1: Atualizar Pacotes do Sistema

Comece atualizando sua lista de pacotes e fazendo upgrade dos pacotes existentes para evitar conflitos de dependência:

sudo apt update && sudo apt upgrade -y

Este passo garante que você tenha as últimas atualizações de segurança e informações do repositório.

Passo 2: Instalar Node.js 20 ou Superior

O Gemini CLI requer Node.js versão 20 ou mais recente. Os repositórios padrão do Ubuntu geralmente incluem versões mais antigas (por exemplo, Node 18 no Ubuntu 24.04).

Método Recomendado: Repositório NodeSource

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Alternativa: Usando nvm (Node Version Manager)

Para um gerenciamento de versão mais fácil:

curl -o-, https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
nvm alias default 20

Verifique a instalação:

node --version
npm --version

Você deverá ver uma saída semelhante a v20.x.x para o Node.js e uma versão correspondente do npm.

Passo 3: Instalar Gemini CLI

Instalação Global (Recomendada para Uso Diário)

npm install -g @google/gemini-cli

Isso torna o comando gemini disponível em todo o sistema.

Teste Rápido Sem Instalação Permanente

Se quiser testar primeiro:

npx @google/gemini-cli

Instalação no Nível do Usuário (Evite Problemas de Permissão)

Se encontrar erros de permissão com a instalação global:

mkdir -p ~/.local/bin
npm config set prefix '~/.local'
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @google/gemini-cli

Passo 4: Verificar a Instalação

Verifique se o Gemini CLI foi instalado corretamente:

gemini --version

A saída esperada mostra a versão atual do Gemini CLI.

Passo 5: Iniciar e Autenticar

Execute a CLI pela primeira vez:

gemini

A ferramenta solicitará que você faça login com o Google. Uma janela do navegador será aberta automaticamente. Complete o fluxo OAuth e retorne ao terminal.

Após a autenticação bem-sucedida, a interface interativa do Gemini CLI será carregada. Use /help para ver os comandos disponíveis.

Melhor prática: Navegue até o diretório do seu projeto antes de iniciar:

cd ~/my-project
gemini

Problemas Comuns & Solução de Problemas

• 'gemini: command not found': Reinicie seu terminal ou execute source ~/.bashrc. Verifique seu PATH com echo $PATH.

• Permissão negada durante npm install: Use o método de instalação no nível do usuário mencionado acima, em vez de sudo npm.

• Erro de versão do Node.js: Execute novamente a configuração do NodeSource ou alterne as versões com nvm. Confirme com node --version.

• Falha de autenticação: Desative bloqueadores de pop-up do navegador, certifique-se de que os cookies estão habilitados e tente novamente. Limpe o cache do npm, se necessário: npm cache clean --force.

• Tempo limite de rede ou erros de download (ex., ripgrep prebuilt): Certifique-se de que a internet está estável. Tente novamente a instalação ou use npx como uma solução alternativa.

• Ferramentas de compilação ausentes: Instale as dependências de desenvolvimento:

sudo apt install -y build-essential python3

• Problemas específicos do WSL: Execute comandos em um terminal padrão do Ubuntu em vez do WSL se erros de compilação ocorrerem.

Para mais ajuda, consulte o repositório oficial do GitHub: https://github.com/google-gemini/gemini-cli.

Próximos Passos

• Explore os comandos principais: Digite /help, /model ou /settings dentro do CLI.
• Use em projetos: Peça ao Gemini para explicar código, refatorar funções ou gerar novos arquivos com prompts em linguagem natural.
• Personalize: Edite os arquivos de configuração em ~/.config/gemini-cli/ para temas, modelos padrão e extensões.
• Atualize regularmente: Execute npm update -g @google/gemini-cli para obter as últimas melhorias.
• Integre ferramentas: Experimente as extensões integradas e servidores MCP para fluxos de trabalho agenticos avançados, como integração com git.

Agora você está pronto para usar o Gemini CLI como um poderoso assistente de codificação com IA diretamente no seu terminal Ubuntu. Comece com prompts simples em uma pasta de projeto e gradualmente construa tarefas agenticas mais complexas.

Feliz codificação com o Gemini!