gale

module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 28, 2026 License: MIT

README

Gale

Fast, isolated package management for developers. Versioned installs, per-project environments that activate automatically.

Features

  • Install CLI tools and runtimes into isolated directories
  • Per-project environments that activate on cd
  • Declarative gale.toml for reproducible setups
  • Federated recipe repositories with ed25519 signing
  • Optional AI-powered search and recipe generation

Install

Gale is not yet published. Build from source:

git clone https://github.com/kelp/gale
cd gale
go build -o gale ./cmd/gale/
# Copy to somewhere on your PATH

Setup

Add ~/.gale/current/bin to your PATH:

# .zshrc or .bashrc
export PATH="$HOME/.gale/current/bin:$PATH"

For per-project environments with direnv, add the gale hook to your direnvrc:

# ~/.config/direnv/direnvrc
eval "$(gale hook direnv)"

Quick Start

# Install a package globally
gale install jq

# List installed packages
gale list

# Remove a package
gale remove jq

# Initialize a project environment
gale init
# Creates gale.toml and .envrc, then:
direnv allow

Project Environments

gale.toml declares project dependencies:

[packages]
  go = "1.26.1"
  just = "1.48.0"

Run gale sync to install, or let direnv activate the environment automatically when you cd into the project.

Commands

gale install <pkg>[@ver]  Install a package
gale remove <pkg>         Remove a package
gale add <pkg> [pkg...]   Add to gale.toml without installing
gale sync                 Install all packages in gale.toml
gale list                 List packages in gale.toml
gale env                  Print export PATH for current scope
gale init                 Bootstrap project (gale.toml, .envrc)
gale hook direnv          Print use_gale function for direnvrc
gale build <recipe.toml>  Build recipe from source
gale search <query>       Search for packages
gale shell                Open shell with project environment
gale run <cmd>            Run command in project environment
gale import homebrew <n>  Import Homebrew formula as recipe

Development

Prerequisites

Go 1.21+ is required for bootstrapping. After that, gale manages its own dev dependencies.

First-Time Setup
# Clone both repos side-by-side
git clone https://github.com/kelp/gale
git clone https://github.com/kelp/gale-recipes

# Bootstrap: build gale with go, then self-install
cd gale
just bootstrap

# Sync project dev tools (go, just, golangci-lint, gofumpt)
gale sync --local

# Activate the project environment
direnv allow

After bootstrapping, just install rebuilds gale from the current source using gale itself. The version is set from git rev-parse --short HEAD.

Common Tasks
just         # run tests and lint
just build   # build binary
just check   # tests + lint + format check
just test-pkg recipe  # test single package
Two-Repo Architecture

Gale uses two repositories side-by-side:

  • gale — the CLI tool (this repo)
  • gale-recipes — TOML recipe files and CI that builds binaries and pushes them to GHCR

When you run gale install jq, it fetches the recipe from the registry, pulls a prebuilt binary from GHCR if available, and falls back to building from source.

Local Development Flags

When working on gale or recipes locally:

  • --source <dir> — build from a local source directory instead of downloading. Auto-finds the recipe in a sibling gale-recipes/ directory. Version is detected from git rev-parse --short HEAD.
  • --recipe <file> — use a local recipe TOML file instead of fetching from the registry.
  • --local (on gale sync) — resolve all recipes from the sibling gale-recipes/ directory instead of the remote registry.
Adding a Recipe

Recipes live in gale-recipes/ with letter-bucketed paths: recipes/<first-letter>/<name>.toml.

[package]
name = "mytool"
version = "1.0.0"
description = "My tool"
license = "MIT"
homepage = "https://github.com/owner/mytool"

[source]
repo = "owner/mytool"
url = "https://github.com/owner/mytool/archive/refs/tags/v1.0.0.tar.gz"
sha256 = "..."

[dependencies]
build = ["go"]

[build]
steps = [
  "mkdir -p ${PREFIX}/bin",
  "go build -o ${PREFIX}/bin/mytool .",
]

Test locally with:

gale build ../gale-recipes/recipes/m/mytool.toml

License

MIT

Directories

Path Synopsis
cmd
gale command
internal
ai
env

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL