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:
Installing rustuse-cli provides two binaries:
rustuse
cargo-rustuse
The cargo-rustuse binary allows Cargo to invoke RustUse as a Cargo subcommand:
For example, these command pairs are equivalent:
Quick start
Search the RustUse catalog:
Inspect a catalog entry:
Preview adding a RustUse crate:
Add the dependency through Cargo:
Inspect the current project:
Run rustuse without a subcommand in an interactive terminal to open the guided menu:
Command surface
Run rustuse <command> --help for the complete arguments and options supported by a command.
Discovery and adoption
Project tools
Catalog tools
Maintainer tools
Run rustuse dev without a dev subcommand to open the guided maintainer menu.
Automation
CLI utilities
Global flags
Global flags may be supplied before or after a subcommand:
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.
Use --limit to restrict the number of results:
info
Shows catalog metadata for a RustUse crate, primitive, facade, or package.
add
Adds a RustUse crate as a Cargo dependency.
RustUse validates the requested catalog entry and delegates dependency installation to Cargo.
Preview the operation without modifying the project:
remove
Removes a RustUse dependency through the current project workflow.
Use rustuse remove --help for the current path and selection options.
list
Shows RustUse project tracking or catalog entries.
outdated
Finds outdated RustUse crate and primitive dependencies.
update
Updates RustUse Cargo dependencies used by the current project.
update changes project dependencies. It does not upgrade the installed RustUse CLI.
Project tools
init
Initializes optional RustUse project tracking with rustuse.toml.
Preview the planned files and directories without writing them:
RustUse configuration is optional for Cargo-only adoption.
check
Checks a Cargo project and its optional RustUse tracking state.
diff
Shows differences detected by the current RustUse project workflow.
doctor
Diagnoses RustUse CLI, Cargo, environment, and project configuration problems.
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.
Catalog tools
The catalog command exposes lower-level catalog discovery, generation, inspection, search, and validation workflows.
Discover local entries
Generate catalog artifacts
Validate catalog state
Inspect an entry
Search entries
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
Inspection analyzes repository shape and reports findings without writing managed changes.
Generate a facade report
The default facade report file is:
rustuse-report.md
A 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:
The default fleet report file is:
rustuse-fleet-report.md
The 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:
Apply all selected repairs:
By 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:
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 configuration
A 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.
Fail the command when warnings are found:
The 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:
The 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:
Preview the Cargo command without running it:
The upgrade workflow uses:
cargo install rustuse-cli --force --locked
upgrade 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:
Verify formatting:
Build the CLI:
Run tests:
Run tests with all features:
Run Clippy with warnings denied:
Generate private-item documentation without opening a browser:
Generate documentation and open it:
Install the current local build:
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.