Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

Instalar o Aggrega

O Aggrega precisa de duas coisas: o binário aggrega instalado e, para escrever com um assistente de IA, o cliente do assistente ligado ao servidor MCP que o binário inclui. Os comandos vêm primeiro; o que cada um faz, e as outras formas de instalar, vêm a seguir.

Instalar o binário

No Linux e no macOS, num terminal:

Terminal window
curl -fsSL https://aggrega.ai/install.sh | sh

No Windows, no PowerShell:

Terminal window
irm https://aggrega.ai/install.ps1 | iex

Com o Homebrew, no macOS e no Linux:

Terminal window
brew install aggrega-ai/tap/aggrega

Com o Scoop, no Windows:

Terminal window
scoop bucket add aggrega https://github.com/aggrega-ai/scoop-bucket
scoop install aggrega

Com o winget, no Windows:

Terminal window
winget install Cognitio.Aggrega

Em seguida, confirme que é executado:

Terminal window
aggrega version

Uma cadeia de versão significa que o binário é encontrado e pode ser executado. É tudo aquilo de que o servidor MCP precisa. Cada forma de instalar, em pormenor explica o que cada comando faz, onde coloca o binário e como instalar com o instalador do Windows ou manualmente.

Ligar um cliente MCP

O cliente do assistente de IA inicia o servidor MCP do Aggrega executando aggrega mcp, e Ligar o servidor MCP indica o comando ou a entrada que o acrescenta, cliente a cliente. Num assistente que instala plugins, o plugin do Aggrega adiciona o servidor e a skill do Aggrega num único passo: consulte Instalar o plugin.

Cada forma de instalar, em pormenor

O Aggrega é distribuído como um único executável. Um único comando instala-o; os passos manuais que se seguem fazem o mesmo à mão. Ambos o colocam numa pasta própria do utilizador, sempre a mesma, e nenhum precisa de direitos de administrador: ~/.local/bin/aggrega no Linux e no macOS, e %LOCALAPPDATA%\Programs\aggrega\aggrega.exe no Windows. No Windows, o instalador do Windows e o winget instalam-no nessa mesma pasta, também sem direitos de administrador, e incluem-no entre as aplicações instaladas: ver Instalar com o instalador do Windows e Instalar com o winget. O Homebrew, no macOS e no Linux, e o Scoop, no Windows, também o instalam, cada um nas suas próprias pastas: ver Instalar com um gestor de pacotes.

Instalar com um único comando

O comando de instalação é curl -fsSL https://aggrega.ai/install.sh | sh no Linux e no macOS e irm https://aggrega.ai/install.ps1 | iex no PowerShell no Windows, os dois primeiros comandos de Instalar o binário. Esses dois endereços redirecionam para os scripts de instalação que a versão mais recente anexa, pelo que os mesmos comandos também funcionam com os endereços da própria versão:

Terminal window
curl -fsSL https://github.com/aggrega-ai/aggrega-cli/releases/latest/download/install.sh | sh
Terminal window
irm https://github.com/aggrega-ai/aggrega-cli/releases/latest/download/install.ps1 | iex

