Installation Guide

This comprehensive guide covers all methods for installing the kagi CLI on supported platforms. Whether you prefer package managers, manual installation, or building from source, you’ll find detailed instructions here.

Overview of Installation Methods

The kagi CLI can be installed through several methods:

Method	Best For	Complexity	Updates
Install Script	Quick setup, CI/CD	Low	Manual
Package Managers	System integration	Low	Automatic
GitHub Releases	Specific versions	Medium	Manual
Build from Source	Development, customization	High	Manual

Quick Install (Recommended)

For most users, the one-line install scripts provide the fastest path to a working installation.

macOS and Linux

Open your terminal and run:

curl -fsSL https://raw.githubusercontent.com/Microck/kagi-cli/main/scripts/install.sh | sh

This script will:

Detect your operating system and architecture
Download the appropriate binary from GitHub Releases
Install it to a user-local bin directory (~/.local/bin or ~/bin)
Update your shell configuration if necessary

Verification:

kagi --help

You should see the help output listing all available commands.

Windows PowerShell

Open PowerShell and run:

irm https://raw.githubusercontent.com/Microck/kagi-cli/main/scripts/install.ps1 | iex

This script will:

Detect your Windows architecture (x64 or ARM64)
Download the appropriate binary from GitHub Releases
Install it to %LOCALAPPDATA%\*kagi*\bin
Add the directory to your PATH

Verification:

kagi --help

What the Installers Do

The install scripts are designed to be safe and non-destructive:

No sudo required: Installs to user directories, not system directories
Non-destructive: Won’t overwrite existing installations without warning
Shell integration: Automatically updates PATH in .bashrc, .zshrc, or PowerShell profile
Self-contained: No runtime dependencies or external libraries required

Post-Installation Setup

After installation, you may need to: Reload your shell configuration:

# Bash
source ~/.bashrc

# Zsh
source ~/.zshrc

# Fish
source ~/.config/fish/config.fish

Or open a new terminal window to pick up the PATH changes.

Package Manager Installation

For users who prefer package managers, kagi is available through several channels.

Homebrew (macOS and Linux)

If you use Homebrew, you can install kagi via a custom tap:

brew tap Microck/kagi
brew install kagi

Updating:

brew update
brew upgrade kagi

Uninstalling:

brew uninstall kagi
brew untap Microck/kagi

Scoop (Windows)

For Windows users who prefer Scoop:

scoop bucket add kagi https://github.com/Microck/scoop-kagi
scoop install kagi

Updating:

scoop update
scoop update kagi

Uninstalling:

scoop uninstall kagi

npm (Node.js)

The npm package provides a cross-platform wrapper that downloads the native binary:

npm install -g kagi-cli

Or with pnpm:

pnpm add -g kagi-cli

Or with bun:

bun add -g kagi-cli

Important notes:

The package name is kagi-cli (not kagi)
The installed command is kagi
The wrapper downloads the matching native binary during install
Works on any platform supported by Node.js

Updating:

npm update -g kagi-cli

Cargo (Rust)

If you have the Rust toolchain installed, you can install directly from the repository:

cargo install --git https://github.com/Microck/kagi-cli

Or from a local checkout:

git clone https://github.com/Microck/kagi-cli.git
cd kagi-cli
cargo install --path .

Note on crates.io: The package is not currently published to crates.io because both kagi and kagi-cli names are already taken. GitHub Releases remain the canonical distribution method.

Manual Installation from GitHub Releases

For users who want full control over the installation process or need to install a specific version.

Step 1: Download the Release

Visit the GitHub Releases page
Choose the latest release (or a specific version)
Download the appropriate asset for your platform:
- macOS Intel: kagi-x86_64-apple-darwin.tar.gz
- macOS Apple Silicon: kagi-aarch64-apple-darwin.tar.gz
- Linux x86_64: kagi-x86_64-unknown-linux-gnu.tar.gz
- Linux ARM64: kagi-aarch64-unknown-linux-gnu.tar.gz
- Windows x64: kagi-x86_64-pc-windows-msvc.zip

Step 2: Extract the Binary

