rust-cargo-cli

An npm CLI package that automatically installs the Rust toolchain for your current platform and exposes it as cargo, rustc, rustup, rustfmt, rustdoc, cargo-clippy and cargo-fmt terminal commands.

Under the hood it downloads the official rustup installer from static.rust-lang.org and runs it in non-interactive mode, keeping the whole toolchain inside the package — no system-wide changes, no shell profile edits.

Supported platforms

| OS | Arch | rustup-init target | Default toolchain host | |---------|-------|---------------------------------------|-------------------------------| | Linux | x64 | x86_64-unknown-linux-gnu / -musl | same as rustup-init target | | Linux | arm64 | aarch64-unknown-linux-gnu / -musl | same as rustup-init target | | macOS | x64 | x86_64-apple-darwin | same as rustup-init target | | macOS | arm64 | aarch64-apple-darwin | same as rustup-init target | | Windows | x64 | x86_64-pc-windows-msvc | x86_64-pc-windows-gnu | | Windows | arm64 | aarch64-pc-windows-msvc | aarch64-pc-windows-msvc |

On Windows x64 the x86_64-pc-windows-gnu toolchain is installed by default: it ships its own linker (rust-mingw), so Visual Studio Build Tools are not required. Set RUST_CARGO_CLI_WINDOWS_HOST=msvc if you prefer the MSVC target.

Toolchain versions are resolved from the official Rust distribution channel: https://static.rust-lang.org/dist/channel-rust-<toolchain>.toml.

Installation

Global (recommended)

npm i -g --allow-scripts=rust-cargo-cli rust-cargo-cli@latest

npm v11+: npm blocks install-time lifecycle scripts (preinstall / install / postinstall) of registry packages by default, so they must be allowed explicitly. --allow-scripts=rust-cargo-cli allows this package's postinstall script to run and install the Rust toolchain into the package's dist/ folder. The flag is ignored on npm < 11, so the command works there as well.

Verify that the toolchain is installed and working:

cargo --version && rustc --version

Local (per-project)

npm install rust-cargo-cli
npx cargo --version

For local installs, npm v11+ also skips the postinstall script by default. Add an allowScripts entry to your project's package.json and reinstall:

{
  "allowScripts": {
    "rust-cargo-cli": true
  }
}

Alternatively, run node node_modules/rust-cargo-cli/install.js once after npm install.

Dry run

See what would be downloaded and executed, without touching the network or the disk:

node install.js --dry-run     # or: npm run dry-run

IDEs (rust-analyzer, CLion, …) on Windows

Terminal shims (cargo, cargo.cmd, cargo.ps1) are enough for cmd, PowerShell and Git Bash, but IDE tooling spawns cargo / rustc directly through CreateProcess, which only understands real executables — the npm shims are shell scripts, so those tools fail with %1 is not a valid Win32 application (os error 193) unless rust-analyzer.server.extraEnv is configured by hand.

For global installs on Windows the installer wires the toolchain into your user environment automatically (HKCU\Environment, no admin rights required):

• <package>\dist\cargo\bin (the real cargo.exe, rustc.exe, rustup.exe, … rustup proxies) is prepended to the user PATH;
• CARGO_HOME and RUSTUP_HOME are pointed at the bundled dist/cargo and dist/rustup.

Restart VS Code — all windows, not just a window reload — and any open terminals, so they pick up the new environment: VS Code snapshots the environment when the app starts and passes it on to rust-analyzer, so reloading a window keeps the old snapshot.

Manage the integration explicitly:

rust-cargo-cli doctor             # diagnose the install + what IDE tools will see
rust-cargo-cli setup              # (re-)apply the user-environment integration
rust-cargo-cli setup --force      # …and override a pre-existing Rust toolchain
rust-cargo-cli setup --dry-run    # show what would change
rust-cargo-cli unsetup            # remove the PATH entry / CARGO_HOME / RUSTUP_HOME again
rust-cargo-cli env                # print the `rust-analyzer.server.extraEnv` snippet

