Expand description
RustUse command-line adoption helper.
This crate powers the rustuse and cargo-rustuse binaries.
Runtime entry points are run, run_cargo_subcommand, and run_from.
Command modules adapt CLI arguments into RustUse workflows.
§RustUse CLI
rustuse is the command-line tool for discovering, adopting, inspecting, validating, and maintaining RustUse crates and repositories.
RustUse focuses on small, composable Rust crates. The CLI helps Rust users find and adopt those crates through Cargo, while providing RustUse maintainers with repository inspection, reporting, repair, and CI workflows.
The RustUse CLI is not a package manager and does not replace Cargo. It is a workflow layer built around Cargo, local repository inspection, and RustUse conventions.
rustuse-cliis currently in beta. Command names, configuration formats, and generated output may change before the first stable release.
§Installation
Install a local development build from this repository:
cargo install --path . --forceInstalling rustuse-cli provides two binaries:
rustuse
cargo-rustuseThe cargo-rustuse binary allows Cargo to invoke RustUse as a Cargo subcommand:
cargo rustuse <command>For example, these command pairs are equivalent:
rustuse search geometry
cargo rustuse search geometry
rustuse info use-geometry
cargo rustuse info use-geometry
rustuse add use-geometry
cargo rustuse add use-geometry§Quick start
Search the RustUse catalog:
rustuse search geometryInspect a catalog entry:
rustuse info use-geometryPreview adding a RustUse crate:
rustuse add use-geometry --dry-runAdd the dependency through Cargo:
rustuse add use-geometryInspect the current project:
rustuse check .
rustuse doctor .Run rustuse without a subcommand in an interactive terminal to open the guided menu:
rustuse§Command surface
Run rustuse <command> --help for the complete arguments and options supported by a command.
§Discovery and adoption
rustuse search <query> [--limit <count>]
rustuse info <name>
rustuse add <crate> [--dry-run]
rustuse remove [path]
rustuse list [path] [--all]
rustuse outdated [path]
rustuse update [path]§Project tools
rustuse init [path] [--dry-run] [--force]
rustuse check [path]
rustuse diff [path]
rustuse doctor [path]
rustuse docs [name] [--api | --workspace]§Catalog tools
rustuse catalog discover [path]
rustuse catalog generate [path] [--output <path>]
rustuse catalog check [path]
rustuse catalog info <name>
rustuse catalog search <query> [--limit <count>]§Maintainer tools
rustuse dev inspect [path]
rustuse dev report [path]
rustuse dev report [path] --fleet
rustuse dev fix [path]
rustuse dev fix [path] --all
rustuse dev fix [path] --all --writeRun rustuse dev without a dev subcommand to open the guided maintainer menu.
§Automation
rustuse ci check [path]
rustuse ci check [path] --deny-warnings§CLI utilities
rustuse completions <shell>
rustuse upgrade [--dry-run]
rustuse ferris§Global flags
Global flags may be supplied before or after a subcommand:
rustuse --verbose search geometry
rustuse search geometry --verbose
rustuse --quiet doctor .
rustuse --json info use-geometry
rustuse --yes dev fix . --all --write
rustuse --non-interactive ci check .Available global flags:
-v,--verboseshows additional execution details.-q,--quietprints only essential output.--jsonemits machine-readable JSON where supported.--yesaccepts safe command-specific defaults without prompting.--non-interactivedisables prompts and fails when required input has no default.
--yes, --non-interactive, and --json require an explicit command. They do not select a default workflow when rustuse or rustuse dev is invoked without a subcommand.
§Adoption model
RustUse crates are adopted through Cargo.
The CLI assists with:
- catalog discovery
- dependency adoption and removal
- documentation lookup
- version inspection and updates
- optional project tracking
- repository validation
- maintainer workflows
External projects can depend on RustUse crates through Cargo without adding RustUse-specific configuration.
Use rustuse init only when a project should opt into optional RustUse-managed state through rustuse.toml.
§Adoption commands
§search
Searches the RustUse catalog for crates and primitives.
rustuse search geometry
rustuse search quant
rustuse search constantsUse --limit to restrict the number of results:
rustuse search geometry --limit 10§info
Shows catalog metadata for a RustUse crate, primitive, facade, or package.
rustuse info use-geometry
rustuse info use-point§add
Adds a RustUse crate as a Cargo dependency.
RustUse validates the requested catalog entry and delegates dependency installation to Cargo.
rustuse add use-geometry
rustuse add use-pointPreview the operation without modifying the project:
rustuse add use-geometry --dry-run§remove
Removes a RustUse dependency through the current project workflow.
rustuse removeUse rustuse remove --help for the current path and selection options.
§list
Shows RustUse project tracking or catalog entries.
rustuse list
rustuse list . --all§outdated
Finds outdated RustUse crate and primitive dependencies.
rustuse outdated
rustuse outdated .§update
Updates RustUse Cargo dependencies used by the current project.
rustuse update
rustuse update .update changes project dependencies. It does not upgrade the installed RustUse CLI.
§Project tools
§init
Initializes optional RustUse project tracking with rustuse.toml.
rustuse init
rustuse init .Preview the planned files and directories without writing them:
rustuse init --dry-runRustUse configuration is optional for Cargo-only adoption.
§check
Checks a Cargo project and its optional RustUse tracking state.
rustuse check
rustuse check .§diff
Shows differences detected by the current RustUse project workflow.
rustuse diff
rustuse diff .§doctor
Diagnoses RustUse CLI, Cargo, environment, and project configuration problems.
rustuse doctor
rustuse doctor .check focuses on project state. doctor is intended for broader diagnosis of the RustUse environment and configuration.
§docs
Prints RustUse website, API, or workspace documentation URLs.
rustuse docs
rustuse docs use-math
rustuse docs use-math --api
rustuse docs use-math --workspace§Catalog tools
The catalog command exposes lower-level catalog discovery, generation, inspection, search, and validation workflows.
§Discover local entries
rustuse catalog discover .§Generate catalog artifacts
rustuse catalog generate .
rustuse catalog generate . --output rustuse-catalog.json§Validate catalog state
rustuse catalog check .§Inspect an entry
rustuse catalog info use-geometry§Search entries
rustuse catalog search geometry
rustuse catalog search geometry --limit 10§Optional configuration
RustUse supports two configuration surfaces:
- standard Cargo package and workspace metadata in
Cargo.toml - optional RustUse-managed project state in
rustuse.toml
Cargo remains authoritative for normal package identity and dependency configuration.
rustuse.toml is intended for RustUse-specific local workflow settings and managed project state. It is not required for projects that only consume RustUse crates through Cargo.
The configuration schema is still evolving during the beta release series. Use the files generated by the installed version of rustuse init as the source of truth for that version.
§Maintainer workflows
Maintainer workflows live under rustuse dev.
They are intended for RustUse facade repositories and development directories containing multiple RustUse repositories.
§Inspect a facade
cd use-fs
rustuse dev inspect .Inspection analyzes repository shape and reports findings without writing managed changes.
§Generate a facade report
cd use-fs
rustuse dev report .The default facade report file is:
rustuse-report.mdA facade report may include:
- facade repository shape
- child crate discovery
- Cargo manifest health
- child crate inventory
- facade feature and dependency wiring
- package and workspace metadata
- standard file consistency
- CI and release surfaces
- documentation surfaces
- recommended actions
§Generate a fleet report
A fleet is a RustUse development directory containing multiple repositories, including use-* facade repositories.
Example:
git_local/
.github/
.github-private/
cli/
docs/
infra/
mcp/
rustuse/
use-geometry/
use-math/
use-quant/
use-*Generate the fleet report:
cd git_local
rustuse dev report . --fleetThe default fleet report file is:
rustuse-fleet-report.mdThe fleet directory does not need to be a Git repository. RustUse inspects the repositories contained within it.
A fleet report may include:
- development directory and repository discovery
use-*facade discovery- Git repository checks
- child crate and Cargo manifest counts
- facade inventory
- issue summaries
- category and metadata validation
- standard file consistency
- recommended actions
§Repair facade drift
Plan repairs without writing changes:
rustuse dev fix .
rustuse dev fix . --allApply all selected repairs:
rustuse dev fix . --all --writeBy default, inspection, reporting, and repair planning are non-writing. rustuse dev fix writes changes only when --write is supplied.
The interactive maintainer menu can select all repairs or specific issue codes:
rustuse dev§Facade maintenance model
A use-* facade should generally be a thin feature-export crate.
Child crates own behavior. Facades coordinate the public surface.
Facade responsibilities commonly include:
- optional child dependencies
- feature flags
- public re-exports
- prelude exports
- workspace metadata
- README discovery tables
- repository-level maintenance files
RustUse checks alignment across surfaces such as:
crates/use-* directories
Cargo.toml workspace dependencies
Cargo.toml facade dependencies
Cargo.toml features
src/lib.rs exports
src/prelude.rs exports
README child tables
documentation catalogs
CI and release configurationA facade must not contain a child crate with the same package name as the facade itself. For example, use-quant must not contain crates/use-quant.
§Continuous integration
RustUse CI commands are designed for deterministic, non-interactive validation in local automation and hosted CI systems.
rustuse ci check .Fail the command when warnings are found:
rustuse ci check . --deny-warningsThe CI surface is intended to remain:
- stable as an automation entry point
- non-interactive
- safe by default
- non-writing
- machine-friendly
Use --json where the selected CI workflow supports structured output.
§Shell completions
Generate a completion script for a supported shell:
rustuse completions bash
rustuse completions zsh
rustuse completions fish
rustuse completions powershellThe generated script is written to standard output so it can be redirected to the appropriate shell configuration location.
§Upgrading the CLI
Upgrade the installed RustUse CLI through Cargo:
rustuse upgradePreview the Cargo command without running it:
rustuse upgrade --dry-runThe upgrade workflow uses:
cargo install rustuse-cli --force --lockedupgrade replaces the installed RustUse CLI. update changes RustUse dependencies in a project.
§Generated artifacts
RustUse workflows may generate local development artifacts such as:
rustuse-report.md
rustuse-fleet-report.md
.rustuse/Generated reports should be deterministic where practical.
Report files may be committed when they are intentionally used as repository health snapshots. Cache and temporary managed state should follow the ignore policy of the repository using RustUse.
§CLI development
Format the code:
cargo fmtVerify formatting:
cargo fmt --checkBuild the CLI:
cargo buildRun tests:
cargo testRun tests with all features:
cargo test --all-featuresRun Clippy with warnings denied:
cargo clippy --all-targets --all-features -- -D warningsGenerate private-item documentation without opening a browser:
cargo doc --no-deps --document-private-itemsGenerate documentation and open it:
cargo doc --no-deps --document-private-items --openInstall the current local build:
cargo install --path . --force§Design principles
The CLI is intentionally conservative.
- Inspection, reporting, checking, and dry-run workflows should be safe to repeat.
- Commands that write managed changes require explicit write-oriented options.
- Cargo remains the dependency and package-management authority.
- Simple Cargo adoption does not require RustUse configuration.
- Command modules parse arguments, adapt them into RustUse workflows, and render results.
- RustUse workflow modules own repository and domain behavior.
- External-system adapters remain focused and reusable.
§License
RustUse is dual-licensed under either:
- Apache License, Version 2.0
- MIT License
You may choose either license at your option.
See LICENSE-APACHE and LICENSE-MIT for details.