macOS and Linux:

tar -xzf kagi-*-*.tar.gz

Windows:

Expand-Archive -Path kagi-*.zip -DestinationPath .\kagi

Step 3: Move to PATH

Choose a directory in your PATH. Common choices: macOS and Linux:

# User-local installation (recommended)
mkdir -p ~/.local/bin
mv kagi ~/.local/bin/

# Or system-wide (requires sudo)
sudo mv kagi /usr/local/bin/

Windows:

# Create directory and move binary
New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\kagi\bin"
Move-Item -Path .\kagi\kagi.exe -Destination "$env:LOCALAPPDATA\kagi\bin\"

# Add to PATH
[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:LOCALAPPDATA\kagi\bin",
    "User"
)

Step 4: Verify Installation

kagi --version
kagi --help

Building from Source

For developers who want to modify the code or build for an unsupported platform.

Prerequisites

Rust toolchain 1.70 or later
Git
Network connectivity for dependencies

Install Rust: If you don’t have Rust installed:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Verify installation:

rustc --version
cargo --version

Clone the Repository

git clone https://github.com/Microck/kagi-cli.git
cd kagi-cli

Build Release Binary

cargo build --release

The compiled binary will be at:

macOS/Linux: ./target/release/*kagi*
Windows: .\target\release\*kagi*.exe

Install from Build

Option 1: Run directly

./target/release/kagi --help

Option 2: Install to Cargo bin directory

cargo install --path .

This installs to ~/.cargo/bin/ (already in PATH if you have Rust installed). Option 3: Manual installation

cp ./target/release/kagi ~/.local/bin/

Development Build

For development and testing, use the debug build (faster compilation):

cargo build
cargo run -- --help

Platform-Specific Instructions

macOS

Apple Silicon (M1/M2/M3) and Intel Both architectures are supported. The install scripts and Homebrew automatically detect your architecture. Gatekeeper Notes: macOS may warn about the binary being from an unidentified developer. To allow it:

Go to System Preferences → Security & Privacy → General
Click “Allow Anyway” next to the kagi warning
Run the command again

Or bypass for a single execution:

xattr -d com.apple.quarantine $(which kagi)

Linux

Supported Distributions:

Ubuntu 18.04+
Debian 10+
Fedora 32+
CentOS/RHEL 8+
Arch Linux
Alpine Linux (musl build)

Dependencies: The binary is statically linked and has no runtime dependencies beyond the Linux kernel. Shell Completion: To enable tab completion, add to your shell configuration:

# Bash (~/.bashrc)
eval "$(kagi completions bash)"

# Zsh (~/.zshrc)
eval "$(kagi completions zsh)"

# Fish (~/.config/fish/config.fish)
kagi completions fish | source

Windows

PowerShell Execution Policy: If you encounter execution policy errors when running the install script:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then re-run the install command. Windows Defender: Windows Defender may flag the binary as unfamiliar. This is normal for new releases. You can:

Click “More info” on the warning
Click “Run anyway”
Or add an exclusion for the kagi directory

Verification and Testing

After installation, verify everything works:

Basic Functionality

# Check version
kagi --version

# View help
kagi --help

# Test unauthenticated command
kagi news --category world --limit 3

Authentication Test (if you have tokens)

# Set up session token
kagi auth set --session-token 'https://kagi.com/search?token=YOUR_TOKEN'

# Verify auth
kagi auth check

# Test search
kagi search --pretty "test query"

Troubleshooting

”command not found” or “kagi is not recognized”

Problem: The binary isn’t in your PATH. Solution:

Find where kagi was installed:

# macOS/Linux
which *kagi* || find ~ -name "*kagi*" -type f 2>/dev/null

# Windows PowerShell
Get-Command *kagi* -ErrorAction SilentlyContinue

Add the directory to your PATH (see Manual Installation section)
Reload your shell or open a new terminal

”Permission denied” (macOS/Linux)

Problem: The binary doesn’t have execute permissions. Solution:

chmod +x ~/.local/bin/kagi

Network errors during installation

Problem: Corporate proxy or firewall blocking the download. Solutions:

Use a package manager that respects system proxy settings
Manual download: Download the release asset through a browser
Build from source: Clone and build locally

”Cannot find binary for platform”

Problem: Your platform isn’t supported by the install script. Solutions:

Check the GitHub Releases for your platform
Build from source
Request support by opening an issue

Binary won’t run on Windows

Problem: Windows blocks unsigned executables. Solutions:

Click “More info” → “Run anyway” in the SmartScreen dialog
Add Windows Defender exclusion for the kagi directory
Use the npm package instead (Node.js handles the binary)

Installation succeeded but commands fail

Check these common issues:

Authentication not configured: Set up your tokens (see Authentication Guide)
Wrong token for command: Check the Auth Matrix
Network connectivity: Verify you can reach kagi.com
Rate limiting: Wait a few minutes and try again

Updating from an old version

Using install script: Re-run the install script - it will overwrite the existing binary. Using package manager:

# Homebrew
brew upgrade kagi

# Scoop
scoop update kagi

# npm
npm update -g kagi-cli

# Cargo
cargo install --git https://github.com/Microck/kagi-cli --force

Uninstallation

To completely remove kagi: macOS/Linux:

# Remove binary
rm ~/.local/bin/kagi

# Remove config
rm ./.kagi.toml

# Remove from PATH (edit ~/.bashrc, ~/.zshrc, etc.)

Windows:

# Remove binary
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\kagi"

# Remove config
Remove-Item ".kagi.toml"

# Remove from PATH via System Properties

Package managers:

# Homebrew
brew uninstall kagi
brew untap Microck/kagi

# Scoop
scoop uninstall kagi

# npm
npm uninstall -g kagi-cli

# Cargo
cargo uninstall kagi

Next Steps

Now that kagi is installed, continue with:

Quickstart - Run your first commands
Authentication - Set up your tokens
Advanced Usage - Automation, scripting, and CI/CD patterns

Need help? See the Troubleshooting guide or open an issue on GitHub.

Getting Started

Usage

​Installation Guide

​Overview of Installation Methods

​Quick Install (Recommended)

​macOS and Linux

​Windows PowerShell

​What the Installers Do

​Post-Installation Setup

​Package Manager Installation

​Homebrew (macOS and Linux)

​Scoop (Windows)

​npm (Node.js)

​Cargo (Rust)

​Manual Installation from GitHub Releases

​Step 1: Download the Release

​Step 2: Extract the Binary

​Step 3: Move to PATH

​Step 4: Verify Installation

​Building from Source

​Prerequisites

​Clone the Repository

​Build Release Binary

​Install from Build

​Development Build

​Platform-Specific Instructions

​macOS

​Linux

​Windows

​Verification and Testing

​Basic Functionality

​Authentication Test (if you have tokens)

​Troubleshooting

​”command not found” or “kagi is not recognized”

​”Permission denied” (macOS/Linux)

​Network errors during installation

​”Cannot find binary for platform”

​Binary won’t run on Windows

​Installation succeeded but commands fail

​Updating from an old version

​Uninstallation

​Next Steps

Installation Guide

Overview of Installation Methods

Quick Install (Recommended)

macOS and Linux

Windows PowerShell

What the Installers Do

Post-Installation Setup

Package Manager Installation

Homebrew (macOS and Linux)

Scoop (Windows)

npm (Node.js)

Cargo (Rust)

Manual Installation from GitHub Releases

Step 1: Download the Release

Step 2: Extract the Binary

Step 3: Move to PATH

Step 4: Verify Installation

Building from Source

Prerequisites

Clone the Repository

Build Release Binary

Install from Build

Development Build

Platform-Specific Instructions

macOS

Linux

Windows

Verification and Testing

Basic Functionality

Authentication Test (if you have tokens)

Troubleshooting

”command not found” or “kagi is not recognized”

”Permission denied” (macOS/Linux)

Network errors during installation

”Cannot find binary for platform”

Binary won’t run on Windows

Installation succeeded but commands fail

Updating from an old version

Uninstallation

Next Steps