If another Rust toolchain is already present (its cargo.exe is on PATH, or CARGO_HOME / RUSTUP_HOME are set), the integration is skipped so your setup is never hijacked — use --force to override it, or set RUST_CARGO_CLI_NO_ENV=1 to disable the integration entirely.

Local installs do not touch your environment — enable it once with npx rust-cargo-cli setup, or paste the rust-cargo-cli env snippet into your editor settings:

{
  "rust-analyzer.server.extraEnv": {
    "CARGO_HOME": "…\\node_modules\\rust-cargo-cli\\dist\\cargo",
    "RUSTUP_HOME": "…\\node_modules\\rust-cargo-cli\\dist\\rustup",
    "PATH": "…\\node_modules\\rust-cargo-cli\\dist\\cargo\\bin;${env:PATH}"
  }
}

Usage

After a global install:

# Check versions
cargo --version
rustc --version
rustup --version

# Create and run a project
cargo new hello && cd hello
cargo build
cargo run
cargo test

# Formatting and lints (components of the default profile)
cargo fmt
cargo clippy

# Toolchain management
rustup update
rustup default nightly
rustup component add rust-src

Environment variables

| Variable | Default | Meaning | |--------------------------------|--------------------|---------------------------------------------------------------------------------------------| | RUST_CARGO_CLI_HOME | <package>/dist | Base folder holding cargo/ (CARGO_HOME), rustup/ (RUSTUP_HOME) and rustup-init. | | RUST_CARGO_CLI_TOOLCHAIN | stable | Toolchain passed to rustup-init --default-toolchain (e.g. stable, nightly, 1.75.0). | | RUST_CARGO_CLI_PROFILE | default | rustup profile: minimal, default or complete. minimal is much smaller. | | RUST_CARGO_CLI_WINDOWS_HOST | gnu | Windows x64 toolchain flavour: gnu (no Visual Studio needed) or msvc. | | RUST_CARGO_CLI_SKIP | — | Set to 1 to skip the download entirely (useful in containers / CI). | | RUST_CARGO_CLI_NO_ENV | — | Set to 1 to disable the Windows user-environment integration (see the IDE section above). | | RUST_CARGO_CLI_SETUP_ENV | — | Set to 1 to force the integration from install.js for non-global installs. | | RUST_CARGO_CLI_DRY_RUN | — | Set to 1 for a dry run (same as --dry-run). | | HTTPS_PROXY / HTTP_PROXY | — | Passed through to rustup for downloads behind a proxy. |

When RUST_CARGO_CLI_HOME points outside the package, the chosen path is remembered in a .rust-cargo-cli-home marker file, so the cargo/rustc shims keep using it.

Project structure

rust-cargo-cli/
├── bin/
│   ├── cargo.js          # `cargo` CLI wrapper
│   ├── cargo-clippy.js   # `cargo clippy` backend
│   ├── cargo-fmt.js      # `cargo fmt` backend
│   ├── rust-cargo-cli.js # management CLI (setup / unsetup / doctor / env)
│   ├── rustc.js          # `rustc` CLI wrapper
│   ├── rustdoc.js        # `rustdoc` CLI wrapper
│   ├── rustfmt.js        # `rustfmt` CLI wrapper
│   └── rustup.js         # `rustup` CLI wrapper
├── dist/                 # Installed toolchain (created at install time)
│   ├── rustup-init[.exe]
│   ├── cargo/            # CARGO_HOME (bin/rustc, bin/cargo, registry cache…)
│   └── rustup/           # RUSTUP_HOME (toolchains/…)
├── lib/
│   ├── cli.js            # implementation of the `rust-cargo-cli` management CLI
│   ├── download.js       # HTTPS download with redirects, retries and progress
│   ├── env-setup.js      # Windows user-environment integration (PATH / CARGO_HOME / RUSTUP_HOME)
│   ├── manifest.js       # channel-rust-*.toml helpers (static.rust-lang.org)
│   ├── platform.js       # Platform detection + target triples + directories
│   ├── run.js            # Shared "spawn the toolchain binary" logic for all bins
│   └── scripts/          # PowerShell helpers used by env-setup.js
│       ├── read-env.ps1  #   reads HKCU/HKLM environment (raw values + registry kinds)
│       └── write-env.ps1 #   writes HKCU\Environment and broadcasts WM_SETTINGCHANGE
├── install.js            # postinstall script
└── package.json

