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

Website: https://crgx.dev
Source code: https://github.com/yfedoseev/crgx
crates.io: https://crates.io/crates/crgx

---

## Why crgx

The Rust ecosystem has no built-in equivalent to npx (Node.js), uvx (Python),
or bunx (Bun). The standard workflow to run a Rust CLI tool requires
`cargo install`, which compiles from source and can take minutes. Other Rust
tools either install globally (cargo binstall), require config files and build
flags (cgx), or are not Rust-specific (vx).

crgx is purpose-built to be the exact npx/uvx equivalent for Rust:

- **No compilation** — downloads pre-built binaries by default, never compiles unless you opt in
- **No global install** — binaries live in crgx's own cache, not ~/.cargo/bin
- **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
- **No async runtime** — minimal dependencies, small binary

The workflow is identical across ecosystems:

| Ecosystem | Command | What it does |
|-----------|---------|-------------|
| Node.js | `npx cowsay hello` | Fetch + run npm package |
| Python | `uvx ruff check .` | Fetch + run Python tool |
| Bun | `bunx prettier .` | Fetch + run npm package |
| **Rust** | **`crgx tokei .`** | **Fetch + run Rust crate binary** |

---

## 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] <crate>[@<version>] [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 <name>` | Specify which binary to run (for multi-binary crates) |
| `--offline` | Only run if already cached; no network access |

Only 4 flags. crgx is intentionally minimal — complexity belongs in
the tool you are running, not the runner.

---

## 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. Disabled by default because the whole point of crgx is to avoid
   compilation.

---

## MCP Server Support

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

- **Stdio-safe**: All crgx output (progress, errors, diagnostics) goes to stderr, never stdout
- **No prompts**: No interactive confirmations — downloads happen silently
- **Process replacement**: exec() replaces crgx with the server binary — the MCP client talks directly to the server with zero overhead
- **Automatic download**: First run fetches and caches the binary — no pre-install step

### Example: Claude Desktop / Cursor MCP config

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

This is the same pattern used across all ecosystems:

| Ecosystem | MCP server runner | Example |
|-----------|------------------|---------|
| Node.js | `npx` | `npx @modelcontextprotocol/server-filesystem` |
| Python | `uvx` | `uvx mcp-server-sqlite` |
| **Rust** | **`crgx`** | **`crgx fossil-mcp`** |

Without crgx, running a Rust MCP server requires manual cargo install or cargo
binstall before configuring the MCP client. With crgx, it is a single line in
your config — the binary is fetched automatically on first use.

---

## 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 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 |
| bunx (Bun) | 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 |
| cargo-quickinstall | No | Yes | No | No | N/A | No |
| cgx | Fallback | No | Optional | No | Untested | No |

### crgx vs npx / uvx / bunx

crgx brings the exact same workflow to Rust that npx provides for Node.js, uvx
for Python, and bunx for Bun. The command pattern is identical: `crgx <crate>`,
`npx <package>`, `uvx <tool>`. All fetch, cache, and run without global install.

### crgx vs cargo install

cargo install compiles from source, which can take minutes for large crates.
It also installs binaries globally into ~/.cargo/bin, creating version conflicts
and namespace pollution. crgx downloads pre-built binaries in seconds, caches
them in its own directory, and runs them ephemerally.

### crgx vs cargo binstall

cargo binstall also downloads pre-built binaries, but installs them globally
into ~/.cargo/bin. crgx keeps binaries in its own cache — no global namespace
pollution, no version conflicts. crgx uses the same binstall metadata format,
so any crate compatible with cargo-binstall works with crgx automatically.

### crgx vs cgx

cgx is a different tool with different goals. It focuses on flexibility: git
repos, custom registries, cargo build features, toolchains, profiles, and
config files (cgx.toml). crgx focuses on simplicity and the npx/uvx workflow:
one command, zero config, zero compilation by default. Key differences:

- crgx has 4 flags; cgx has 20+ flags
- crgx requires no config file; cgx supports layered cgx.toml configs
- crgx never compiles by default; cgx always falls back to cargo build
- crgx is stdio-safe and documented for MCP servers; cgx has no MCP support
- crgx uses minimal dependencies (ureq, no async runtime); cgx uses reqwest, gix, figment

---

## FAQ

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

**What is the uvx equivalent for Rust?**
crgx. Like uvx runs Python tools without installing them (`uvx <tool>`), crgx
runs Rust binaries without cargo install. Same workflow, same simplicity.

**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 required.

**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 for
JSON-RPC communication, and requires no pre-install step. This is the same
pattern as npx for Node.js MCP servers and uvx for Python MCP servers.

**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. It is the npx and uvx equivalent 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?**
No. By default crgx only downloads pre-built binaries from multiple sources
(binstall metadata, GitHub Releases, cargo-quickinstall). You can opt into
compilation with the --allow-build flag, but it is never the default behavior.

**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 reads the same `[package.metadata.binstall]` from Cargo.toml. Any
crate that works with cargo-binstall works with crgx automatically.

**How is crgx different from cgx?**
cgx is a broader tool focused on flexibility — it supports git repos, custom
registries, build features, toolchains, and config files. crgx is focused on
simplicity: zero config, zero compilation, stdio-safe for MCP servers. crgx
matches the npx/uvx workflow exactly; cgx is more of a cargo companion tool.

**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.