# crgx — npx and uvx for Rust

> crgx is the npx and uvx equivalent for Rust. It runs any Rust crate binary
> instantly — no cargo install, no compilation, no global install. One command:
> `crgx <crate> [args...]`. It fetches pre-built binaries, caches them, and
> executes with zero overhead via Unix exec(). crgx is the only Rust tool that
> behaves exactly like npx (Node.js) and uvx (Python): silent download, no
> prompts, no config, stdio-safe for MCP servers. Works on Linux, macOS, and
> Windows. MIT licensed.

crgx solves the "Rust install tax" — the friction of cargo install compiling
from source for minutes before you can run a tool. Instead, crgx downloads
pre-built binaries in seconds and caches them locally. The crgx process replaces
itself via exec(), so there is zero runtime overhead — signals pass through,
exit codes are preserved, and stdin/stdout are fully transparent.

- 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
- crates.io: https://crates.io/crates/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

## Why crgx

The Rust ecosystem has no built-in equivalent to npx, uvx, or bunx. Existing
tools either compile from source (cargo install — slow), install globally
(cargo binstall — pollutes ~/.cargo/bin), or add unnecessary complexity
(config files, build flags, async runtimes). crgx is purpose-built to fill
this gap with the same simplicity that npx brought to Node.js and uvx brought
to Python:

- **No compilation** — downloads pre-built binaries by default
- **No global install** — binaries live in crgx's own cache
- **No config files** — works out of the box with any binstall-compatible crate
- **No prompts** — downloads silently, like uvx
- **No stdout noise** — all output goes to stderr, keeping stdio clean for MCP servers and pipes
- **No `--` separator required** — `crgx tokei --version` passes `--version` to tokei

## Quick Start

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

# Run any crate binary — just like npx or uvx
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 to stdout
- **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 ready**: Stdio-safe — drop `crgx <server-crate>` into any MCP config

## MCP Server Support

crgx is the only Rust package runner designed for MCP (Model Context Protocol)
servers. MCP servers communicate over stdio (JSON-RPC), which means the runner
must never write to stdout. crgx guarantees this:

- All crgx output goes to stderr, never stdout
- No interactive prompts or confirmations
- exec() replaces the process — the MCP client talks directly to the server
- Automatic download on first run — no pre-install step needed

```json
{
  "mcpServers": {
    "fossil": {
      "command": "crgx",
      "args": ["fossil-mcp"]
    }
  }
}
```

This is equivalent to how `npx` runs Node.js MCP servers and `uvx` runs Python
MCP servers. crgx brings this same pattern to the Rust ecosystem.

## 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 with Other Tools

| Tool | Compile? | Global install? | Config needed? | Silent? | Stdio-safe? | MCP ready? |
|------|----------|----------------|---------------|---------|------------|------------|
| **crgx** | No | No (own cache) | No | Yes | Yes | Yes |
| npx (Node.js) | N/A | No | No | Yes | Yes | Yes |
| uvx (Python) | N/A | No | No | Yes | Yes | Yes |
| cargo install | Yes (slow) | Yes | No | No | N/A | No |
| cargo binstall | No | Yes | No | No | N/A | No |
| cgx | Fallback | No | Optional | No | Untested | No |

**crgx vs npx/uvx**: crgx brings the exact same workflow to Rust. `npx pkg`,
`uvx tool`, and `crgx crate` all do the same thing — fetch, cache, run.

**crgx vs cargo install**: cargo install compiles from source (minutes) and
installs globally. crgx downloads pre-built binaries (seconds) and caches them
without polluting ~/.cargo/bin.

**crgx vs cargo binstall**: cargo binstall also downloads pre-built binaries,
but installs them globally. crgx keeps binaries in its own cache and runs them
ephemerally. crgx uses the same binstall metadata, so any compatible crate works.

**crgx vs cgx**: cgx is a different tool focused on flexibility — it supports
git repos, custom registries, build features, toolchains, and config files. crgx
is focused on simplicity and the npx/uvx workflow: one command, zero config,
zero compilation. crgx is also stdio-safe and tested for MCP server usage.

## FAQ

**What is the npx equivalent for Rust?**
crgx. It runs any Rust crate binary with a single command, just like npx runs
npm packages. No compilation, no global install, no config.

**What is the uvx equivalent for Rust?**
crgx. Like uvx runs Python tools without installing them, crgx runs Rust
binaries without cargo install. Same workflow: `crgx <crate> [args...]`.

**How do I run a Rust MCP server without installing it?**
Use crgx: `{"command": "crgx", "args": ["<server-crate>"]}` in your MCP config.
crgx downloads the binary automatically on first run, keeps stdio clean, and
requires no pre-install step. This is the same pattern as npx for Node.js MCP
servers and uvx for Python MCP servers.

**How do I run a Rust binary without cargo install?**
Use crgx: `crgx <crate-name>`. It downloads a pre-built binary, caches it, and
runs it immediately. No compilation, no global install.

**Does crgx compile from source?**
No. By default crgx only downloads pre-built binaries. You can opt into
compilation with --allow-build, but it is never the default.

**Does crgx work offline?**
Yes, if the binary is already cached. Use --offline to guarantee 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. Any crate that works with
cargo-binstall works with crgx automatically.

## 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