Skip to content

Latest commit

 

History

History
117 lines (79 loc) · 4.34 KB

README.md

File metadata and controls

117 lines (79 loc) · 4.34 KB

cargox

CI Crates.io

cargox runs Rust binaries on demand, installing them automatically if necessary. It mirrors the convenience of npx for the Cargo ecosystem while prioritising cargo-binstall to download prebuilt executables whenever possible.

Installation

We recommend installing cargo-binstall as well, this significantly speeds up use of cargox:

cargo install cargo-binstall
cargo binstall cargox-cli

If you don’t want that then you can just cargo install cargox-cli.

Features

  • Executes crate[@version] binaries, installing them on demand.
  • Prefers cargo-binstall for fast installs falling back to cargo install.
  • Passes through additional arguments to the invoked binary via --.

Usage

cargox <crate[@version]> [--] [binary-args...]

Examples:

# Run the latest bat that is installed or installing the latest bat if necessary
$ cargox bat ./README.md

$ cargox bat@latest ./README.md
# If the installed bat is old we only check for newer if you do this.
# This is how every foo*x* tool works. We are not being different.

# Install and run a pinned version
$ cargox cargo-deny@0.16.3 check

# Force a reinstall, building from source instead of using cargo-binstall
$ cargox --force --build-from-source cargo-nextest
# ^^ shorter: cargox -fs cargo-nextest

Tip

  • Arguments before the first positional are passed to cargox.
  • Arguments after the positional argument are passed to the invoked binary.
  • You can use -- if necessary to define this separation point.

Flags

  • --bin <name>: choose a specific binary when a crate exposes several.
  • -f, --force: reinstall even if the binary already exists on PATH.
  • -q, --quiet: suppress installer output (still prints a short status line).
  • -s, --build-from-source: build from source using cargo install instead of cargo-binstall.

Versioned Installs

Every binary installed by cargox is stored with an explicit version suffix. For example, running cargox bat@0.24.0 produces bin/bat-0.24.0 under the install root. When you invoke cargox bat without a version, the newest installed version is selected automatically. The special specifier @latest triggers a crates.io lookup to install and run the newest published release if a newer one exists.

Where Binaries Are Stored

cargox operates in a completely sandboxed environment, isolated from your system's Cargo installation. This ensures that binaries installed by cargox are separate and don't interfere with your regular cargo install workflow.

Default install locations:

  • Linux/Unix: ~/.local/share/cargox/bin (XDG Data Directory)
  • macOS: ~/Library/Application Support/cargox/bin
  • Windows: %APPDATA%\cargox\bin

Customizing the install directory:

You can override the default by setting:

  • CARGOX_INSTALL_DIR: Custom location for cargox installations

Complete sandboxing:

cargox ensures complete isolation by:

  1. Not checking standard Cargo directories: Binaries in ~/.cargo/bin, ~/.local/bin, /usr/local/bin, or CARGO_HOME/bin are ignored when looking for already-installed binaries.

  2. Binary lookup is restricted to:

    • The cargox install directory only

  3. Environment isolation: When installing packages, cargox removes all Cargo-related environment variables (like CARGO_INSTALL_ROOT, CARGO_HOME, BINSTALL_INSTALL_PATH, etc.) to prevent any leakage into the installation process. Only the controlled cargox install directory is set.

This sandboxing guarantees that:

  • You can test different versions without affecting your system installations
  • cargox binaries won't accidentally shadow your regular Cargo binaries
  • The installation process is predictable and reproducible

Build artifact cleanup:

cargox automatically cleans up build artifacts after installation:

  • When using cargo-binstall, binaries are downloaded pre-built (no artifacts to clean)
  • When using cargo install, build artifacts are placed in a temporary directory that is automatically cleaned up after installation completes

This keeps your system clean and prevents build cache bloat.