dotbins 0.18.0

Keep updated binaries in your dotfiles

dotbins 🧰

dotbins manages CLI tool binaries in your dotfiles repository, offering:

• ✅ Cross-platform binary management (macOS, Linux, Windows)
• ✅ No admin privileges required
• ✅ Version-controlled CLI tools
• ✅ Downloads from GitHub releases
• ✅ Perfect for dotfiles synchronization

No package manager, no sudo, no problem.

:zap: Quick Start

Using the amazing uv package manager:

# Install directly to ~/.local/bin
uvx dotbins get junegunn/fzf

# Set up multiple tools with a config file
uvx dotbins update

# Bootstrap a collection of tools from a remote config
uvx dotbins get https://raw.githubusercontent.com/username/dotbins-config/main/tools.yaml

See it in action:

[ToC] 📚

• :star2: Features
• :bulb: Why I Created dotbins
• :books: Usage
  • Commands
  • Quick Install with dotbins get
• :hammer_and_wrench: Installation
• :gear: Configuration
  • Basic Configuration
  • Tool Configuration
  • Platform and Architecture Mapping
  • Pattern Variables
  • Multiple Binaries
  • Configuration Examples
    • Minimal Tool Configuration
    • Standard Tool
    • Tool with Multiple Binaries
    • Platform-Specific Tool
  • Full Configuration Example
• :bulb: Examples
• :computer: Shell Integration
• :heart: Support and Contributions

:star2: Features

• 🌐 Supports multiple platforms (macOS, Linux, etc.) and architectures (amd64, arm64, etc.)
• 📦 Downloads and organizes binaries from GitHub releases
• 🔄 Updates tools to their latest versions with a single command
• 📊 Tracks installed versions and update timestamps for all tools
• 🧩 Extracts binaries from various archive formats (zip, tar.gz)
• 📂 Organizes tools by platform and architecture for easy access
• 🐙 Easy integration with your dotfiles repository for version control

:bulb: Why I Created dotbins

I frequently works across multiple environments where I clone my dotfiles repository with all my preferred configurations. I faced a common frustration: some of my favorite tools (fzf, bat, zoxide, etc.) were not available on the new system and installing them with a package manager is too much work or even not possible. dotbins was born out of this frustration.

It allows me to:

1. Track pre-compiled binaries in a separate Git repository (using Git LFS for efficient storage)
2. Include this repository as a submodule in my dotfiles
3. Ensure all my essential tools are immediately available after cloning, regardless of system permissions

Now when I clone my dotfiles on any new system, I get not just my configurations but also all the CLI tools I depend on for productivity.

No package manager, no sudo, no problem!

:books: Usage

[!TIP] Use uvx dotbins and create a ~/.config/dotbins/config.yaml file to store your configuration.

To use dotbins, you'll need to familiarize yourself with its commands:

dotbins --help

usage: dotbins [-h] [-v] [--tools-dir TOOLS_DIR] [--config-file CONFIG_FILE]
               {list,update,init,version,versions,readme,get} ...

dotbins - Manage CLI tool binaries in your dotfiles repository

positional arguments:
  {list,update,init,version,versions,readme,get}
                        Command to execute
    list                List available tools
    update              Update tools
    init                Initialize directory structure
    version             Print version information
    versions            Show installed tool versions and their last update
                        times
    readme              Generate README.md file with tool information
    get                 Download and install a tool directly from GitHub or
                        from a remote configuration

options:
  -h, --help            show this help message and exit
  -v, --verbose         Enable verbose output (default: False)
  --tools-dir TOOLS_DIR
                        Tools directory (default: None)
  --config-file CONFIG_FILE
                        Path to configuration file (default: None)

Commands

1. update - Download or update tools
2. get - Download and install a tool directly without using a configuration file
3. init - Initialize the tools directory structure
4. list - List available tools defined in your configuration
5. version - Print version information
6. versions - Show detailed information about installed tool versions

Quick Install with dotbins get

The get command allows you to quickly download and install tools directly from GitHub or from a remote configuration file:

# Install fzf to the default location (~/.local/bin)
dotbins get junegunn/fzf