How it works

1. npm install triggers the postinstall script (install.js).

2. The script detects the OS, CPU architecture and (on Linux) glibc vs musl.

3. It reads the official channel manifest (channel-rust-stable.toml) to report which toolchain version is about to be installed and to verify that the target is published for it.

4. rustup-init is downloaded from the official rustup distribution (https://static.rust-lang.org/rustup/dist/<target>/rustup-init) into dist/.

5. rustup-init runs non-interactively:

   rustup-init -y --no-modify-path --default-host <host> --default-toolchain stable --profile default

   with CARGO_HOME=<package>/dist/cargo and RUSTUP_HOME=<package>/dist/rustup.

6. Every bin/*.js entry point is a thin wrapper: it locates the toolchain binary inside CARGO_HOME/bin, passes CARGO_HOME / RUSTUP_HOME / PATH through and delegates all CLI arguments via child_process.spawnSync (exit codes and signals are forwarded as-is).

7. On Windows the installer also prepends dist\cargo\bin to the user PATH and sets CARGO_HOME / RUSTUP_HOME in HKCU\Environment (global installs only), so IDE tools such as rust-analyzer can spawn the real cargo.exe / rustc.exe. rust-cargo-cli doctor reports the current state, rust-cargo-cli unsetup reverts it.

Linking note — rustc still needs a system linker when a crate compiles C code or links a binary:

• Windows (gnu host): the self-contained rust-mingw linker is used, nothing else is needed.
• Windows (msvc host): Visual Studio Build Tools must be installed.
• macOS: Xcode Command Line Tools (xcode-select --install).
• Linux: gcc / build-essential.

Updating Rust

The toolchain manages itself — just use rustup:

rustup update                 # update all installed toolchains
rustup toolchain install beta # add another toolchain
rustup self update            # update rustup itself

To reinstall from scratch (e.g. after changing RUST_CARGO_CLI_TOOLCHAIN or the Windows host flavour), remove the toolchain directory and re-run the installer:

rm -rf dist              # PowerShell: Remove-Item -Recurse -Force dist
node install.js

Troubleshooting

• Windows: rust-analyzer fails with os error 193 or “cannot find cargo” — the toolchain is not on the user PATH that VS Code sees. Run rust-cargo-cli doctor, then rust-cargo-cli setup and fully quit VS Code (all windows — a window reload keeps the old environment snapshot); a global npm install performs this automatically.
• cargo is not installed — the postinstall script did not run (npm v11+ skips lifecycle scripts by default). Run node node_modules/rust-cargo-cli/install.js, or reinstall globally with npm i -g --allow-scripts=rust-cargo-cli rust-cargo-cli@latest.
• Global install done with sudo — the toolchain landed in a root-owned folder, so cargo cannot write its registry cache. Set a writable home first: RUST_CARGO_CLI_HOME=$HOME/.rust-cargo-cli npm i -g ....
• rustup-init fails behind a proxy — export HTTPS_PROXY / HTTP_PROXY before installing.
• Windows: link.exe not found — you are on the msvc host without Visual Studio Build Tools. Reinstall with RUST_CARGO_CLI_WINDOWS_HOST=gnu (the default for x64).
• Big download size — a full default profile takes roughly 1.5–2 GB on disk (measured: ~1.7 GB for stable on Windows x64). Use RUST_CARGO_CLI_PROFILE=minimal for a much smaller toolchain (rustc + cargo + rust-std only).

License

MIT