Installation

ChameleonDB CLI is available for Linux, macOS, and Windows. Choose your platform below.

Prerequisites

Before installing ChameleonDB, ensure you have:

Go 1.21+ (for using ChameleonDB in your applications)
PostgreSQL 14+ (as the backend database)
Rust 1.75+ (only if building from source)

Quick Install

Linux / macOS
Windows

Auto-Install Script

The easiest way to install ChameleonDB on Linux or macOS:

curl -sSL https://chameleondb.dev/install | sh

This script will:

Detect your platform and architecture
Download the latest release binary
Install to /usr/local/bin/chameleon
Make it executable

Verify Installation

chameleon --version
# Output: chameleon v1.0-alpha

The install script requires curl and sudo access. If you don’t have sudo, see the manual installation section below.

Download Binary

ChameleonDB is distributed as a portable binary for Windows. No installer required.

Download

Download the compressed .gz file:Download ChameleonDB for Windows

Extract

Extract the .gz file using WinRAR, WinZip, 7-Zip, or similar.You will get two files:

chameleon.exe
chameleon.dll

Both files must be kept together in the same directory.

Move to Safe Folder

Create a folder for ChameleonDB:

C:\chameleon\

Move both files (.exe and .dll) into that folder.

Add to PATH

To run chameleon from any terminal:

Open System Settings → Environment Variables
Under System variables, select Path → Edit
Add the path: C:\chameleon\ (or your chosen path)
Click OK to save

Close and reopen your terminal for the PATH change to take effect.

Verify Installation

Open a new terminal (CMD or PowerShell) and run:

chameleon --version
# Output: chameleon v1.0-alpha

Manual Installation

Linux (Manual)

Download Binary

# AMD64
curl -LO https://github.com/chameleon-db/chameleondb/releases/download/v1.0-alpha/chameleon-linux-amd64

# ARM64
curl -LO https://github.com/chameleon-db/chameleondb/releases/download/v1.0-alpha/chameleon-linux-arm64

Install

# AMD64
chmod +x chameleon-linux-amd64
sudo mv chameleon-linux-amd64 /usr/local/bin/chameleon

# ARM64
chmod +x chameleon-linux-arm64
sudo mv chameleon-linux-arm64 /usr/local/bin/chameleon

Verify

chameleon --version

If you don’t have sudo access, install to ~/bin/chameleon and add ~/bin to your PATH.

macOS (Manual)

Download Binary

# Intel (AMD64)
curl -LO https://github.com/chameleon-db/chameleondb/releases/download/v1.0-alpha/chameleon-darwin-amd64

# Apple Silicon (ARM64)
curl -LO https://github.com/chameleon-db/chameleondb/releases/download/v1.0-alpha/chameleon-darwin-arm64

Install

# Intel
chmod +x chameleon-darwin-amd64
sudo mv chameleon-darwin-amd64 /usr/local/bin/chameleon

# Apple Silicon
chmod +x chameleon-darwin-arm64
sudo mv chameleon-darwin-arm64 /usr/local/bin/chameleon

Handle macOS Security

macOS may block the binary on first run:

# Remove quarantine attribute
xattr -d com.apple.quarantine /usr/local/bin/chameleon

Verify

chameleon --version

Build from Source

For advanced users who want to build ChameleonDB from source:

Install Prerequisites

You’ll need:

Rust 1.75+: https://rustup.rs
Go 1.21+: https://golang.org/dl
Git: https://git-scm.com
Make: Usually pre-installed on Linux/macOS

Clone Repository

git clone https://github.com/chameleon-db/chameleondb.git
cd chameleondb

Build Rust Core

cd chameleon-core
cargo build --release

This creates libchameleon.so (Linux) or libchameleon.dylib (macOS).

Install Shared Library

sudo cp target/release/libchameleon.so /usr/local/lib/
sudo cp include/chameleon.h /usr/local/include/
sudo ldconfig

sudo cp target/release/libchameleon.dylib /usr/local/lib/
sudo cp include/chameleon.h /usr/local/include/

Build Go CLI

cd ../chameleon
make build

This creates ./bin/chameleon.

Install CLI

sudo make install

Or manually:

sudo cp ./bin/chameleon /usr/local/bin/

Verify Installation

chameleon --version
# Output: chameleon v1.0-alpha

Building from source requires both Rust and Go toolchains. For most users, the pre-built binaries are recommended.

Using ChameleonDB as a Go SDK

If you want to use ChameleonDB in your Go application:

Install the Package

go get github.com/chameleon-db/chameleondb/chameleon@latest

Requirements

The Go package links to libchameleon via cgo:

Linux: libchameleon.so must be in /usr/local/lib (or set CGO_LDFLAGS)
macOS: libchameleon.dylib must be in /usr/local/lib
Windows: chameleon.dll must be in the same directory as your .exe
Header: chameleon.h should be in /usr/local/include

Build from Monorepo

If building from the ChameleonDB monorepo:

# Build Rust core
cd chameleon-core
cargo build --release