O que o comando faz:

  • Escolhe o binário predefinido para a máquina a partir da versão mais recente: Linux e macOS em x86 de 64 bits ou ARM de 64 bits, Windows em x86 de 64 bits. Recusa qualquer outro sistema ou processador com uma mensagem que indica o que encontrou ou a que recorrer em alternativa. Num Mac com Apple silicon, escolhe o binário Apple silicon, mesmo a partir de uma shell executada através do Rosetta 2.
  • Verifica o binário em relação ao SHA256SUMS da versão antes de instalar o que quer que seja. Uma transferência cujo digest SHA-256 difira do indicado na lista é eliminada, nada é instalado e o comando para com uma mensagem que indica os dois digests.
  • Instala o binário apenas para o utilizador, como ~/.local/bin/aggrega no Linux e no macOS e como %LOCALAPPDATA%\Programs\aggrega\aggrega.exe no Windows, criando a pasta quando não existe e substituindo num único passo uma cópia anterior que lá esteja, de modo que executar o comando de novo atualiza a existente. Nunca usa sudo. No Windows, remove também a marca que um ficheiro transferido da internet pode ter, como faz Unblock-File nos passos manuais. No macOS, transfere com curl, pelo que o binário que instala não tem marca de quarentena (ver O binário pré-compilado para macOS).
  • Torna o comando acessível. No Linux e no macOS, quando a pasta não está no PATH, imprime um comando que acrescenta a pasta ao ficheiro que a shell lê ao iniciar: ~/.zshrc para zsh, ~/.bashrc para bash (~/.bash_profile no macOS), ~/.config/fish/config.fish para fish, com uma linha fish_add_path, e ~/.profile para qualquer outra shell. Não executa esse comando por si: execute-o e abra um novo terminal. No Windows, acrescenta a pasta ao PATH do utilizador quando não está lá, e ao PATH da janela do PowerShell em que é executado, de modo que aggrega funciona nessa janela e em todos os terminais abertos depois, e indica que acrescentou a pasta.
  • Verifica que o binário instalado é executado, e para com uma mensagem antes de configurar qualquer outra coisa quando não é. Acrescenta uma nota quando outro aggrega surge no PATH antes daquele que instalou.
  • Imprime a versão instalada, ao executar o binário que instalou pelo caminho completo, para que a versão apareça mesmo antes de o seu PATH incluir a pasta.
  • Termina com os próximos passos, sob Next:, uma linha para cada um: o comando que executa o quickstart de IA, como descreve Primeiros passos; aggrega skills install --global, que acrescenta a skill do Aggrega aos assistentes de IA da máquina, como descreve Acrescentar a skill do assistente durante a instalação; e o endereço desta página, para o preenchimento automático da shell e Ligar um cliente MCP acima. Quando uma opção já instalou a skill, a respetiva linha é omitida.

O que imprime é breve: a versão e o sistema para o qual instala, uma linha assim que a transferência corresponde à sua soma de verificação, e o caminho onde instalou. Primeiros passos mostra uma execução completa. --verbose, indicado depois de sh -s -- tal como as opções abaixo, imprime também o endereço da lista de somas de verificação, o nome do ficheiro da release e o endereço de onde o transfere; install.ps1 tem o mesmo parâmetro como -Verbose, para uma execução do script com argumentos, que irm … | iex não lhe consegue dar. Quando o comando recusa ou um passo falha, indica-o numa linha, na saída de erro padrão a partir de install.sh e como o erro ou aviso que o PowerShell mostra a partir de install.ps1:

aggrega install: error: <what went wrong> - <what to do>

install.sh, o script para Linux e macOS, precisa de curl ou wget, uname, e sha256sum ou shasum. install.ps1, o do Windows, corre no Windows PowerShell 5.1 e no PowerShell 7.

Duas definições alteram o que instala, cada uma lida a partir do ambiente em que o script corre:

  • AGGREGA_VERSION indica a versão a instalar, como 0.8.7, escrita com ou sem o v inicial. Se não estiver definida, o comando instala a versão mais recente — a que o GitHub marca como mais recente, que nunca é uma pré-versão, pelo que uma pré-versão só é instalada indicando-a aqui.
  • AGGREGA_INSTALL_DIR indica a pasta onde instalar em vez da predefinida. O binário aí é aggrega, aggrega.exe no Windows, e o comando torna essa pasta acessível como acima.

No Linux e no macOS, coloque a definição antes de sh, e não antes de curl, para que o script a receba:

Terminal window
curl -fsSL https://aggrega.ai/install.sh | AGGREGA_VERSION=<version> sh

No PowerShell, defina-a primeiro na janela; mantém-se definida aí até ser removida com Remove-Item Env:AGGREGA_VERSION:

Terminal window
$env:AGGREGA_VERSION = "<version>"
irm https://aggrega.ai/install.ps1 | iex

Configurar o preenchimento automático da shell durante a instalação

Com --completion, install.sh também configura o preenchimento automático da shell, para que a tecla Tab complete os comandos e as flags de aggrega. As opções vão depois de sh -s --, que as passa ao script que sh lê do pipe:

Terminal window
curl -fsSL https://aggrega.ai/install.sh | sh -s -- --completion

irm … | iex não passa nenhuma opção a um script. No PowerShell, configure o preenchimento automático depois de concluída a instalação, com o script que aggrega completion powershell escreve, como descreve Preenchimento automático da shell. install.ps1 também aceita -Completion, para uma execução do script com argumentos.

