# crgx — Run Any Crate Binary Instantly > crgx is a command-line tool that runs any Rust crate binary instantly without > cargo install. It is the npx equivalent for the Rust ecosystem — it fetches > pre-built binaries, caches them locally, and executes them in one command. > Works on Linux, macOS, and Windows. MIT licensed. Current version: 0.1.0. crgx resolves binaries through a multi-source chain: local cache, binstall metadata, GitHub Releases, cargo-quickinstall, and optionally cargo build. Any crate that works with cargo-binstall works with crgx automatically. The crgx process replaces itself via exec(), so there is zero runtime overhead. Website: https://crgx.dev Source code: https://github.com/yfedoseev/crgx crates.io: https://crates.io/crates/crgx --- ## Installation ### macOS (Homebrew) ```bash brew install yfedoseev/tap/crgx ``` ### Linux / macOS (shell script) ```bash curl -fsSL crgx.dev/install.sh | sh ``` ### Windows (PowerShell) ```powershell irm crgx.dev/install.ps1 | iex ``` ### Any platform (Cargo) ```bash cargo install crgx ``` ### Pre-built binaries Download from https://github.com/yfedoseev/crgx/releases --- ## Usage ``` crgx [FLAGS] [@] [tool-args...] ``` Everything after the crate specifier is passed directly to the tool. crgx downloads automatically without prompting, like uvx. ### Examples ```bash crgx tokei . # count lines of code crgx hyperfine "echo hello" # benchmark a command crgx ripgrep -i "TODO" src/ # search files crgx dust . # disk usage overview crgx cargo-audit # security audit crgx sd 'before' 'after' *.md # find & replace ``` ### Version pinning ```bash crgx tokei@14.0.0 . # exact version (cached forever) crgx tokei@latest . # force latest from registry crgx tokei . # latest, with 24h staleness check ``` --- ## Flags | Flag | Description | |------|-------------| | `-v`, `--verbose` | Show detailed progress and resolution info | | `--allow-build` | Allow compiling from source if no pre-built binary found | | `--bin ` | Specify which binary to run (for multi-binary crates) | | `--offline` | Only run if already cached; no network access | --- ## Version Specifiers | Specifier | Behavior | |-----------|----------| | `crgx tokei` | Latest version, re-checked every 24 hours | | `crgx tokei@latest` | Force-fetch the latest version from the registry | | `crgx tokei@14.0.0` | Exact version, cached forever once downloaded | Bare names (no version suffix) use a 24-hour staleness window — crgx checks for a newer version at most once per day. Exact versions are pinned permanently and never re-checked. --- ## Cache Management ```bash crgx --cache-list # show cached binaries crgx --cache-clean # remove all cached binaries crgx --cache-dir # print cache directory path ``` ### Cache locations | OS | Path | |----|------| | Linux | `~/.cache/crgx/` | | macOS | `~/Library/Caches/crgx/` | | Windows | `%LOCALAPPDATA%\crgx\cache` | Exact versions (`tool@1.2.3`) are cached forever. Unversioned calls use a 24-hour staleness window. When the network is unavailable, crgx falls back to cached binaries instead of failing. --- ## Resolution Chain crgx tries each source in order to find a pre-built binary. The first match wins. 1. **Local cache** — Instant if already downloaded. Exact versions never expire; bare names check staleness after 24 hours. 2. **Binstall metadata** — Reads the crate author's download URL from Cargo.toml `[package.metadata.binstall]`. Any crate that works with cargo-binstall works with crgx automatically. 3. **GitHub Releases** — Matches a release asset by your target triple (e.g. x86_64-unknown-linux-gnu). Tries multiple tag formats: v1.0.0, 1.0.0, crate-v1.0.0, crate-1.0.0. 4. **QuickInstall** — Falls back to cargo-quickinstall's pre-built binary registry. 5. **cargo build** — Opt-in with `--allow-build`. Compiles from source as a last resort. --- ## Use Cases ### MCP Servers Drop into any MCP configuration. No pre-install step required. crgx downloads automatically without prompting. ```json { "command": "crgx", "args": ["fossil-mcp"] } ``` ### CI/CD No `cargo install` step burning CI minutes. ```yaml - run: crgx cargo-tarpaulin -- --out xml ``` ### One-off tools Try any Rust tool without committing to a global install. ```bash crgx cargo-audit crgx tokei . crgx cargo-expand ``` ### Version pinning Lock a specific version for reproducible builds and workflows. ```bash crgx tokei@14.0.0 . crgx ripgrep@14.1.1 -- -i pattern ``` --- ## How It Works On first run, crgx resolves the crate from crates.io, downloads a pre-built binary through the resolution chain, and caches it locally. Then it calls exec() — the crgx process is replaced entirely by the target binary. This means zero overhead at runtime: signals pass through, exit codes are preserved, and the tool behaves exactly as if installed natively. Subsequent runs hit the cache and execute immediately. --- ## Network Resilience crgx is designed to work reliably in poor network conditions: - **Timeouts**: 30-second timeout for API calls, 5-minute timeout for downloads - **Retries**: Automatically retries on transient errors (5xx, network failures) with exponential backoff - **Offline fallback**: When the network is unavailable and a cached version exists, crgx uses it instead of failing - **Stale cache**: If a staleness check fails due to network issues, the existing cached version is used --- ## Comparison with Similar Tools | Tool | What it does | Compile? | Cache? | One command? | |------|-------------|----------|--------|-------------| | **crgx** | Fetch + cache + run pre-built binary | No | Yes | Yes | | cargo install | Compile from source and install globally | Yes (slow) | No | Yes | | cargo binstall | Install pre-built binary globally | No | No | Yes | | cargo-quickinstall | Install pre-built binary globally | No | No | Yes | | npx (Node.js) | Run npm package binary without installing | N/A | Partial | Yes | | uvx (Python) | Run Python tool without installing | N/A | Yes | Yes | | bunx (Bun) | Run npm package binary without installing | N/A | Yes | Yes | **crgx vs cargo install**: cargo install compiles from source, which can take minutes. crgx downloads pre-built binaries in seconds. crgx also caches binaries and runs them directly without global installation. **crgx vs cargo binstall**: cargo binstall installs binaries globally into ~/.cargo/bin. crgx keeps binaries in its own cache and runs them ephemerally — no global namespace pollution. crgx uses the same resolution chain as cargo binstall, so any crate compatible with binstall works with crgx. --- ## FAQ **What is crgx?** crgx is a command-line tool that runs any Rust crate binary instantly without cargo install. It fetches pre-built binaries, caches them, and executes them in a single command. Think of it as npx for the Rust ecosystem. **How do I pronounce crgx?** "cargo-x" or just spell it out: C-R-G-X. **Does crgx compile from source?** By default, no. crgx downloads pre-built binaries from multiple sources (binstall metadata, GitHub Releases, cargo-quickinstall). You can opt into compilation with the --allow-build flag. **Does crgx work offline?** Yes, if the binary is already cached. Use `--offline` to ensure no network access. crgx also falls back to cached versions automatically when the network is unavailable. **Is crgx compatible with cargo-binstall?** Yes. crgx uses the same binstall metadata format from Cargo.toml. Any crate that works with cargo binstall works with crgx automatically. **How do I use crgx with MCP servers?** Add `{"command": "crgx", "args": [""]}` to your MCP configuration. crgx downloads automatically without prompting. **Where are binaries cached?** Linux: ~/.cache/crgx/, macOS: ~/Library/Caches/crgx/, Windows: %LOCALAPPDATA%\crgx\cache. **How do I clear the cache?** Run `crgx --cache-clean` to remove all cached binaries. --- ## Contributing See CONTRIBUTING.md for development setup and guidelines. Repository: https://github.com/yfedoseev/crgx ## License MIT — see LICENSE for details.