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:

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:

1. Detect your operating system and architecture
2. Download the appropriate binary from GitHub Releases
3. Install it to a user-local bin directory (~/.local/bin or ~/bin)
4. 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:

1. Detect your Windows architecture (x64 or ARM64)
2. Download the appropriate binary from GitHub Releases
3. Install it to %LOCALAPPDATA%\kagi\bin
4. 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.

Nix / NixOS

The repository includes a flake for Nix users. It provides the CLI package, a runnable app, shell completions, and a development shell.

Run the CLI without installing it:

nix run github:Microck/kagi-cli -- search "rust async"

Install it into your Nix profile:

nix profile install github:Microck/kagi-cli

For NixOS or Home Manager, add github:Microck/kagi-cli as a flake input. Use kagi.packages.${system}.default for the package or kagi.overlays.default in your package set.

Authentication works the same as with other installation methods. Run kagi auth after installation or set the required Kagi environment variable.

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

1. Visit the GitHub Releases page
2. Choose the latest release (or a specific version)
3. 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.85 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:

1. Go to System Preferences → Security & Privacy → General
2. Click "Allow Anyway" next to the kagi warning
3. 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
• Other distros (e.g. Alpine): no prebuilt musl binary is published yet, so build from source (see below)

Dependencies:

The binary is statically linked and has no runtime dependencies beyond the Linux kernel.

Shell Completion:

To enable tab completion, install a generated completion script for your detected shell:

kagi completion install

You can also choose the shell explicitly:

kagi completion install --shell bash
kagi completion install --shell zsh
kagi completion install --shell fish
kagi completion install --shell powershell

For manual installs, write the generated script yourself:

kagi completion generate bash > ~/.local/share/bash-completion/completions/kagi
kagi completion generate zsh > ~/.zsh/completions/_kagi
kagi completion generate fish > ~/.config/fish/completions/kagi.fish

The older kagi --generate-completion <shell> shortcut still prints the generated script to stdout.

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:

1. Click "More info" on the warning
2. Click "Run anyway"
3. 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 --format pretty "test query"

Troubleshooting

"command not found" or "kagi is not recognized"

Problem: The binary isn't in your PATH.

Solution:

1. Find where kagi was installed:

   # macOS/Linux
   which kagi || find ~ -name "kagi" -type f 2>/dev/null
   
   # Windows PowerShell
   Get-Command kagi -ErrorAction SilentlyContinue

2. Add the directory to your PATH (see Manual Installation section)

3. 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:

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

"Cannot find binary for platform"

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

Solutions:

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

Binary won't run on Windows

Problem: Windows blocks unsigned executables.

Solutions:

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

Installation succeeded but commands fail

Check these common issues:

1. Authentication not configured: Set up your tokens (see Authentication Guide)
2. Wrong token for command: Check the Auth Matrix
3. Network connectivity: Verify you can reach kagi.com
4. 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 ~/.config/kagi-cli/config.toml

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

Windows:

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

# Remove config
Remove-Item "$HOME\.config\kagi-cli\config.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.