A ready-to-use starting point for small, fast Rust command-line utilities. The project already connects argument parsing, configuration, errors, streaming I/O, tests, native binary packaging, CI, and instructions for coding agents.
Use this template · First command · Architecture · Agent workflow
Start with a useful synchronous command, then spend the first product change on
what your users need. The included stats example scans files or stdin using a
fixed 64 KiB buffer. It does not need a server, database, asynchronous runtime,
network access, or user configuration to run.
Install Rust through rustup, with your platform's normal native linker. The repository selects Rust 1.98.1 and the formatter/Clippy components automatically. Python 3.9+ is used for initialization and repository maintenance; ordinary application development uses Cargo. The minimum supported compiler is also Rust 1.98.1. The template follows the current stable baseline; it no longer targets Rust 1.85.1.
Create your repository using GitHub's Use this template button, or:
gh repo create my-tool --template Dankosik/rust-cli-template --public --clone
cd my-tool
python3 scripts/init.py --name my-tool --repository https://github.com/your-name/my-tool
cargo test --locked
cargo run --locked -- --helpOn Windows, use python where your installation does not provide python3.
The optional Makefile shortcuts require Make; every underlying command is
available directly.
Try the included command before or after initialization:
cargo run --locked -- stats README.md
cargo run --locked -- --format json stats README.md
cargo run --locked -- --config examples/config.toml stats README.md
cargo run --locked -- completions bash
cargo build --locked --releaseWith alpha\nbeta on stdin, JSON output is exactly:
{"bytes":10,"lines":1}The initializer changes package/crate identity, executable references,
environment prefix, repository links, and optional description. It also writes
a consumer README from .template/README.md. Use --dry-run
to inspect the patch. It validates before writing, preserves dependency versions
and checksums, and leaves Git state for you to review and commit. Repeating the
same identity is a no-op; a later different rename is an explicit project change.
Vendored skills and upstream attribution remain unchanged.
| Area | Included |
|---|---|
| CLI contract | clap arguments/subcommands, typed values, help/version, generated shell completions |
| Configuration | Explicit bounded TOML file, environment overrides, CLI precedence, unknown-field rejection |
| Output and errors | Stable text/JSON, distinct stdout/stderr, intentional exit status, fallible final output |
| Streaming core | Byte-safe scanning with memchr, fixed buffer, short-read/Interrupted handling, checked count growth |
| Tests | Focused core tests plus real binaries, pipes, config, native paths, output failure and subprocess cleanup |
| Rust tooling | Pinned toolchain, lockfile, formatter, Clippy, profiling profile, editor recommendations |
| CLI toolbox | Collections, byte strings, traversal, glob filters, temporary files, progress, logging, and application errors |
| CI | Linux/macOS/Windows tests, declared minimum Rust 1.98.1, dependency advisories/licenses, renamed-consumer validation |
| Delivery | Native archives for Linux, both macOS architectures, and Windows; extracted-binary smoke tests and checksums |
| Agents | Shared AGENTS.md, Claude/Copilot pointers, 16 vendored Rust skills with immutable provenance |
| Adoption | Safe identity initializer, integrity checks, explicit pinned skill updates, first-command guide |
Direct dependencies have specific jobs: clap and clap_complete own command
parsing and completion generation; serde, serde_json, and toml handle typed
formats; thiserror preserves error meaning; memchr supplies optimized byte
search. The predeclared toolbox adds anyhow, itertools, bstr, walkdir,
ignore, globset, tempfile, indicatif, log, and env_logger. assert_cmd
is available in dev-dependencies for ordinary CLI tests. Cargo.toml
and Cargo.lock are the dependency authorities.
Consult the matching library-guide entry when adding technical mechanics or choosing a dependency; known project/std APIs do not need another full catalog review. It maps needs to APIs and resource tradeoffs. The toolbox is deliberately available before the first product command; the sample does not manufacture uses of every crate. Chosen default features avoid unrelated WebAssembly progress support, Unicode tables for byte-only helpers, and timestamp/message-regex logging features. The full research record and 78-crate catalog are dated background evidence, not a mandatory reading list for ordinary changes.
The release profile uses ordinary optimized Rust with thin LTO and keeps unwind semantics. It makes no CPU-native assumptions. Startup, throughput, resident memory, and binary size still depend on the real workload; see performance measurement.
stats [INPUT] reads stdin when INPUT is omitted or -. It counts all raw bytes
and LF terminators, matching the newline convention of wc -l. An unterminated
tail contributes bytes but no extra line. Input does not need to be UTF-8.
Global options can appear before or after the subcommand:
--format text|jsonoverridesRUST_CLI_TEMPLATE_FORMAT, then the explicit config file'sformat, then the defaulttext.--config PATHoverridesRUST_CLI_TEMPLATE_CONFIG. No configuration file is discovered implicitly from the working directory or home directory.- An explicitly selected config is validated even when a flag overrides its value. Invalid configuration fails before opening the command's input.
- Help, version, and
completions SHELLdo not load config or consume stdin.
After initialization, my-tool uses the prefix MY_TOOL instead. Available
completion shells are listed by completions --help.
Successful results go to stdout; operational diagnostics go to stderr. Exit 0 means success, including a downstream stdout pipe deliberately closed by its reader; exit 1 means an operation failed; exit 2 means invalid command usage. Read errors and unrelated output failures remain failures. Ctrl+C uses the operating system's default behavior. A command that later owns persistent writes or child processes must define the cleanup it needs.
| Command | Purpose |
|---|---|
cargo test --locked |
Test Rust behavior, including the real CLI |
cargo fmt --all -- --check |
Check formatting |
cargo clippy --locked --all-targets -- -D warnings |
Compiler/lint feedback |
cargo build --locked --release |
Build the optimized executable |
make check |
Formatting, Clippy, all-target tests and doctests |
make template-check |
Pinned skills, local links, and maintenance tests without a Rust build |
make verify |
Combines check and template-check |
make template-smoke |
Initialize and test a disposable consumer |
make audit |
Advisories, licenses, and sources using cargo-deny |
For local dependency policy checks, install the tool version used by CI:
cargo install cargo-deny --version 0.20.2 --locked
cargo deny checkThe CI jobs use pinned action revisions and expose one aggregate required
check for branch protection. Ordinary changes need matching focused local
proof; they do not require repeated full validation or a new specification file.
See CONTRIBUTING.md for contribution and validation details.
Ask your coding agent to implement the requested behavior in this repository. AGENTS.md routes it to the relevant Rust skills and actual validation commands. Clear implementation tasks proceed directly to code; review-only tasks stay read-only. Larger tasks can record concise decisions and split independent work across available agents. Agent evaluation provides optional scenarios on this template; it is not a mandatory implementation stage.
docs/first-command.md shows where to add or replace a
subcommand and its tests. Replace the demonstration command, its tests, the
release smoke case in scripts/release.py, and performance examples together.
Initialized consumers' CI does not require keeping stats as a permanent feature.
The 16 skills are vendored from Dankosik/rust-cli-skills. They are available immediately, without an installer or live download. To update from a reviewed local checkout, supply an exact upstream commit:
python3 scripts/sync_skills.py --source ../rust-cli-skills --revision FULL_COMMIT_SHA --check
python3 scripts/sync_skills.py --source ../rust-cli-skills --revision FULL_COMMIT_SHA --apply--check returns 1 when an update is available; it writes nothing. Application
files and locally changed skills are protected from replacement.
skills-source.json records the exact upstream revision
and hashes. Duplicate per-skill license files are omitted only when their bytes
are already retained in the root LICENSE; other resources or notices need review.
For an instruction-only update, review the diff and run make template-check;
add Rust/consumer checks when their corresponding inputs change. See
agent workflow for the update and validation boundaries.
docs/releasing.md describes the native target matrix,
compatibility boundaries, archive verification, and tag-driven GitHub Releases.
Manual release-workflow runs verify packages without publishing. A matching v
tag publishes only after CI and every native archive check succeeds. Source
publication to crates.io remains disabled until you intentionally configure it.
This adapts the ready-to-run, contract, initialization, validation, and agent workflow ideas of Dankosik/go-service-template-rest to Rust CLI development. Template design explains the adaptation. The Rust skills provide the technical foundation.