Date: 2026-09-10

​
Instalar e configurar a Nova

Nesta lição, vais preparar o ambiente local, instalar a CLI e iniciar a Nova a partir de um projeto. Segue os passos no terminal que usas habitualmente.

​
Requisitos

A distribuição npm da Nova requer:
  • Node.js 22.12.0 ou posterior.
  • npm.
  • Uma conta Compass ou credenciais de um fornecedor de modelos suportado.
  • Um terminal com acesso ao projeto que queres que a Nova analise.
No Windows, o PowerShell é uma escolha nativa. No macOS ou Linux, usa o terminal do sistema ou outra shell compatível. Confirma o runtime local antes de instalares:

​
Instalar a CLI

Instala globalmente o pacote npm oficial:
O pacote regista os nomes executáveis nova e compass. A documentação e os exemplos deste curso usam nova. Confirma o executável:

​
Executar a configuração inicial

Inicia o fluxo de configuração guiado:
O comando de configuração estabelece a autenticação, o consentimento, o acesso a fornecedores e as preferências locais. A Nova pode usar modelos geridos pela Compass, credenciais de fornecedores suportados, fluxos OAuth quando implementados ou pontos de acesso de modelos personalizados registados através de nova models. Não coloques chaves de API em ficheiros do projeto, prompts, NOVA.md, configuração controlada por Git ou histórico da shell. Usa o fluxo de configuração seguro e os mecanismos de armazenamento de credenciais suportados.

​
Iniciar a Nova num projeto

Muda primeiro para o diretório do repositório ou projeto e depois inicia a Nova:
O diretório de início é importante porque estabelece a raiz do projeto da Nova e determina que instruções de projeto, configuração, comandos, competências, memória, sessões e ficheiros do repositório são relevantes. Para um projeto novo, a Nova pode inicializar a configuração Compass local ao projeto:
A configuração do projeto fica em ./.compass; o estado global do utilizador fica em ~/.compass, conforme resolvido pelo sistema operativo.

​
Precedência da configuração

A Nova resolve a configuração normal da prioridade mais baixa para a mais alta:
  1. Valores predefinidos internos.
  2. Configuração global em ~/.compass/config.json.
  3. Configuração do projeto em ./.compass/config.json.
  4. Variáveis de ambiente.
  5. Opções de linha de comandos.
Isto permite uma base comum, substituições específicas do projeto e escolhas temporárias por invocação.

​
Utilização não interativa

Para scripts pontuais ou leituras ao estilo de CI, usa o modo de impressão:
Para trabalho de engenharia normal, a sessão interativa é preferível porque suporta perguntas de seguimento, aprovações, comandos com barra, estado de plano e progresso das ferramentas visível. A Nova também disponibiliza nova tools-rpc --stdio para clientes de automatização que precisem de acesso a ferramentas JSON-RPC. É uma superfície de integração, não o fluxo interativo habitual.

​
Verificações de estado e reparação

Se a configuração ou o comportamento em execução falhar, começa por:
Usa novamente nova setup para reconfigurar a autenticação ou o acesso ao fornecedor. nova update procura e instala atualizações disponíveis. Ativa a saída de depuração apenas quando necessário e analisa-a antes de a partilhares, porque os registos podem conter metadados sensíveis do projeto.

​
Atualizar ou remover a Nova

Atualiza através da Nova ou do npm:
Remove o pacote com:
O fluxo de desinstalação da Nova pode preservar ou remover dados de utilizador em ~/.compass. Esse local pode conter configuração, credenciais cifradas, sessões, memória, comandos, agentes, competências, dados de utilização e caches; não o elimines sem avaliar o impacto.

​
Recapitulação

  • Confirma Node.js e npm antes de instalares a CLI.
  • Executa nova setup para configurar a autenticação sem expor credenciais.
  • Inicia a Nova na raiz do projeto que queres analisar.

​
Prática segura

Num diretório de teste ou numa cópia local de um projeto, confirma a instalação e pede ajuda sem alterar ficheiros:
Não uses este exercício se o índice tiver alterações sensíveis. Verifica primeiro com git status. Anterior: Como funciona a Nova · Seguinte: A tua primeira sessão com a Nova