# Install library
sudo cp target/release/libchameleon.so /usr/local/lib/
sudo cp include/chameleon.h /usr/local/include/
sudo ldconfig  # Linux only

# Use in Go
cd ../chameleon
go build ./...

Custom Library Location

If you install the library in a non-standard location:

CGO_LDFLAGS="-L/path/to/lib -Wl,-rpath,/path/to/lib -lchameleon" \
CGO_CFLAGS="-I/path/to/include" \
go build ./...

For production deployments, we recommend using pkg-config to manage library paths. See the ChameleonDB repository for details.

Platform-Specific Notes

Linux

Shared Library Location

libchameleon.so must be in a directory that ld searches:

/usr/local/lib (recommended)
/usr/lib
Custom path (requires LD_LIBRARY_PATH or ldconfig config)

Update Library Cache

After installing to /usr/local/lib:

sudo ldconfig

Verify Library

ldd $(which chameleon)
# Should show libchameleon.so => /usr/local/lib/libchameleon.so

macOS

System Integrity Protection (SIP)

macOS may block unsigned binaries. If you see a security warning:

xattr -d com.apple.quarantine /usr/local/bin/chameleon

Library Location

libchameleon.dylib should be in:

/usr/local/lib (recommended)
Custom path (requires DYLD_LIBRARY_PATH)

Verify Library

otool -L $(which chameleon)
# Should show libchameleon.dylib

Windows

DLL Location

chameleon.dll must be:

In the same directory as chameleon.exe
In a directory listed in your PATH
In C:\Windows\System32 (not recommended)

PowerShell Execution Policy

If you encounter permission errors:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Verify Installation

Get-Command chameleon
# Should show: C:\chameleon\chameleon.exe

Docker

Official Docker images are coming soon. For now, you can build your own:

Dockerfile

FROM rust:1.75 AS builder-rust
WORKDIR /build
COPY chameleon-core ./chameleon-core
RUN cd chameleon-core && cargo build --release

FROM golang:1.21 AS builder-go
WORKDIR /build
COPY --from=builder-rust /build/chameleon-core/target/release/libchameleon.so /usr/local/lib/
COPY --from=builder-rust /build/chameleon-core/include/chameleon.h /usr/local/include/
COPY chameleon ./chameleon
RUN cd chameleon && make build

FROM ubuntu:22.04
COPY --from=builder-go /build/chameleon/bin/chameleon /usr/local/bin/
COPY --from=builder-rust /build/chameleon-core/target/release/libchameleon.so /usr/local/lib/
RUN ldconfig
ENTRYPOINT ["chameleon"]

Troubleshooting

command not found: chameleon

The binary is not in your PATH.Solution:

Check installation location: which chameleon
Add to PATH: export PATH="$PATH:/usr/local/bin"
Reinstall with sudo: sudo mv chameleon /usr/local/bin/

error while loading shared libraries: libchameleon.so

The shared library is not found.Solution (Linux):

sudo cp libchameleon.so /usr/local/lib/
sudo ldconfig

Solution (macOS):

sudo cp libchameleon.dylib /usr/local/lib/

cannot execute binary file

You downloaded the wrong architecture.Solution:

Check your architecture: uname -m
Download the correct binary (amd64 or arm64)

Windows: The system cannot find the file specified

chameleon.dll is not in the same directory as chameleon.exe.Solution:

Keep both files together
Or add the DLL directory to your PATH

Next Steps

Quick Start

Get started with ChameleonDB in 5 minutes

CLI Reference

Learn all available commands

Getting Help

If you encounter installation issues:

GitHub Issues: Report a bug
Discord: Join our community
Documentation: Browse all docs

​Installation

​Prerequisites

​Quick Install

​Auto-Install Script

​Verify Installation

​Download Binary

​Manual Installation

​Download Binary

​Install

​Verify

​Download Binary

​Install

​Handle macOS Security

​Verify

​Build from Source

​Using ChameleonDB as a Go SDK

​Install the Package

​Requirements

​Build from Monorepo

​Custom Library Location

​Platform-Specific Notes

​Shared Library Location

​Update Library Cache

​Verify Library

​System Integrity Protection (SIP)

​Library Location

​Verify Library

​DLL Location

​PowerShell Execution Policy

​Verify Installation

​Docker

​Troubleshooting

​Next Steps

Quick Start

CLI Reference

​Getting Help

Installation

Prerequisites

Quick Install

Auto-Install Script

Verify Installation

Download Binary

Manual Installation

Download Binary

Install

Verify

Download Binary

Install

Handle macOS Security

Verify

Build from Source

Using ChameleonDB as a Go SDK

Install the Package

Requirements

Build from Monorepo

Custom Library Location

Platform-Specific Notes

Shared Library Location

Update Library Cache

Verify Library

System Integrity Protection (SIP)

Library Location

Verify Library

DLL Location

PowerShell Execution Policy

Verify Installation

Docker

Troubleshooting

Next Steps

Getting Help