README tweaks

Author: mxcl

Cargo.toml

@@ -3,7 +3,7 @@ name = "cargox-cli"
 version = "0.1.0"
 edition = "2024"
 repository = "https://github.com/pkgxdev/cargox"
-description = "Run Cargo binaries on demand, installing them via cargo-binstall when missing."
+description = "`npx` for the cargo ecosystem."
 license = "Apache-2.0"
 
 [[bin]]

README.md

@@ -1,11 +1,24 @@
 # `cargox`
 
 [![CI](https://github.com/mxcl/cargox/actions/workflows/ci.yml/badge.svg)](https://github.com/mxcl/cargox/actions/workflows/ci.yml)
+[![Crates.io](https://img.shields.io/crates/v/cargox-cli.svg)](https://crates.io/crates/cargox-cli)
 
 `cargox` runs Rust binaries on demand, installing them automatically if necessary.
 It mirrors the convenience of `npx` for the Cargo ecosystem while prioritising
 `cargo-binstall` to download prebuilt executables whenever possible.
 
+## Installation
+
+We recommend installing cargo-binstall as well, this significantly speeds up
+use of `cargox`:
+
+```sh
+cargo install cargo-binstall
+cargo binstall cargox-cli
+```
+
+If you don’t want that then you can just `cargo install cargox-cli`.
+
 ## Features
 
 - Executes `crate[@version]` binaries, installing them on demand.
@@ -21,21 +34,26 @@ cargox <crate[@version]> [--] [binary-args...]
 Examples:
 
 ```bash
-# Run the latest wasm-pack, installing it if necessary
-cargox bat ./README.md
+# Run the latest bat that is installed or installing the latest bat if necessary
+$ cargox bat ./README.md
+
+$ cargox bat@latest ./README.md
+# If the installed bat is old we only check for newer if you do this.
+# This is how every foo*x* tool works. We are not being different.
 
 # Install and run a pinned version
-cargox cargo-deny@0.16.3 check
+$ cargox cargo-deny@0.16.3 check
 
 # Force a reinstall, building from source instead of using cargo-binstall
-cargox --force --build-from-source cargo-nextest
+$ cargox --force --build-from-source cargo-nextest
+# ^^ shorter: cargox -fs cargo-nextest
 ```
 
 > [!TIP]
 >
 > - Arguments before the first positional are passed to `cargox`.
-> - Arguments after `--` are passed to the invoked binary.
-> - Use `--` if necessary to define the separation point.
+> - Arguments after the positional argument are passed to the invoked binary.
+> - You can use `--` if necessary to define this separation point.
 
 ### Flags
 

src/cli.rs

@@ -3,9 +3,9 @@ use clap::Parser;
 use std::env;
 use std::ffi::OsString;
 
-/// Run Cargo binaries on demand, installing them via `cargo-binstall` when missing.
+/// Run Cargo binaries on demand
 #[derive(Parser, Debug)]
-#[command(name = "cargox", author, version, about, long_about = None, arg_required_else_help = true)]
+#[command(name = "cargox", author, version, about = "Run Cargo binaries on demand", long_about = None, arg_required_else_help = true)]
 pub struct Cli {
     /// Crate to run, optionally suffixed with `@version`
     #[arg(value_name = "crate[@version]")]

src/installer.rs

@@ -42,9 +42,7 @@ fn install_with_binstall(target: &Target, cli: &Cli, version: &Version) -> Resul
         cmd.arg("--quiet");
     }
     cmd.arg("--no-confirm");
-    if cli.force {
-        cmd.arg("--force");
-    }
+    cmd.arg("--force");
     if let Some(bin) = &cli.bin {
         cmd.arg("--bin");
         cmd.arg(bin);