Install Aggrega
Aggrega needs two things: the aggrega binary installed, and, to author with an AI assistant, your assistant’s client connected to the MCP server the binary carries. The commands come first; what each one does, and the other ways to install, follow them.
Install the binary
On Linux and macOS, in a terminal:
curl -fsSL https://aggrega.ai/install.sh | shOn Windows, in PowerShell:
irm https://aggrega.ai/install.ps1 | iexWith Homebrew, on macOS and Linux:
brew install aggrega-ai/tap/aggregaWith Scoop, on Windows:
scoop bucket add aggrega https://github.com/aggrega-ai/scoop-bucketscoop install aggregaWith winget, on Windows:
winget install Cognitio.AggregaThen check that it runs:
aggrega versionA version string means the binary is found and runnable. That is everything the MCP server needs. Each way to install, in detail says what each command does, where it puts the binary, and how to install with the Windows installer or by hand.
Connect an MCP client
Your AI assistant’s client starts Aggrega’s MCP server by running aggrega mcp, and Connect the MCP server gives the command or the entry that adds it, client by client. In an assistant that installs plugins, the Aggrega plugin adds the server and the Aggrega skill in one step: see Install the plugin.
Each way to install, in detail
Aggrega ships as a single executable. One command installs it; the manual steps after it do the same by hand. Both put it in one folder of your own, the same one each time, and neither needs administrator rights: ~/.local/bin/aggrega on Linux and macOS, and %LOCALAPPDATA%\Programs\aggrega\aggrega.exe on Windows. On Windows, the Windows installer and winget install it into that same folder, also without administrator rights, and list it among your installed apps: see Install with the Windows installer and Install with winget. Homebrew, on macOS and Linux, and Scoop, on Windows, install it too, each into its own folders: see Install with a package manager.
Install with one command
The install command is curl -fsSL https://aggrega.ai/install.sh | sh on Linux and macOS and irm https://aggrega.ai/install.ps1 | iex in PowerShell on Windows, the first two commands of Install the binary. Those two addresses redirect to the install scripts the latest release attaches, so the same commands also run with the release’s own addresses:
curl -fsSL https://github.com/aggrega-ai/aggrega-cli/releases/latest/download/install.sh | shirm https://github.com/aggrega-ai/aggrega-cli/releases/latest/download/install.ps1 | iexWhat the command does:
- It picks the default binary for your machine from the latest release: Linux and macOS on 64-bit x86 or 64-bit ARM, Windows on 64-bit x86. It refuses any other system or processor with a message saying which it found or where to turn instead. On a Mac with Apple silicon it picks the Apple silicon binary, even from a shell running through Rosetta 2.
- It checks the binary against the release’s
SHA256SUMSbefore installing anything. A download whose SHA-256 digest differs from the one the list gives is deleted, nothing is installed, and the command stops with a message naming both digests. - It installs the binary for you alone, as
~/.local/bin/aggregaon Linux and macOS and as%LOCALAPPDATA%\Programs\aggrega\aggrega.exeon Windows, creating the folder when it is missing and replacing an earlier copy there in one step, so running the command again updates the one you have. It never usessudo. On Windows it also removes the mark a file downloaded from the internet can carry, asUnblock-Filedoes in the manual steps. On macOS it downloads withcurl, so the binary it installs carries no quarantine mark (see The macOS prebuilt binary). - It makes the command reachable. On Linux and macOS, when the folder is not on your
PATH, it prints a command that adds the folder to the file your shell reads when it starts:~/.zshrcfor zsh,~/.bashrcfor bash (~/.bash_profileon macOS),~/.config/fish/config.fishfor fish, with afish_add_pathline, and~/.profilefor any other shell. It does not run that command itself: run it and open a new terminal. On Windows it adds the folder to your userPATHwhen it is not there, and to thePATHof the PowerShell window it runs in, soaggregaruns in that window and in every terminal opened after it, and it says that it added the folder. - It checks that the installed binary runs, and stops with a message before anything else is set up when it does not. It adds a note when another
aggregacomes before the one it installed on yourPATH. - It prints the installed version, running the binary it installed by its full path, so the version shows before your
PATHreaches the folder. - It ends with the next steps, under
Next:, one line each: the command that runs the AI quickstart, as Getting started describes;aggrega skills install --global, which adds the Aggrega skill to the AI assistants on your machine, as Add the assistant skill as you install describes; and the address of this page, for shell completion and Connect an MCP client above. When an option has already installed the skill, its line is left out.
What it prints is short: the version and the system it installs for, a line once the download matches its checksum, and the path it installed. Getting started shows a whole run. --verbose, given after sh -s -- as the options below are, also prints the address of the checksum list, the name of the release file and the address it downloads it from; install.ps1 has the same switch as -Verbose, for a run of the script with arguments, which irm … | iex cannot give it. When the command refuses or a step fails, it says so in one line, on standard error from install.sh and as the error or warning PowerShell shows from install.ps1:
aggrega install: error: <what went wrong> - <what to do>install.sh, the Linux and macOS script, needs curl or wget, uname, and sha256sum or shasum. install.ps1, the Windows one, runs in Windows PowerShell 5.1 and in PowerShell 7.
Two settings change what it installs, each read from the environment the script runs in:
AGGREGA_VERSIONnames the release to install, such as0.8.7, written with or without its leadingv. Unset, the command installs the latest release — the one GitHub marks as latest, which is never a prerelease, so a prerelease is installed only by naming it here.AGGREGA_INSTALL_DIRnames the folder to install into in place of the default. The binary isaggregathere,aggrega.exeon Windows, and the command makes that folder reachable as above.
On Linux and macOS, put the setting before sh, not before curl, so that the script receives it:
curl -fsSL https://aggrega.ai/install.sh | AGGREGA_VERSION=<version> shIn PowerShell, set it in the window first; it stays set there until you remove it with Remove-Item Env:AGGREGA_VERSION:
$env:AGGREGA_VERSION = "<version>"irm https://aggrega.ai/install.ps1 | iexSet up shell completion as you install
With --completion, install.sh also sets up shell completion, so that the Tab key completes aggrega commands and flags. Options go after sh -s --, which hands them to the script sh reads from the pipe:
curl -fsSL https://aggrega.ai/install.sh | sh -s -- --completionirm … | iex passes no option to a script. In PowerShell, set completion up once the install is done, with the script aggrega completion powershell writes, as Shell completion describes. install.ps1 takes -Completion too, for a run of the script with arguments.
It sets completion up for you alone, without administrator rights, for the shell your SHELL setting names, or in PowerShell for the PowerShell it runs in. It uses the script the installed binary’s own aggrega completion writes, and names every file it writes or changes:
- bash: it writes the script into
~/.local/share/bash-completion/completions, the folder the bash-completion package reads your own completions from. Bash completion foraggreganeeds that package. - zsh: it writes
_aggregainto~/.local/share/zsh/site-functionsand adds three lines to~/.zshrcthat put that folder on zsh’s function path and load it, runningcompinitwhere nothing in the file ran it first. - fish: it writes
aggrega.fishinto~/.config/fish/completions, which fish reads on its own. - PowerShell: it writes the script as
%LOCALAPPDATA%\aggrega\completion.ps1and adds two lines that load it to your profile for every host of the PowerShell it runs in,$PROFILE.CurrentUserAllHosts. Windows PowerShell and PowerShell 7 keep separate profiles, so run it from each one you use. A profile runs only where the execution policy a new window takes isRemoteSigned,UnrestrictedorBypass; under any other, such asRestricted, it writes nothing and says which policy it found. It never changes the policy.
XDG_DATA_HOME, XDG_CONFIG_HOME, BASH_COMPLETION_USER_DIR and ZDOTDIR move those folders and files as each shell reads them. A new terminal or window loads the completion. Running the command again rewrites a script only when the installed aggrega writes a different one, and adds the lines to ~/.zshrc or the profile only once; that is also how to add completion to an install you already have, since the command installs the binary again on the way.
Add the assistant skill as you install
With --skills (-Skills in PowerShell), the install command also installs the Aggrega skill — the instructions that teach an AI assistant to install and use Aggrega — in every project of yours, for the AI assistants on your machine. Both options can be given together:
curl -fsSL https://aggrega.ai/install.sh | sh -s -- --completion --skillsIn PowerShell, where irm … | iex passes no option, run aggrega skills install --global once the install is done: it is the command -Skills runs.
It runs the installed binary’s own aggrega skills install --global, which looks for the assistants on your machine — each one whose configuration folder is in your home directory, or whose command is on your PATH — and prints each one it found and what found it. Then:
- At a terminal, it asks first. Press Enter to install the skill for the assistants it found, or type the identifiers of others to add them, separated by spaces or commas;
aggrega skills listprints the identifiers. Undercurl … | shthe script reads itself from the pipe, so it asks through your terminal instead. - With no terminal to ask through, as in a script, it installs for the assistants it found.
- To choose the assistants yourself, give them after the option, separated by commas:
--skills claude-code,cursor, or--skills=claude-code,cursor, and in PowerShell-Skills claude-code,cursor. It then installs for those and looks for no others.
It prints each skill folder it writes, such as ~/.claude/skills/aggrega for Claude Code, all of them beneath your home directory. Running the command again replaces the copies an earlier run wrote, which is how the skill follows the binary to a newer version. aggrega skills describes the command, the folder each assistant reads and what finds each one.
When a step cannot be done
When completion cannot be set up — a shell it does not set up, such as dash, a folder it cannot write, or a PowerShell execution policy that runs no profile — or the skill cannot be installed — no assistant found and none named, an identifier it does not know, or a file at a skill folder that an installation did not write — the binary is still installed and runs. The command says why the step failed, prints the next steps, and ends with a status saying which step failed. The statuses are:
| Status | Meaning |
|---|---|
0 | aggrega is installed, and every step an option asked for succeeded |
1 | nothing was installed, or the installed aggrega did not run |
2 | the command was given an option it does not take, or a list naming no assistant; it did nothing |
3 | aggrega is installed and runs, but setting up shell completion failed |
4 | aggrega is installed and runs, but installing the skill failed |
5 | aggrega is installed and runs, but both of those failed |
The PowerShell script never closes the window it runs in, so it leaves the status in $LASTEXITCODE, and every status but 0 ends in an error, which powershell -Command and pwsh -Command report as exit status 1.
Install with the Windows installer
Each release carries a Windows installer, aggrega-<version>-windows-amd64-setup.exe, on the release page at https://github.com/aggrega-ai/aggrega-cli/releases. Download it and run it. It installs the default aggrega.exe for you alone, without administrator rights and without asking for them, through a short wizard:
- A welcome page, then the license, Aggrega’s Apache License 2.0: nothing is installed until you press I Agree. Then the components: Aggrega itself, always installed, and Add to PATH, selected.
- The install folder,
%LOCALAPPDATA%\Programs\aggregaunless you choose another; it is the folder the install command uses. - The progress, then a finish page naming the folder and saying whether this install added it to your
PATH, with the next steps: installing the Aggrega skill withaggrega skills install --global, and connecting your AI client as Connect an MCP client describes.
What it does:
- With Add to PATH selected, it adds the install folder to your user
PATHunless it is there already. A terminal opened after the install findsaggrega; one already open keeps thePATHit started with. With it cleared, nothing is added to yourPATH, and a terminal runsaggrega.exeby its full path; an entry an earlier install added is left as it is. - It lists Aggrega among your installed apps, published by Cognitio s.r.l., so it is uninstalled from Settings → Apps like any other app. The uninstaller asks you to confirm, then removes the files the installer put in the folder, the
PATHentry and the entry in that list, and removes the folder when nothing else is left in it. - Run again, it installs over what is there, offering the folder it installed into last, so the installer of a later release updates the copy you have, keeping one entry on your
PATH. - Beside
aggrega.exe, the folder holdsuninstall.exe,LICENSEwith the license text, andEnVar.dll, the component the installer and the uninstaller edit yourPATHwith.
When aggrega.exe is running — started by an editor or an AI client — the installer cannot replace it, and stops with a message saying so; close what started it and run the installer again. The uninstaller stops the same way, before it has removed anything.
To install with no window, from a script or a tool that installs software on many machines, run the installer with /S, written in capitals; it then installs without a window or a question, into the folder an earlier install used or else the default one, with Add to PATH, and reports a failure through its exit code, which is not 0. The uninstaller takes the same switch:
.\aggrega-<version>-windows-amd64-setup.exe /S& "$env:LOCALAPPDATA\Programs\aggrega\uninstall.exe" /SThe installer is signed as the executables are, with the publisher Cognitio S.r.l. and a timestamp: the checks in The Windows prebuilt binary apply to it as they do to aggrega.exe, and so does what it says about the prompts Windows may show for a downloaded file. SHA256SUMS lists its digest as it does every other file of the release.
Where the installer does not suit, the install command above and the manual steps install the same aggrega.exe into the same folder.
Install with a package manager
Every release also updates a Homebrew formula and a Scoop manifest, so the package manager you already use can install Aggrega and keep it current. Each installs the same default binary the install command does, checked against the SHA-256 digest the release’s SHA256SUMS gives it.
On macOS and Linux, brew install aggrega-ai/tap/aggrega installs it with Homebrew. Homebrew adds the aggrega-ai/tap tap the first time and installs the binary for your system and processor: macOS on Apple silicon or on Intel, Linux on 64-bit x86 or on 64-bit ARM. After a new release, brew upgrade updates it, with every other formula you installed.
On Windows, with Scoop, add the Aggrega bucket once, with scoop bucket add aggrega https://github.com/aggrega-ai/scoop-bucket, and install from it with scoop install aggrega. Scoop installs the Windows binary as aggrega.exe and makes it reachable as aggrega through the folder of shims it keeps on your PATH. After a new release, scoop update refreshes the buckets and scoop update aggrega updates it.
Homebrew and Scoop each install into their own folders rather than into ~/.local/bin or %LOCALAPPDATA%\Programs\aggrega, and update only the copy they installed. Use one way of installing on a machine: a copy installed by the install command or by hand and another installed by Homebrew or Scoop are two copies, and whichever folder comes first on your PATH decides which one runs.
Install with winget
On Windows, winget install Cognitio.Aggrega installs it with winget, the Windows Package Manager. winget downloads the Windows installer of the release from its release page, checks it against the SHA-256 digest the package’s manifest gives, and runs it unattended. The result is the installer’s own: aggrega.exe in %LOCALAPPDATA%\Programs\aggrega, or in the folder an earlier install used, that folder on your user PATH, and Aggrega in your list of installed apps, all without administrator rights. winget does not change the PATH of the terminal it runs in, so open a new terminal before running aggrega version.
winget upgrade Cognitio.Aggrega installs a later release over it, and winget uninstall Cognitio.Aggrega runs its uninstaller. winget, the installer and the install command all install into the same folder unless you choose another one in the installer, so whichever runs last puts the aggrega.exe there.
Install it by hand
Each release carries prebuilt binaries for Linux on 64-bit x86 and on 64-bit ARM, for Windows on 64-bit x86, and for macOS on Apple silicon and on Intel, on the release page at https://github.com/aggrega-ai/aggrega-cli/releases. Download the executable for your operating system and processor — Choosing the file below names each — and check it against the release’s SHA256SUMS, as described there. Then mark it executable and move it to ~/.local/bin/aggrega. On Linux, from the directory the download is in, with <version> replaced by the version you downloaded, and amd64 by arm64 on 64-bit ARM:
chmod +x aggrega-<version>-linux-amd64mkdir -p ~/.local/binmv aggrega-<version>-linux-amd64 ~/.local/bin/aggregaOn Windows, see The Windows prebuilt binary below; on macOS, see The macOS prebuilt binary.
When ~/.local/bin is not on your PATH, add this line to the file your shell reads when it starts — ~/.zshrc for zsh, ~/.bashrc for bash (~/.bash_profile on macOS) — and open a new terminal:
export PATH="$HOME/.local/bin:$PATH"From source, with a Go toolchain installed, build the aggrega command from the source tree and put the resulting binary in the same folder.
Confirm the install with aggrega version, as at the end of Install the binary.
Choosing the file
A release names each executable aggrega-<version>-<system>-<processor>, with .exe on Windows:
| System | Processor | File |
|---|---|---|
| Linux | 64-bit x86 (uname -m prints x86_64) | aggrega-<version>-linux-amd64 |
| Linux | 64-bit ARM (uname -m prints aarch64) | aggrega-<version>-linux-arm64 |
| Windows | 64-bit x86 | aggrega-<version>-windows-amd64.exe |
| macOS | Apple silicon | aggrega-<version>-darwin-arm64 |
| macOS | Intel | aggrega-<version>-darwin-amd64 |
That file is the one the install command installs, and the one to download by hand. Two variants of it sit beside it; the install command installs neither, and each installs by hand the same way:
aggrega-debug-<version>-…is the same program with its debug information, which a debugger or a profiler reads. It runs and reports its version exactly as the default file does, and is larger.aggrega-light-<version>-…is built without the embedded plugins: it resolves every plugin through the plugin cascade, as the workspace configures it, rather than finding the core ones inside itself.
For Windows the release also carries aggrega-<version>-windows-amd64-setup.exe, the Windows installer, which installs the default file for you.
Each release also carries SHA256SUMS, the SHA-256 digest of every other file it attaches, the two install scripts included, in the form sha256sum reads. The install command makes this check itself. To check a download by hand on Linux, with SHA256SUMS in the same directory:
sha256sum --check --ignore-missing SHA256SUMSThe file you downloaded is reported OK; any other report means it is not the file the release published.
The Windows prebuilt binary
The Windows executable is aggrega-<version>-windows-amd64.exe (the debug and light variants beside it in the release install the same way). Rename it to aggrega.exe, move it into %LOCALAPPDATA%\Programs\aggrega, the folder the install command uses, and add that folder to your user PATH: Windows runs a file ending in .exe without marking it executable, and finds it as the aggrega command under that name. From PowerShell, for example, with <version> replaced by the version you downloaded:
$dir = "$env:LOCALAPPDATA\Programs\aggrega"New-Item -ItemType Directory -Force $dir | Out-NullMove-Item ".\aggrega-<version>-windows-amd64.exe" "$dir\aggrega.exe"Unblock-File "$dir\aggrega.exe"[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$dir", "User")A terminal opened after that finds aggrega; one already open keeps the PATH it started with.
The executables are signed. Each carries an Authenticode signature, the code signature Windows checks, and the publisher Windows shows for it is Cognitio S.r.l. Each signature also carries a timestamp: the certificate behind a signature is valid for a few days only, and the timestamp is what keeps the signature valid after that certificate expires. To check a downloaded file before you run it:
-
In File Explorer, open the file’s Properties and its Digital Signatures tab. The signature list names Cognitio S.r.l.; select it and then Details, which reports This digital signature is OK.
-
In PowerShell, with
$diras in the example above:Terminal window $signature = Get-AuthenticodeSignature "$dir\aggrega.exe"$signature.Status$signature.SignerCertificate.SubjectStatusreportsValid, and the subject beginsCN=Cognitio S.r.l..NotSignedorHashMismatchmeans the file is not the one the release published, or was changed after it was signed.
A signature names the publisher; it does not make every warning go away. Which one you meet depends on how the file arrived and how you start it:
- While downloading, a browser may warn that the file is not commonly downloaded and ask whether to keep it. Keeping it saves the file as downloaded.
- When you start it from File Explorer or from the browser, Windows may show Windows protected your PC. That prompt comes from Microsoft Defender SmartScreen, which weighs the reputation a file and its publisher have built, so a newly released version can still meet it, signed as it is, until its own reputation builds. For a signed file the prompt names the publisher: select More info, check that it names Cognitio S.r.l. and the file name you downloaded, then select Run anyway. Started from PowerShell or a command prompt instead, the same file may run without that prompt; whether it does depends on the Windows version and its settings.
Unblock-Fileanswers that prompt in advance. A downloaded file is marked as coming from the internet, and that mark is what the Windows protected your PC check answers to.Unblock-Filein PowerShell, as in the example above, removes the mark; so does the Unblock checkbox on the General tab of the file’s Properties in File Explorer.- Where Smart App Control is turned on (Windows 11), it checks a program when you start it. As Microsoft describes it, Smart App Control first asks Microsoft’s cloud security service whether the program is safe; when that service cannot make a confident prediction, it checks the signature, letting a program with a valid signature run and blocking one that is unsigned or whose signature is invalid. Whether it is on is shown under App & browser control in Windows Security.
The macOS prebuilt binary
The macOS executables are aggrega-<version>-darwin-arm64, for a Mac with Apple silicon, and aggrega-<version>-darwin-amd64, for a Mac with an Intel processor; About This Mac in the Apple menu shows which one you have. The debug and light variants beside them in the release install the same way. A Mac with Apple silicon also runs the Intel file, through Rosetta 2 where it is installed, but the Apple silicon file is the one built for it.
Rename the file to aggrega, mark it executable, and move it into ~/.local/bin, the folder the install command uses. From Terminal, in the directory the download is in, for example, with <version> replaced by the version you downloaded, and arm64 by amd64 on an Intel Mac:
chmod +x aggrega-<version>-darwin-arm64mkdir -p ~/.local/binmv aggrega-<version>-darwin-arm64 ~/.local/bin/aggregaThe mkdir creates the folder where it does not exist yet. ~/.local/bin is not on the PATH macOS gives a new terminal, so add the line from Install it by hand to ~/.zshrc, or to ~/.bash_profile for bash, unless it is there already.
The executables are signed and notarized. Each carries a code signature made with the Developer ID of Cognitio s.r.l. — the certificate Apple issues to a developer for software distributed outside the Mac App Store — with the hardened runtime and a secure timestamp, and Apple’s notary service has checked each one and notarized it. Gatekeeper, the macOS check on software from the internet, assesses a program that carries the quarantine mark, the mark a web browser adds to a file it downloads, and accepts one that Apple has notarized, so a file downloaded from the release page runs as it is. A notarization ticket cannot be attached to a single executable file, so Gatekeeper finds the ticket online the first time the file runs; on a Mac that is offline at that moment, Gatekeeper may block the file until the Mac can reach Apple.
To check a downloaded file before you run it, from Terminal, with the file name you downloaded:
codesign --verify --strict --verbose=2 aggrega-<version>-darwin-arm64codesign --display --verbose=2 aggrega-<version>-darwin-arm64The first reports that the file is valid on disk and satisfies its Designated Requirement. The second lists the signature’s authorities, the first of them Developer ID Application: COGNITIO SRL followed by the team identifier in parentheses, and a Timestamp. A file that fails either is not the one the release published, or was changed after it was signed.
A file fetched with curl carries no quarantine mark, so Gatekeeper does not assess it at all: curl does not add the mark a browser does. That is also why the binary the install command puts in place runs without that assessment.