Configura o preenchimento automático apenas para o utilizador atual, sem direitos de administrador, para a shell indicada pela definição SHELL, ou, no PowerShell, para o PowerShell em que é executado. Usa o script que o próprio aggrega completion do binário instalado escreve, e indica cada ficheiro que escreve ou altera:

  • bash: escreve o script em ~/.local/share/bash-completion/completions, a pasta a partir da qual o pacote bash-completion lê os preenchimentos do próprio utilizador. O preenchimento automático do bash para aggrega precisa desse pacote.
  • zsh: escreve _aggrega em ~/.local/share/zsh/site-functions e acrescenta a ~/.zshrc três linhas que colocam essa pasta no caminho de funções do zsh e o carregam, executando compinit onde nada no ficheiro o executou antes.
  • fish: escreve aggrega.fish em ~/.config/fish/completions, que o fish lê por si.
  • PowerShell: escreve o script como %LOCALAPPDATA%\aggrega\completion.ps1 e acrescenta ao perfil, para todos os anfitriões do PowerShell em que é executado, $PROFILE.CurrentUserAllHosts, duas linhas que o carregam. O Windows PowerShell e o PowerShell 7 mantêm perfis separados, pelo que deve executá-lo a partir de cada um que utilize. Um perfil só é executado onde a política de execução que uma nova janela assume é RemoteSigned, Unrestricted ou Bypass; com qualquer outra, como Restricted, não escreve nada e indica que política encontrou. Nunca altera a política.

XDG_DATA_HOME, XDG_CONFIG_HOME, BASH_COMPLETION_USER_DIR e ZDOTDIR mudam essas pastas e ficheiros de lugar tal como cada shell os lê. Um novo terminal ou janela carrega o preenchimento automático. Executar o comando novamente só reescreve um script quando o aggrega instalado escreve um diferente, e acrescenta as linhas a ~/.zshrc ou ao perfil uma única vez; é também assim que se acrescenta o preenchimento automático a uma instalação já existente, uma vez que o comando volta a instalar o binário pelo caminho.

Acrescentar a skill do assistente durante a instalação

Com --skills (-Skills no PowerShell), o comando de instalação também instala a skill do Aggrega — as instruções que ensinam um assistente de IA a instalar e usar o Aggrega — em todos os projetos do utilizador, para os assistentes de IA da máquina. As duas opções podem ser indicadas em conjunto:

Terminal window
curl -fsSL https://aggrega.ai/install.sh | sh -s -- --completion --skills

No PowerShell, onde irm … | iex não passa nenhuma opção, execute aggrega skills install --global depois de concluída a instalação: é o comando que -Skills executa.

Executa o próprio aggrega skills install --global do binário instalado, que procura os assistentes na máquina — cada um cuja pasta de configuração está no diretório pessoal, ou cujo comando está no PATH — e imprime cada um que encontrou e o que o encontrou. Depois:

  • Num terminal, pergunta primeiro. Prima Enter para instalar a skill para os assistentes encontrados, ou escreva os identificadores de outros para os acrescentar, separados por espaços ou vírgulas; aggrega skills list imprime os identificadores. Com curl … | sh, o script lê-se a si próprio a partir do pipe, pelo que pergunta através do terminal.
  • Sem um terminal através do qual perguntar, como num script, instala para os assistentes que encontrou.
  • Para escolher os assistentes, indique-os depois da opção, separados por vírgulas: --skills claude-code,cursor, ou --skills=claude-code,cursor, e no PowerShell -Skills claude-code,cursor. Instala então para esses e não procura outros.

Imprime cada pasta de skill que escreve, como ~/.claude/skills/aggrega para o Claude Code, todas dentro do diretório pessoal. Executar o comando novamente substitui as cópias que uma execução anterior escreveu, e é assim que a skill acompanha o binário até uma versão mais recente. aggrega skills descreve o comando, a pasta que cada assistente lê e o que encontra cada um.

Quando um passo não pode ser realizado

Quando o preenchimento automático não pode ser configurado — uma shell que não configura, como dash, uma pasta onde não consegue escrever, ou uma política de execução do PowerShell que não executa nenhum perfil — ou a skill não pode ser instalada — nenhum assistente encontrado e nenhum indicado, um identificador que não conhece, ou um ficheiro numa pasta de skill que nenhuma instalação escreveu —, o binário fica instalado na mesma e é executado. O comando indica por que razão o passo falhou, imprime os próximos passos e termina com um estado que indica qual passo falhou. Os estados são:

EstadoSignificado
0aggrega está instalado, e todos os passos que uma opção pediu foram concluídos com êxito
1nada foi instalado, ou o aggrega instalado não foi executado
2o comando recebeu uma opção que não aceita, ou uma lista que não indica nenhum assistente; não fez nada
3aggrega está instalado e é executado, mas a configuração do preenchimento automático da shell falhou
4aggrega está instalado e é executado, mas a instalação da skill falhou
5aggrega está instalado e é executado, mas ambos falharam

O script do PowerShell nunca fecha a janela em que é executado, pelo que deixa o estado em $LASTEXITCODE, e todos os estados diferentes de 0 terminam num erro, que powershell -Command e pwsh -Command comunicam como estado de saída 1.

Instalar com o instalador do Windows

Cada versão inclui um instalador do Windows, aggrega-<version>-windows-amd64-setup.exe, na página da versão em https://github.com/aggrega-ai/aggrega-cli/releases. Descarregue-o e execute-o. Instala o aggrega.exe predefinido apenas para o utilizador, sem direitos de administrador e sem os pedir, através de um breve assistente:

  • Uma página de boas-vindas, depois a licença, a Apache License 2.0 do Aggrega: nada é instalado até premir I Agree. Depois os componentes: o próprio Aggrega, sempre instalado, e Add to PATH, selecionado.
  • A pasta de instalação, %LOCALAPPDATA%\Programs\aggrega, salvo se escolher outra; é a pasta que o comando de instalação utiliza.
  • O progresso, depois uma página final que nomeia a pasta e indica se esta instalação a acrescentou ao PATH, com os passos seguintes: instalar a skill do Aggrega com aggrega skills install --global e ligar o cliente de IA como descreve Ligar um cliente MCP.

O que faz:

  • Com Add to PATH selecionado, acrescenta a pasta de instalação ao PATH do utilizador, a menos que já lá esteja. Um terminal aberto depois da instalação encontra aggrega; um já aberto mantém o PATH com que foi iniciado. Com a opção desmarcada, nada é acrescentado ao PATH, e um terminal executa aggrega.exe pelo caminho completo; uma entrada acrescentada por uma instalação anterior é deixada como está.
  • Inclui o Aggrega entre as aplicações instaladas, com a Cognitio s.r.l. como editora, pelo que se desinstala em Settings → Apps como qualquer outra aplicação. O desinstalador pede confirmação e depois remove os ficheiros que o instalador colocou na pasta, a entrada do PATH e a entrada nessa lista, e remove a pasta quando nada mais lá resta.
  • Executado de novo, instala por cima do que existe, propondo a pasta em que instalou da última vez, pelo que o instalador de uma versão posterior atualiza a cópia existente, mantendo uma única entrada no PATH.
  • Ao lado de aggrega.exe, a pasta contém uninstall.exe, LICENSE com o texto da licença e EnVar.dll, o componente com que o instalador e o desinstalador editam o PATH.

Quando aggrega.exe está em execução — iniciado por um editor ou por um cliente de IA — o instalador não o consegue substituir e para com uma mensagem que o indica; feche o que o iniciou e execute de novo o instalador. O desinstalador para da mesma forma, antes de ter removido o que quer que seja.

Para instalar sem janelas, a partir de um script ou de uma ferramenta que instala software em muitas máquinas, execute o instalador com /S, escrito em maiúscula; instala então sem janela nem perguntas, na pasta que uma instalação anterior utilizou ou, caso contrário, na predefinida, com Add to PATH, e comunica uma falha através do código de saída, que não é 0. O desinstalador aceita a mesma opção:

Terminal window
.\aggrega-<version>-windows-amd64-setup.exe /S
& "$env:LOCALAPPDATA\Programs\aggrega\uninstall.exe" /S

O instalador é assinado tal como os executáveis, com a editora Cognitio S.r.l. e um carimbo temporal: as verificações em O binário pré-compilado para Windows aplicam-se-lhe como a aggrega.exe, tal como o que aí se diz sobre os avisos que o Windows pode mostrar para um ficheiro transferido. SHA256SUMS lista o seu digest como faz com todos os outros ficheiros da versão.

Onde o instalador não for adequado, o comando de instalação acima e os passos manuais instalam o mesmo aggrega.exe na mesma pasta.

Instalar com um gestor de pacotes

