# cgx
[](https://github.com/anelson/cgx/actions/workflows/ci.yml)
[](https://crates.io/crates/cgx)
Execute Rust crates easily and quickly. Like `uvx` or `npx` for Rust.
`cgx` lets you run Cargo plugins and other Rust binaries without needing to install them first. It does what you would
otherwise do manually with `cargo install`, `cargo binstall`, `cargo update`, and `cargo run-bin`, but in a single
command.
:warning: **NOTE**: `cgx` is still under active development, and is not yet considered stable. :warning:
## Installation
### Quick Install (Recommended)
**macOS and Linux:**
```sh
**Windows:**
```powershell
The installer will download the appropriate binary for your platform and add it to your PATH.
> **Note:** To install a specific version for CI/reproducible builds, replace `latest` in the URL above with the desired
> version tag from the [Releases page](https://github.com/anelson/cgx/releases), such as `v0.0.10`.
### Alternative Installation Methods
You can also install using Rust tooling:
**Via cargo install:**
```sh
cargo install cgx
```
**Via cargo-binstall (faster, uses pre-built binaries):**
```sh
cargo binstall cgx
```
**Manual download:**
Download prebuilt binaries directly from the [Releases page](https://github.com/anelson/cgx/releases).
---
_Coming soon: Install via `curl https://cgx.sh/install.sh | sh` once the cgx.sh domain is set up._
## GitHub Action
`cgx` ships a GitHub Action that installs `cgx` and puts it on `PATH`, so later steps can
run `cgx <crate>`. It prefers prebuilt binaries but falls back to building from source only when no suitable prebuilt
binary is available for the runner.
### Usage
```yaml
- uses: anelson/cgx@v1
- run: cgx ripgrep -- --version
```
A fuller example:
```yaml
- uses: anelson/cgx@v1
with:
version: "0.0.11" # default: latest release
cargo-cgx: true # also install the `cargo cgx` subcommand
# prefetch specific crates (--prefetch-all is already enabled by default)
prefetch: |
ripgrep@14
cargo-deny
- run: cgx ripgrep -- --version
```
### Inputs
- `version` - cgx version to install (`0.0.11` or `v0.0.11`; leading `v` optional).
- Default: `latest`.
- `target` - target triple to install. When set, downloads that exact prebuilt archive.
- Default: the runner's native target (auto-detected).
- `cargo-cgx` - also install the `cargo-cgx` binary (the `cargo cgx ...` subcommand).
- Default: `false`.
- `github-token` - token for the action's own downloads and prefetch. Never exported to later steps.
- Default: `${{ github.token }}`.
- `cache` - cache cgx's state (resolve cache + downloaded tool binaries) across runs.
- Default: `true`.
- `cache-key-prefix` - prefix for the cache key; bump it to invalidate.
- Default: `cgx`.
- `app-dir` - directory for cgx's state, exported as `CGX_APP_DIR` for later steps.
- Default: a stable per-runner path under the runner tool cache.
- `prefetch-all` - after install, run `cgx --prefetch-all` (uses this repo's `cgx.toml`).
- Default: `true`.
- `prefetch` - newline-separated crate specs to prefetch with `cgx --prefetch`.
- Default: empty (nothing prefetched).
### Outputs
- `version` - the requested version (`latest` or `vX.Y.Z`).
- `cgx-version` - the concrete version reported by `cgx --version`.
- `path` - absolute path to the installed `cgx` binary.
- `app-dir` - the `CGX_APP_DIR` used for cgx's state.
### Caching and prefetch
With `cache: true` (the default) the action caches cgx's on-disk state (the resolve cache and the tool
binaries cgx downloads) keyed by OS and architecture, restoring it before your steps and saving it after the
job. The cgx binary itself is downloaded fresh each run.
Prefetch warms that cache at setup time so later `cgx <crate>` steps are instant. `prefetch-all` prepares
every tool and alias in your repository's `cgx.toml` (so run `actions/checkout` before this action, otherwise
there is no `cgx.toml` to read); `prefetch` prepares the crate specs you list. Prefetch failures are reported
as warnings and never fail your build, and any tools prepared successfully are still cached.
### GitHub token
The `github-token` is used only inside the action's own install and prefetch steps; for security reasons it is never
persisted anywhere for re-use in later steps. If you run `cgx` yourself in later steps and want those requests authenticated (to avoid
GitHub's anonymous API rate limits), set the token on those steps where `cgx` is invoked, eg:
```yaml
- run: cgx cargo deny check
env:
GITHUB_TOKEN: ${{ github.token }}
```
### Pinning
`@v1` tracks the latest v1 release of the action. To pin exactly, reference a commit SHA
(`anelson/cgx@<sha>`).
## Runtime Dependencies
`cgx` uses `gix` for git operations, and for git-over-HTTP `gix` uses a curl/OpenSSL transport backend.
The pre-built Linux musl artifacts are fully static: libcurl, OpenSSL, and zlib are statically linked into the binary, so they add
no runtime library dependencies. Other Linux builds (glibc) dynamically link dependencies like `libcurl`, OpenSSL, and `libz`.
If you run a dynamically linked `cgx` in minimal containers or stripped-down environments, make sure the appropriate
shared libraries are present.
## Quick Start
Run a crate by name:
```sh
# Run ripgrep, installing or updating it if needed
cgx ripgrep --version
```
There's a special case if the first argument is `cargo`, which indicates that you want to run a Cargo subcommand that
may be a third-party Cargo plugin:
```sh
# Run `cargo deny`, installing cargo-deny if it is missing
cgx cargo deny --version
```
Like `npx` and `uvx`, `cgx` requires that its own flags come before the crate name, and any flags intended for the
executed crate come after the crate name:
```sh
# Correct: cgx flags before crate name, crate flags after
# This tells `cgx` to build ripgrep with the `serde` feature, and passes `--color=always` to the ripgrep binary
cgx --features serde ripgrep --color=always
# Wrong: --features is passed to ripgrep and `cgx` will use the default features for ripgrep instead of enabling `serde`
cgx ripgrep --features serde --color=always
```
You can also use `--` as an explicit separator:
```sh
cgx ripgrep -- --version
```
## Version Requirements
The default is to use the latest version of the crate. To choose a subset of releases, use the same version requirement
syntax Cargo supports for dependencies:
```sh
# Run the latest release compatible with major version 14
cgx ripgrep@14
# Run the latest release compatible with 14.1
cgx ripgrep@14.1
# Run exactly 14.1.1
cgx ripgrep@=14.1.1
```
You can also pass the version requirement as a `cgx` option before the crate name:
```sh
cgx --crate-version 14 ripgrep
```
> **NOTE:** `cgx --version` (or `cgx -V`) prints the version of `cgx` itself. To specify the semver version requirement
> for the crate that you are running, use the `@VERSION` suffix or the `--crate-version` option shown above. A
> `--version` placed _after_ the crate name is forwarded to the tool (e.g. `cgx ripgrep --version`
> runs `ripgrep --version`).
## Sources
By default, `cgx` resolves crates from crates.io. You can point it at other sources:
```sh
# Local crate or workspace
cgx --path ./tools/my-tool
# Git repository containing a Rust crate called `my-tool`, using the code in the `v1.0.0` tag
cgx --git https://github.com/owner/repo.git --tag v1.0.0 my-tool
# GitHub or GitLab shorthand specifying a repo containing a crate called `my-tool` in the default branch
cgx --github owner/repo my-tool
cgx --gitlab owner/repo my-tool
# Named Cargo registry or direct registry index URL, containing a crate `private-tool`
cgx --registry my-registry private-tool
cgx --index https://registry.example.com/index private-tool
```
For git sources, `--branch`, `--tag`, and `--rev` select the git ref. `--github-url` and `--gitlab-url` can
override the default API URLs to point to self-hosted instances of GitHub and GitLab, respectively.
## Build and Execution Controls
`cgx` builds in release mode by default and defaults to locked dependency resolution, unlike `cargo install`. Use these
flags to change how a crate is built or run:
```sh
# Cargo build options
cgx --features serde --no-default-features ripgrep
cgx --all-features ripgrep
cgx --debug ripgrep
cgx --profile release-with-debug ripgrep
cgx --target x86_64-unknown-linux-musl ripgrep
cgx -j 4 ripgrep
# Lockfile and network behavior
cgx --unlocked ripgrep
cgx --frozen ripgrep
cgx --offline ripgrep
# Build or resolve without executing
cgx --no-exec ripgrep
cgx --list-targets ripgrep
# Select a particular executable target from a crate
cgx --bin rg ripgrep
cgx --example demo some-crate
# Ignore cached data for this invocation
cgx --refresh ripgrep
```
`--no-exec` prints the resolved executable path to stdout. `--list-targets` lists the crate's binary and example targets
without building or executing them.
## Prefetching Crates
You can prepare crates ahead of time so later runs are fast and work offline:
```sh
# Prepare a single crate (download or build) without running it; prints nothing
cgx --prefetch ripgrep
# Prefetch every tool and alias configured across your cgx.toml files
cgx --prefetch-all
```
To see what tools and aliases are configured (and thus would be prefetched with `--prefetch-all`), you can run:
```sh
# List the tools and aliases configured across all cgx.toml files
cgx --list-tools
```
`--prefetch` is equivalent to `--no-exec` but prints nothing on success; once a crate is prefetched it is guaranteed to
be runnable later without network access and without building from source (as long as you don't change build options,
features, or toolchain). `--prefetch-all` is a convenience shortcut equivalent to running `--prefetch` for each
configured tool and alias.
## Configuration Files
One of the handy features of tools like `uvx` and `npx` is that you can pin or customize tools in your workspace. `cgx`
supports this using `cgx.toml` configuration files.
Create a `cgx.toml` file in your project root:
```toml
[tools]
ripgrep = "14.1"
cargo-deny = "=0.17.0"
```
Now, anywhere inside this directory or its subdirectories, `cgx ripgrep` will use a 14.1-compatible ripgrep and
`cgx cargo deny` will use exactly `cargo-deny` 0.17.0.
You can also specify more complex configurations:
```toml
[tools]
# Simple version requirements
ripgrep = "14"
cargo-deny = "=0.17.0"
# Detailed configuration with features
taplo-cli = { version = "1.0", features = ["full"] }
# Default features can be disabled, just like in a Cargo dependency
sccache = { version = "0.8", default-features = false }
# Git repository source
my-tool = { git = "https://github.com/owner/repo.git", tag = "v1.0.0" }
# Custom registry
private-tool = { version = "1.0", registry = "my-registry" }
[aliases]
# Convenient short names
rg = "ripgrep"
taplo = "taplo-cli"
```
Config files are loaded and merged in order of precedence, with later sources overriding earlier ones:
1. System-wide config (`/etc/cgx.toml` on Linux/macOS, platform equivalent on Windows)
2. User config (`$XDG_CONFIG_HOME/cgx/cgx.toml` or platform equivalent)
3. Directory hierarchy from filesystem root to current directory (each `cgx.toml` found)
4. Command-line arguments and `CGX_*` environment-backed CLI options
Use `--config-file <FILE>` to read only one config file and bypass the normal search. See
[`cgx-example.toml`](cgx-example.toml) for a more comprehensive example.
You can use `cgx --list-tools` to see the final merged configuration of tools and aliases that `cgx` will use, after applying all config files and CLI options.
## Prebuilt Binaries
By default, `cgx` tries to use pre-built binaries and falls back to building from source if none are found. The default
provider order is:
1. `binstall`
2. `github-releases`
3. `gitlab-releases`
4. `quickinstall`
You can control this at the command line:
```sh
# Default behavior: try prebuilt binaries, fall back to source builds
cgx --prebuilt-binary auto ripgrep
# Require a prebuilt binary and fail if none are found
cgx --prebuilt-binary always ripgrep
# Never attempt to use a prebuilt binary; always build from source
cgx --prebuilt-binary never ripgrep
# Consider only GitHub releases and Quick Install as sources of prebuilt binaries;
# if neither are found then fall back to building from source
cgx --prebuilt-binary-sources github-releases,quickinstall ripgrep
```
Or in config:
```toml
[prebuilt_binaries]
use_prebuilt_binaries = "auto"
binary_providers = ["binstall", "github-releases", "gitlab-releases", "quickinstall"]
```
To disable prebuilt binaries in config, set `use_prebuilt_binaries = "never"`. An empty `binary_providers` list is only
valid when prebuilt binaries are disabled.
Prebuilt binaries are used only when default features and settings are selected. Custom features, `--all-features`,
`--no-default-features`, custom profiles, custom targets, custom toolchains, `--bin`, or `--example` always cause `cgx` to
build from source instead.
## HTTP Configuration and Proxies
`cgx` makes HTTP requests to download crate metadata, pre-built binaries, and release assets from registries, GitHub,
GitLab, and other providers. These requests can be configured via the `[http]` section in `cgx.toml`, CLI flags, or
environment variables.
```toml
[http]
timeout = "30s"
retries = 2
backoff_base = "500ms"
backoff_max = "5s"
proxy = "socks5://localhost:1080"
```
```sh
cgx --http-timeout 60s --http-retries 3 ripgrep
cgx --http-proxy socks5://localhost:1080 ripgrep
cgx --http-proxy http://user:password@proxyhost:8080 ripgrep
```
HTTP values use this precedence: CLI flags and `CGX_HTTP_*` environment variables, then config files, then Cargo
environment variable fallbacks, then defaults. The Cargo fallbacks are:
| `CARGO_HTTP_PROXY` | `--http-proxy` | HTTP/SOCKS proxy URL |
| `CARGO_HTTP_TIMEOUT` | `--http-timeout` | Request timeout in seconds (integer) |
| `CARGO_NET_RETRY` | `--http-retries` | Number of retry attempts |
The standard proxy variables `HTTPS_PROXY`, `https_proxy`, and `http_proxy` are also honored automatically by the
underlying HTTP library.
For git operations (`--git`, `--github`, `--gitlab`) over HTTP/S, `cgx` applies the same HTTP settings where possible:
proxy, retries and backoff, user agent, and timeout. For git-over-HTTP specifically, `timeout` is used both as a
connection timeout and as a stalled-transfer timeout threshold.
## Cargo Subcommand Package
The `cargo-cgx` crate packages the same `cgx` tool but as a Cargo subcommand:
```sh
cargo install cargo-cgx
cargo cgx ripgrep --version
```
This is functionally the same as running `cgx ripgrep --version`. It exists for users who prefer the `cargo <command>`
style or want `cgx` available as a Cargo plugin.
## AI Use
**For users:**
Agentic coding tools are used by the developers of `cgx`, but subject to the AI policy rules. Be assured that this
project is not vibe-coded Dunning-Kruger slop, but is the product of many years of human experience in Rust and the Rust
ecosystem, solving a real human problem that has been a pain point for the human maintainers and many other human Rust
developers. Users are encouraged to review the source code and docs for themselves, looking for the telltale LLM tics
that pervade the vast expanse of slop now being regurgitated out onto the Internet; we trust that you will not find any.
In particular, you are encouraged to regard this project with skepticism, given how potentially security-sensitive
a tool like this is. Review the security considerations that the maintainers have put into place, and satisfy yourself
that this tool is built responsibly and with care to avoid the pitfalls that one would expect in a performative
vibe-coded clout-chasing garbage project.
**For contributors:**
Contributions to this repo are subject to our [AI Policy](AI_POLICY.md). Please read it carefully before contributing.
## License
Licensed under either of:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.