# Install ripgrep with a custom binary name
dotbins get BurntSushi/ripgrep --name rg

# Install bat to a specific location
dotbins get sharkdp/bat --dest ~/bin

# Install multiple tools from a remote config URL
dotbins get https://example.com/my-tools.yaml --dest ~/.local/bin

This is perfect for:

• Quickly installing tools on a new system
• One-off installations without needing a configuration file
• Adding tools to PATH in standard locations like ~/.local/bin
• Bootstrapping with a pre-configured set of tools using a remote configuration URL

The get command automatically detects whether you're providing a GitHub repository or a configuration URL. When using a URL, it will download all tools defined in the configuration for your current platform and architecture.

:hammer_and_wrench: Installation

We highly recommend to use uv to run dotbins:

uvx dotbins

or install as a global command:

uv tool install dotbins

Otherwise, simply use pip:

pip install dotbins

You'll also need to create or update your dotbins.yaml configuration file either in the same directory as the script or at a custom location specified with --tools-dir.

:gear: Configuration

dotbins uses a YAML configuration file to define the tools and settings. The configuration file is searched in the following locations (in order):

1. Explicitly provided path (using --config-file option)
2. ./dotbins.yaml (current directory)
3. ~/.config/dotbins/config.yaml (XDG config directory)
4. ~/.config/dotbins.yaml (XDG config directory, flat)
5. ~/.dotbins.yaml (home directory)
6. ~/.dotbins/dotbins.yaml (default dotfiles location)

The first valid configuration file found will be used. If no configuration file is found, default settings will be used.

Basic Configuration

# Basic settings
tools_dir: ~/.dotbins

# Target platforms and architectures
platforms:
  linux:
    - amd64
    - arm64
  macos:
    - arm64  # Only arm64 for macOS

# Tool definitions
tools:
  # Tool configuration entries

Tool Configuration

Each tool must be configured with at least a GitHub repository. Many other fields are optional and can be auto-detected:

tool-name:
  repo: owner/repo                 # Required: GitHub repository
  extract_binary: true             # Optional: Whether to extract from archive (true) or direct download (false)
  binary_name: executable-name     # Optional: Name of the resulting binary(ies) (defaults to tool-name)
  binary_path: path/to/binary      # Optional: Path to the binary within the archive (auto-detected if not specified)

  # Asset patterns - Optional with auto-detection
  # Option 1: Platform-specific patterns
  asset_patterns:                  # Optional: Asset patterns for each platform
    linux: pattern-for-linux.tar.gz
    macos: pattern-for-macos.tar.gz
  # Option 2: Single pattern for all platforms
  asset_patterns: pattern-for-all-platforms.tar.gz  # Global pattern for all platforms
  # Option 3: Explicit platform patterns for different architectures
  asset_patterns:
    linux:
      amd64: pattern-for-linux-amd64.tar.gz
      arm64: pattern-for-linux-arm64.tar.gz
    macos:
      amd64: pattern-for-macos-amd64.tar.gz
      arm64: pattern-for-macos-arm64.tar.gz

If you don't specify binary_path or asset_patterns, dotbins will attempt to auto-detect the appropriate values for you. This often works well for standard tool releases.

Platform and Architecture Mapping

If the tool uses different naming for platforms or architectures:

tool-name:
  # Basic fields...
  platform_map:                    # Optional: Platform name mapping
    macos: darwin                  # Converts "macos" to "darwin" in patterns
  arch_map:                        # Optional: Architecture name mapping
    amd64: x86_64                  # Converts "amd64" to "x86_64" in patterns
    arm64: aarch64                 # Converts "arm64" to "aarch64" in patterns

Pattern Variables

In asset patterns, you can use these variables:

• {version} - Release version (without 'v' prefix)
• {platform} - Platform name (after applying platform_map)
• {arch} - Architecture name (after applying arch_map)

Multiple Binaries

For tools that provide multiple binaries:

tool-name:
  # Other fields...
  binary_name: [main-binary, additional-binary]
  binary_path: [path/to/main, path/to/additional]

Configuration Examples

Minimal Tool Configuration