Cada versão atualiza também uma fórmula do Homebrew e um manifesto do Scoop, para que o gestor de pacotes já utilizado possa instalar o Aggrega e mantê-lo atualizado. Cada um instala o mesmo binário predefinido que o comando de instalação, verificado em relação ao digest SHA-256 que o SHA256SUMS da versão lhe atribui.

No macOS e no Linux, brew install aggrega-ai/tap/aggrega instala-o com o Homebrew. O Homebrew acrescenta o tap aggrega-ai/tap na primeira vez e instala o binário para o sistema e o processador: macOS em Apple silicon ou em Intel, Linux em x86 de 64 bits ou em ARM de 64 bits. Depois de uma nova versão, brew upgrade atualiza-o, juntamente com todas as outras fórmulas instaladas.

No Windows, com o Scoop, acrescente uma vez o bucket do Aggrega, com scoop bucket add aggrega https://github.com/aggrega-ai/scoop-bucket, e instale a partir dele com scoop install aggrega. O Scoop instala o binário do Windows como aggrega.exe e torna-o acessível como aggrega através da pasta de shims que mantém no PATH. Depois de uma nova versão, scoop update atualiza os buckets e scoop update aggrega atualiza-o.

O Homebrew e o Scoop instalam cada um nas suas próprias pastas em vez de em ~/.local/bin ou %LOCALAPPDATA%\Programs\aggrega, e atualizam apenas a cópia que instalaram. Use uma única forma de instalação numa máquina: uma cópia instalada pelo comando de instalação ou à mão e outra instalada pelo Homebrew ou pelo Scoop são duas cópias, e a pasta que surge primeiro no PATH decide qual é executada.

Instalar com o winget

No Windows, winget install Cognitio.Aggrega instala-o com o winget, o Gestor de Pacotes do Windows. O winget descarrega o instalador do Windows da versão a partir da página da versão, verifica-o em relação ao digest SHA-256 indicado no manifesto do pacote e executa-o sem intervenção. O resultado é o do próprio instalador: aggrega.exe em %LOCALAPPDATA%\Programs\aggrega, ou na pasta que uma instalação anterior utilizou, essa pasta no PATH do utilizador e o Aggrega na lista de aplicações instaladas, tudo sem direitos de administrador. O winget não altera o PATH do terminal em que é executado, pelo que deve abrir um novo terminal antes de executar aggrega version.

winget upgrade Cognitio.Aggrega instala uma versão posterior por cima, e winget uninstall Cognitio.Aggrega executa o seu desinstalador. O winget, o instalador e o comando de instalação instalam todos na mesma pasta, salvo se escolher outra no instalador, pelo que o último a ser executado coloca lá o seu aggrega.exe.

Instalar à mão

Cada versão inclui binários pré-compilados para Linux em x86 de 64 bits e em ARM de 64 bits, para Windows em x86 de 64 bits e para macOS em Apple silicon e em Intel, na página da versão em https://github.com/aggrega-ai/aggrega-cli/releases. Descarregue o executável para o seu sistema operativo e processador — Escolher o ficheiro, mais abaixo, indica cada um — e verifique-o em relação ao SHA256SUMS da versão, como aí descrito. Depois marque-o como executável e mova-o para ~/.local/bin/aggrega. No Linux, a partir do diretório onde está a transferência, com <version> substituído pela versão descarregada, e amd64 por arm64 em ARM de 64 bits:

Terminal window
chmod +x aggrega-<version>-linux-amd64
mkdir -p ~/.local/bin
mv aggrega-<version>-linux-amd64 ~/.local/bin/aggrega

No Windows, ver O binário pré-compilado para Windows abaixo; no macOS, ver O binário pré-compilado para macOS.

Quando ~/.local/bin não está no PATH, acrescente esta linha ao ficheiro que a shell lê ao arrancar — ~/.zshrc para zsh, ~/.bashrc para bash (~/.bash_profile no macOS) — e abra um novo terminal:

Terminal window
export PATH="$HOME/.local/bin:$PATH"

A partir do código-fonte, com uma toolchain Go instalada, compile o comando aggrega a partir da árvore de código-fonte e coloque o binário resultante na mesma pasta.

Confirme a instalação com aggrega version, como no final de Instalar o binário.

Escolher o ficheiro

Uma versão dá a cada executável o nome aggrega-<version>-<system>-<processor>, com .exe no Windows:

