Installation

Geni can be installed using multiple methods depending on your platform and preferences. Choose the installation method that works best for your environment.

Quick Install

macOS

brew install geni

Rust Developers

cargo install geni

Installation Methods

Homebrew (macOS & Linux)

The easiest way to install Geni on macOS or Linux with Homebrew:

brew install geni

Verify the installation:

geni --version

Homebrew automatically adds Geni to your PATH and handles updates via brew upgrade geni.

GitHub Releases (Linux)

Download the latest binary directly from GitHub releases:

sudo curl -fsSL -o /usr/local/bin/geni \
  https://github.com/emilpriver/geni/releases/latest/download/geni-linux-amd64
sudo chmod +x /usr/local/bin/geni

Verify the installation:

geni --version

Pre-built binaries are available for Linux AMD64 architecture. For other platforms, consider using Cargo or Docker.

Cargo (All Platforms)

If you have Rust installed, you can build and install Geni from source:

cargo install geni

This will compile Geni from source and install it to ~/.cargo/bin/. Make sure this directory is in your PATH.Verify the installation:

geni --version

Installing via Cargo ensures you get the latest version optimized for your specific platform.

Docker

Geni provides official Docker images published to GitHub Container Registry.

Standard Image

The standard image includes all database client tools (pg_dump, mysqldump, etc.) for schema dumping:

docker run --rm -it --network=host ghcr.io/emilpriver/geni:latest --help

Slim Image

The slim image is smaller but doesn’t include database client tools. Schema dumping will be disabled:

docker run --rm -it --network=host ghcr.io/emilpriver/geni:latest-slim --help

The slim image won’t attempt to dump the database schema. Use the standard image if you need schema.sql generation.

Using Docker with Migrations

To create or apply migrations, use Docker’s bind mount feature to make your local migrations directory available:

# Create a new migration
docker run --rm -it --network=host \
  -v "$(pwd)/migrations:/migrations" \
  ghcr.io/emilpriver/geni:latest new create_users_table

# Run migrations
docker run --rm -it --network=host \
  -v "$(pwd)/migrations:/migrations" \
  -e DATABASE_URL="postgres://user:pass@localhost/db" \
  ghcr.io/emilpriver/geni:latest up

The --network=host flag allows the container to access services running on your host machine (like local databases).

Nix Flake

Run Geni directly using Nix without installation:

nix run github:emilpriver/geni -- up

You can also run other commands:

# Create a new migration
nix run github:emilpriver/geni -- new create_users

# Check status
nix run github:emilpriver/geni -- status

This method doesn’t require installation and always fetches the latest version from GitHub.

PKGX

Run Geni using PKGX without installation:

pkgx geni up

PKGX will automatically fetch and run the appropriate version:

# Create a migration
pkgx geni new add_email_column

# Check migration status
pkgx geni status

PKGX is great for trying out Geni or using it in environments where you can’t install packages.

Verify Installation

After installation, verify that Geni is working correctly:

Check Version

Run the version command to ensure Geni is installed:

geni --version

You should see output like:

geni v1.1.9

View Help

Display available commands:

geni --help

This will show all available subcommands:

A standalone database CLI migration tool

Usage: geni <COMMAND>

Commands:
  new     Create new migration
  up      Migrate to the latest version
  down    Rollback to last migration
  create  Create database
  drop    Drop database
  status  Show current migrations to apply
  dump    Dump database structure
  help    Print this message or the help of the given subcommand(s)

Test with SQLite

Create a test migration with SQLite (no database setup required):

mkdir test-geni && cd test-geni
DATABASE_URL="sqlite://./test.db" geni new test_migration

You should see:

Created migration: migrations/20240302120000_test_migration.up.sql
Created migration: migrations/20240302120000_test_migration.down.sql

Next Steps

Now that you have Geni installed:

Quickstart Tutorial

Follow a hands-on tutorial to create and run your first migration

Configuration

Learn about environment variables and configuration options

Commands Reference

Explore all available Geni commands and their options

Database Setup

Configure Geni for your specific database system

Troubleshooting

Geni command not found

If you installed via Cargo, ensure ~/.cargo/bin is in your PATH:

export PATH="$HOME/.cargo/bin:$PATH"

Add this to your ~/.bashrc or ~/.zshrc to make it permanent.

Permission denied on Linux

If you downloaded from GitHub releases and get permission errors:

sudo chmod +x /usr/local/bin/geni

Ensure you have write permissions to /usr/local/bin/ or install to a user directory.

Docker: Cannot connect to database

When running in Docker, use --network=host to access host databases:

docker run --rm -it --network=host \
  -e DATABASE_URL="postgres://localhost/db" \
  ghcr.io/emilpriver/geni:latest up

Or use the container’s gateway IP to reach the host.

Get Started

Core Concepts

Commands

Configuration

Database Support

Integration

Guides

Installation

Quick Install

macOS

Rust Developers

Installation Methods

Homebrew (macOS & Linux)

GitHub Releases (Linux)

Cargo (All Platforms)

Docker

Standard Image

Slim Image

Using Docker with Migrations

Nix Flake

PKGX

Verify Installation

Next Steps

Quickstart Tutorial

Configuration

Commands Reference

Database Setup

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Commands

Configuration

Database Support

Integration

Guides

​Quick Install

macOS

Rust Developers

​Installation Methods

​Homebrew (macOS & Linux)

​GitHub Releases (Linux)

​Cargo (All Platforms)

​Docker

​Standard Image

​Slim Image

​Using Docker with Migrations

​Nix Flake

​PKGX

​Verify Installation

​Next Steps

Quickstart Tutorial

Configuration

Commands Reference

Database Setup

​Troubleshooting

Build docs developers (and LLMs) love

Quick Install

Installation Methods

Homebrew (macOS & Linux)

GitHub Releases (Linux)

Cargo (All Platforms)

Docker

Standard Image

Slim Image

Using Docker with Migrations

Nix Flake

PKGX

Verify Installation

Next Steps

Troubleshooting