ripgrep:
  repo: BurntSushi/ripgrep
  binary_name: rg  # Only specify if different from tool name

Standard Tool

atuin:
  repo: atuinsh/atuin
  arch_map:
    amd64: x86_64
    arm64: aarch64
  asset_patterns:
    linux: atuin-{arch}-unknown-linux-gnu.tar.gz
    macos: atuin-{arch}-apple-darwin.tar.gz

Tool with Multiple Binaries

uv:
  repo: astral-sh/uv
  binary_name: [uv, uvx]
  binary_path: [uv-*/uv, uv-*/uvx]

Platform-Specific Tool

eza:
  repo: eza-community/eza
  arch_map:
    amd64: x86_64
    arm64: aarch64
  asset_patterns:
    linux: eza_{arch}-unknown-linux-gnu.tar.gz
    macos: null  # No macOS version available

Full Configuration Example

# Configuration
tools_dir: ~/.dotbins

platforms:
  linux:
    - amd64
    - arm64
  macos:
    - arm64

# Tool definitions
tools:
  fzf:
    repo: junegunn/fzf

  bat:
    repo: sharkdp/bat

  eza:
    repo: eza-community/eza
    arch_map:
      amd64: x86_64
      arm64: aarch64
    asset_patterns:
      linux: eza_{arch}-unknown-linux-gnu.tar.gz
      macos: null  # No macOS binaries available as of now

  zoxide:
    repo: ajeetdsouza/zoxide

  delta:
    repo: dandavison/delta

  uv:
    repo: astral-sh/uv
    binary_name: [uv, uvx]
    binary_path: [uv-*/uv, uv-*/uvx]

  micromamba:
    repo: mamba-org/micromamba-releases
    extract_binary: false
    binary_path: bin/micromamba
    arch_map:
      amd64: 64
      arm64: aarch64
    asset_patterns:
      linux: micromamba-linux-{arch}
      macos: micromamba-osx-arm64

  atuin:
    repo: atuinsh/atuin
    arch_map:
      amd64: x86_64
      arm64: aarch64
    asset_patterns:
      linux: atuin-{arch}-unknown-linux-gnu.tar.gz
      macos: atuin-{arch}-apple-darwin.tar.gz

  git-lfs:
    repo: git-lfs/git-lfs

  ripgrep:
    repo: BurntSushi/ripgrep
    binary_name: rg

  direnv:
    repo: direnv/direnv
    extract_binary: false

  lazygit:
    repo: jesseduffield/lazygit

  fd:
    repo: sharkdp/fd

  duf:
    repo: muesli/duf

  yazi:
    repo: sxyazi/yazi

:bulb: Examples

List available tools:

dotbins list

Update all tools for all platforms:

dotbins update

Update specific tools only:

dotbins update fzf bat

Update tools for a specific platform/architecture:

dotbins update -p macos -a arm64

Install tools from a remote configuration:

dotbins get https://raw.githubusercontent.com/username/dotbins-config/main/tools.yaml --dest ~/bin

:computer: Shell Integration

Add this to your shell configuration file (e.g., .bashrc, .zshrc) to use the platform-specific binaries:

✅ Loading configuration from: /home/runner/work/dotbins/dotbins/dotbins.yaml
🛠️ dotbins initialized tools directory structure

# Add this to your shell configuration file (e.g., .bashrc, .zshrc):

# dotbins - Add platform-specific binaries to PATH
_os=$(uname -s | tr '[:upper:]' '[:lower:]')
[[ "$_os" == "darwin" ]] && _os="macos"

_arch=$(uname -m)
[[ "$_arch" == "x86_64" ]] && _arch="amd64"
[[ "$_arch" == "aarch64" || "$_arch" == "arm64" ]] && _arch="arm64"

export PATH="$HOME/.dotbins/$_os/$_arch/bin:$PATH"

📝 Generated README at /home/runner/.dotbins/README.md
📝 Generated README file with shell integration instructions

:heart: Support and Contributions

We appreciate your feedback and contributions! If you encounter any issues or have suggestions for improvements, please file an issue on the GitHub repository. We also welcome pull requests for bug fixes or new features.

Happy tooling! 🧰🛠️🎉