SistemaProcessadorFicheiro
Linuxx86 de 64 bits (uname -m imprime x86_64)aggrega-<version>-linux-amd64
LinuxARM de 64 bits (uname -m imprime aarch64)aggrega-<version>-linux-arm64
Windowsx86 de 64 bitsaggrega-<version>-windows-amd64.exe
macOSApple siliconaggrega-<version>-darwin-arm64
macOSIntelaggrega-<version>-darwin-amd64

Esse ficheiro é o que o comando de instalação instala, e o que se descarrega à mão. Duas variantes dele encontram-se ao lado; o comando de instalação não instala nenhuma delas, e cada uma instala-se à mão da mesma forma:

  • aggrega-debug-<version>-… é o mesmo programa com as suas informações de depuração, que um depurador ou um profiler lê. Corre e indica a sua versão exatamente como o ficheiro predefinido, e é maior.
  • aggrega-light-<version>-… é compilado sem os plugins incorporados: resolve cada plugin através da cascata de plugins, tal como o espaço de trabalho a configura, em vez de encontrar os principais dentro de si próprio.

Para Windows, a versão inclui também aggrega-<version>-windows-amd64-setup.exe, o instalador do Windows, que instala o ficheiro predefinido.

Cada versão inclui também SHA256SUMS, o digest SHA-256 de todos os outros ficheiros que anexa, incluindo os dois scripts de instalação, na forma que sha256sum lê. O comando de instalação faz ele próprio esta verificação. Para verificar uma transferência à mão no Linux, com SHA256SUMS no mesmo diretório:

Terminal window
sha256sum --check --ignore-missing SHA256SUMS

O ficheiro descarregado é indicado como OK; qualquer outro resultado significa que não é o ficheiro que a versão publicou.

O binário pré-compilado para Windows

O executável para Windows é aggrega-<version>-windows-amd64.exe (as variantes debug e light que o acompanham na versão instalam-se da mesma forma). Mude-lhe o nome para aggrega.exe, mova-o para %LOCALAPPDATA%\Programs\aggrega, a pasta que o comando de instalação utiliza, e acrescente essa pasta ao PATH do utilizador: o Windows executa um ficheiro terminado em .exe sem ser preciso marcá-lo como executável, e encontra-o como o comando aggrega com esse nome. No PowerShell, por exemplo, com <version> substituído pela versão descarregada:

Terminal window
$dir = "$env:LOCALAPPDATA\Programs\aggrega"
New-Item -ItemType Directory -Force $dir | Out-Null
Move-Item ".\aggrega-<version>-windows-amd64.exe" "$dir\aggrega.exe"
Unblock-File "$dir\aggrega.exe"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$dir", "User")

Um terminal aberto depois disso encontra o aggrega; um que já esteja aberto mantém o PATH com que arrancou.

Os executáveis estão assinados. Cada um tem uma assinatura Authenticode, a assinatura de código que o Windows verifica, e o editor que o Windows mostra para ela é Cognitio S.r.l. Cada assinatura tem também um carimbo temporal: o certificado por trás de uma assinatura só é válido durante alguns dias, e é o carimbo temporal que mantém a assinatura válida depois de esse certificado expirar. Para verificar um ficheiro descarregado antes de o executar:

  • No Explorador de Ficheiros, abra as Properties do ficheiro e o separador Digital Signatures. A lista de assinaturas nomeia Cognitio S.r.l.; selecione-a e depois Details, que indica This digital signature is OK.

  • No PowerShell, com $dir como no exemplo acima:

    Terminal window
    $signature = Get-AuthenticodeSignature "$dir\aggrega.exe"
    $signature.Status
    $signature.SignerCertificate.Subject

    Status indica Valid, e o assunto começa por CN=Cognitio S.r.l.. NotSigned ou HashMismatch significa que o ficheiro não é o que a versão publicou, ou que foi alterado depois de ter sido assinado.

