# 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 — signals
pass through and exit codes are preserved.

- Install: `brew install yfedoseev/tap/crgx` or `cargo install crgx`
- Shell installer: `curl -fsSL crgx.dev/install.sh | sh`
- Windows: `irm crgx.dev/install.ps1 | iex`
- Source code: https://github.com/yfedoseev/crgx
- Full documentation: https://crgx.dev/docs
- Full documentation in one file: https://crgx.dev/llms-full.txt

## Documentation

- [README](https://raw.githubusercontent.com/yfedoseev/crgx/main/README.md): Full usage guide with install methods, flags, version pinning, and examples
- [Documentation](https://crgx.dev/docs): Complete reference with resolution chain, cache management, and use cases

## Quick Start

```bash
# Install
brew install yfedoseev/tap/crgx

# Run any crate binary
crgx tokei .                       # count lines of code
crgx ripgrep -- -i "pattern" src/  # search files
crgx cargo-audit                   # security audit
crgx hyperfine "echo hello"       # benchmark a command

# Version pinning
crgx tokei@14.0.0 .               # exact version, cached forever
crgx tokei@latest .                # force latest from registry
```

## Key Features

- **Zero config**: Works with any crate that has binstall metadata or GitHub Releases
- **Smart caching**: 24h staleness for bare names, exact versions cached forever, offline fallback
- **Silent by default**: Downloads automatically without prompting, no output unless --verbose
- **Native execution**: Unix exec() replaces the crgx process entirely — zero overhead
- **Network resilient**: Falls back to cached binaries when offline, retries on transient errors
- **MCP server support**: Drop `crgx <server-crate>` into any MCP config

## Use Cases

- **MCP servers**: `{"command": "crgx", "args": ["fossil-mcp"]}` — no pre-install step
- **CI/CD**: `crgx cargo-tarpaulin -- --out xml` — no cargo install burning CI minutes
- **One-off tools**: Try any Rust tool without committing to a global install
- **Version pinning**: Lock specific versions for reproducible builds and workflows

## Resolution Chain

crgx tries each source in order: local cache, binstall metadata from Cargo.toml,
GitHub Releases asset matching, cargo-quickinstall pre-built registry, and
optionally cargo build (with --allow-build flag).

## Comparison

| 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 | No | Yes |
| cargo binstall | Install pre-built binary globally | No | No | Yes |
| npx (Node.js) | Run npm package binary without installing | N/A | Partial | Yes |

## Optional

- [Contributing](https://raw.githubusercontent.com/yfedoseev/crgx/main/CONTRIBUTING.md): Development setup and contribution guidelines
- [Changelog](https://raw.githubusercontent.com/yfedoseev/crgx/main/CHANGELOG.md): Version history
- [Security](https://raw.githubusercontent.com/yfedoseev/crgx/main/SECURITY.md): Security policy and binary provenance