Uma assinatura nomeia o editor; não faz desaparecer todos os avisos. O aviso que surge depende de como o ficheiro chegou e de como é iniciado:

  • Durante a transferência, um browser pode avisar que o ficheiro não é transferido com frequência e perguntar se o deve manter. Mantê-lo guarda o ficheiro tal como foi transferido.
  • Ao iniciá-lo a partir do Explorador de Ficheiros ou do browser, o Windows pode mostrar Windows protected your PC. Esse aviso vem do Microsoft Defender SmartScreen, que pondera a reputação que um ficheiro e o seu editor construíram, pelo que uma versão acabada de lançar ainda o pode encontrar, mesmo assinada, até construir a sua própria reputação. Para um ficheiro assinado, o aviso nomeia o editor: selecione More info, verifique que nomeia Cognitio S.r.l. e o nome do ficheiro descarregado e, em seguida, selecione Run anyway. Iniciado a partir do PowerShell ou de uma linha de comandos, o mesmo ficheiro pode correr sem esse aviso; se assim é ou não depende da versão do Windows e das suas definições.
  • O Unblock-File responde antecipadamente a esse aviso. Um ficheiro descarregado é marcado como vindo da internet, e é a essa marca que a verificação Windows protected your PC responde. O Unblock-File no PowerShell, como no exemplo acima, remove a marca; o mesmo faz a caixa de verificação Unblock no separador General das Properties do ficheiro no Explorador de Ficheiros.
  • Quando o Smart App Control está ativado (Windows 11), verifica um programa quando este é iniciado. Segundo a descrição da Microsoft, o Smart App Control pergunta primeiro ao serviço de segurança na cloud da Microsoft se o programa é seguro; quando esse serviço não consegue fazer uma previsão fiável, verifica a assinatura, deixando correr um programa com uma assinatura válida e bloqueando um que não esteja assinado ou cuja assinatura seja inválida. Se está ativado é indicado em App & browser control na Segurança do Windows.

O binário pré-compilado para macOS

Os executáveis para macOS são aggrega-<version>-darwin-arm64, para um Mac com Apple silicon, e aggrega-<version>-darwin-amd64, para um Mac com processador Intel; About This Mac no menu Apple mostra qual se tem. As variantes debug e light que os acompanham na versão instalam-se da mesma forma. Um Mac com Apple silicon também executa o ficheiro Intel, através do Rosetta 2 onde estiver instalado, mas o ficheiro Apple silicon é o construído para ele.

Mude o nome do ficheiro para aggrega, marque-o como executável e mova-o para ~/.local/bin, a pasta que o comando de instalação utiliza. No Terminal, no diretório onde está a transferência, por exemplo, com <version> substituído pela versão descarregada, e arm64 por amd64 num Mac Intel:

Terminal window
chmod +x aggrega-<version>-darwin-arm64
mkdir -p ~/.local/bin
mv aggrega-<version>-darwin-arm64 ~/.local/bin/aggrega

O mkdir cria a pasta onde ainda não exista. ~/.local/bin não está no PATH que o macOS dá a um novo terminal, pelo que deve acrescentar a linha de Instalar à mão a ~/.zshrc, ou a ~/.bash_profile para bash, a menos que já lá esteja.

Os executáveis estão assinados e notarizados. Cada um tem uma assinatura de código feita com o Developer ID da Cognitio s.r.l. — o certificado que a Apple emite a um programador para software distribuído fora da Mac App Store — com o runtime reforçado e um carimbo temporal seguro, e o serviço de notarização da Apple verificou e notarizou cada um. O Gatekeeper, a verificação do macOS sobre software vindo da internet, avalia um programa que tenha a marca de quarentena, a marca que um browser acrescenta a um ficheiro que descarrega, e aceita um que a Apple tenha notarizado, pelo que um ficheiro descarregado da página da versão corre tal como está. Um ticket de notarização não pode ser anexado a um único ficheiro executável, pelo que o Gatekeeper encontra o ticket online na primeira vez que o ficheiro corre; num Mac que esteja offline nesse momento, o Gatekeeper pode bloquear o ficheiro até o Mac conseguir contactar a Apple.

Para verificar um ficheiro descarregado antes de o executar, no Terminal, com o nome do ficheiro descarregado:

Terminal window
codesign --verify --strict --verbose=2 aggrega-<version>-darwin-arm64
codesign --display --verbose=2 aggrega-<version>-darwin-arm64

O primeiro indica que o ficheiro é valid on disk e satisfies its Designated Requirement. O segundo lista as autoridades da assinatura, a primeira das quais Developer ID Application: COGNITIO SRL seguida do identificador da equipa entre parênteses, e um Timestamp. Um ficheiro que falhe qualquer um dos dois não é o que a versão publicou, ou foi alterado depois de assinado.

Um ficheiro obtido com curl não tem marca de quarentena, pelo que o Gatekeeper não o avalia de todo: o curl não acrescenta a marca que um browser acrescenta. É também por isso que o binário que o comando de instalação coloca no lugar corre sem essa avaliação.