Scaffold Rust projects (CLI, GUI, TUI, library or workspace) with strict lints, real CI, signed releases, and a house style that checks itself.
In a truecolor terminal the banner animates: every letter takes its own hue and the rule sweeps the spectrum for about a second, then settles. NO_COLOR, pipes and CI get plain text.
npx github:freeknet/create-rust-app # interactive
npx github:freeknet/create-rust-app my-tool --preset cli -y # no questions asked
npx github:freeknet/create-rust-app my-tool --preset cli --with subcommands --bin mt -y
npx github:freeknet/create-rust-app my-gui --preset rustaman --with tray,singleInstance
npx github:freeknet/create-rust-app --preset lib --dry-run --json # see the plan, write nothingNot on npm yet.
npx create-rust-appandnpm create rust-appdon't work: this project hasn't published to npm, and thecreate-rust-appname there belonged to an unrelated package that was unpublished in 2025.npx github:freeknet/create-rust-appinstalls straight from this repository (npm clones and builds it the first time, so the first run takes a little longer). Or run it from a clone:git clone https://github.com/freeknet/create-rust-app && cd create-rust-app npm ci # also builds dist/ node dist/bin/create-rust-app.js my-tool --preset cli -y
Then:
cd my-tool
cargo run
cargo test
cargo clippy --all-targets --all-features -- -D warningsInteractively it's three screens: a name, what you're building, and a review of everything that will be generated in plain words. From the review you Create it, or Customize… any section (crates, app features, tooling, licence and Rust version, post-steps) and come back to it. The finish screen prints the next commands and the one-line command that recreates the project without prompts.
Needs Node 22.18+. Rust is optional at scaffold time; when cargo is on PATH the new project gets
a cargo fetch (and, with --cargo-check, a full cargo check), and you get a
rustup toolchain install hint if the pinned channel is missing.
| Preset | What you get | Kind | Edition | Licence |
|---|---|---|---|---|
rustaman |
single-crate desktop GUI (Windows-first, builds on Linux) · eframe + wgpu · winres icon/manifest · screenshot example | gui |
2024 | MIT |
strobe |
cargo workspace desktop app · winit + glutin + egui_glow · cargo xtask ci / changelog |
workspace |
2024 | MIT + Commons Clause |
cli |
clap + anyhow + env_logger, full tooling | cli |
2024 | MIT |
tui |
ratatui + crossterm terminal app | tui |
2024 | MIT |
lib |
publishable crate · thiserror · docs.rs ready, no binary | lib |
2024 | MIT OR Apache-2.0 |
minimal |
Cargo.toml + lints + main + CI, nothing else | cli |
2024 | MIT |
With no preset (or --preset custom, which means the same) you get the defaults: a single-crate
eframe GUI, edition 2024, MSRV 1.98, toolchain pinned to 1.99.1, every tooling option on. Presets are just partial answers layered on
those defaults (see src/presets.ts); any flag below overrides them.
create-rust-app [dir] [options]
| Flag | Meaning |
|---|---|
[dir] |
Target directory (defaults to the project name) |
--name <kebab> |
Crate / project name, ^[a-z][a-z0-9-]*$, at most 64 characters; not a Rust keyword (fn, type, gen …), test/std/core/alloc/proc-macro, a Cargo-reserved name (build, deps, examples, incremental) or a Windows device name (con, nul …) |
--bin <name> |
Executable name when it differs from the crate (writes [[bin]]; clap, README and release follow it). Lowercase letters, digits, - and _, at most 64 characters, same Cargo and Windows reserved names |
--preset <p> |
rustaman strobe cli tui lib minimal, or custom for no preset (the defaults) |
--kind <k> |
cli gui tui lib workspace |
--gui <stack> |
eframe (wgpu) or winit-glow (winit + glutin + egui_glow) |
--base <theme> |
Surfaces the signature theme lays your accent on: any shipped theme id, e.g. graphite for neutral greys (default midnight) |
--edition <e> |
2024 or 2021 |
--msrv <v> |
rust-version in Cargo.toml (default 1.98); no newer than --toolchain, and at least 1.85 for edition 2024 (1.56 for 2021) |
--toolchain <v> |
Exact channel pinned in rust-toolchain.toml and CI (default 1.99.1) |
--license <l> |
MIT, MIT+CommonsClause, Apache-2.0, MIT OR Apache-2.0 |
--author <name> |
Author for Cargo.toml, LICENSE, headers |
--github <user> |
GitHub handle for CODEOWNERS and repository links |
--accent <#hex> |
Accent colour for GUI themes (default #00e5ff) |
--with a,b |
Turn on features / tooling, e.g. --with tray,commandPalette, or --with subcommands for a CLI built on a clap Subcommand enum (on a desktop app: headless jobs beside the window) |
--without demo |
Start a desktop app from one empty page instead of the overview / palette / about showcase |
--without a,b |
Turn them off, e.g. --without release,dependabot |
--set <key.path=value> |
Set any answer directly (repeatable), e.g. --set tagline="Fast grep", --set crates.async=tokio. The only way to set tagline / displayName without prompts. true/false become booleans |
-y, --yes |
Accept defaults for anything not given; no prompts |
--no-git |
Skip git init -b main and the initial commit |
--no-fetch |
Skip cargo fetch after writing (on by default: seconds, not minutes) |
--cargo-check |
Also run cargo check --all-targets (off by default; a GUI project compiles eframe/wgpu) |
--no-cargo-check |
Skip cargo check even if a preset turns it on |
--open <editor> |
Open the project in code or cursor when done |
--dry-run |
Print the plan, write nothing |
--json |
Machine-readable output: prints only { answers, files } on stdout (notes go to stderr). Without --dry-run it still writes the files, but skips cargo fetch, git, cargo check and --open; answers.post shows what was asked, not what ran |
--no-color |
Plain output (also honoured: NO_COLOR, non-TTY, CI) |
--quiet |
Only errors |
--force |
Write into a non-empty directory; lists the existing files it overwrote on stderr |
--help, --version |
The usual |
A non-TTY stdin implies --yes. Answer flags apply left to right, so a later --set or
--without overrides an earlier one. --help lists every --with / --without name.
Every project carries the same lint block (single crates in [lints], workspaces in
[workspace.lints] with [lints] workspace = true per crate):
[lints.rust] |
level | [lints.clippy] |
level |
|---|---|---|---|
warnings |
deny | unwrap_used |
deny |
dead_code |
deny | expect_used |
deny |
missing_docs |
deny | panic |
deny |
unreachable_pub |
forbid | todo / unimplemented / unreachable |
deny |
unused_imports |
forbid | wildcard_enum_match_arm |
deny |
unused_must_use |
forbid | match_wildcard_for_single_variants |
deny |
unreachable_patterns |
forbid | allow_attributes |
deny |
unsafe_op_in_unsafe_fn |
deny | undocumented_unsafe_blocks |
deny |
non_snake_case & friends |
deny | missing_safety_doc |
deny |
One deliberate exception: projects that log with tracing get unused_imports = "deny" instead of
forbid, because tracing's event macros expand to #[allow(unused_imports)], which forbid turns
into a hard error (E0453).
Exceptions are written #[expect(lint, reason = "…")], never #[allow]. Tests return
anyhow::Result<()> and every assert! carries a message. Release profile: LTO, one codegen
unit, panic = "abort", plus a release-fast profile for quick optimised builds.
Every .rs file opens with the same banner, and the Module: line is derived from the path:
// ============================================================================
// Module: gui::ui::theme
// Description: Palette and egui visuals derived from the active theme.
//
// Dependencies: egui
// ============================================================================
//! Theme bindings for egui.
src/lib.rs → my_app (library crate root), src/main.rs → my_app (binary crate root),
tests/x.rs → x (integration test), and workspace crates get their crate as a prefix
(crates/neon-app/src/cli.rs → neon_app::cli). A generated src/header_check.rs test walks the crate and fails the build
when a banner drifts.
GUI projects keep FFI in src/win/ (and the GL loader in src/gui/run/ for the winit + glow
runtime) only, one call per private safe function, a // SAFETY:
comment on each, and Drop types that own every handle. src/unsafe_check.rs enforces it.
rust-toolchain.toml pins an exact channel with clippy + rustfmt. tests/toolchain_pin.rs
checks that every workflow's toolchain: "…" matches it, so CI and your laptop never disagree.
ci.yml: format, cargo-deny, Windows (clippy-D warnings, test, release build) and Linux jobs; concurrency-cancelled,contents: read, a timeout on every job, every action pinned to a full commit SHA.release.yml: push av*tag → draft release → build and zip per target → CycloneDX SBOM + SHA-256 → build-provenance and SBOM attestations → publish. A tag-vs-Cargo.toml check runs first.- Dependabot (cargo + github-actions, weekly, grouped), CODEOWNERS, issue forms, PR template,
SECURITY.md, and agent docs (
AGENTS.md,CLAUDE.md) if you want them.
deny.toml with an explicit licence allow-list, unknown-registry / unknown-git denied,
yanked crates warned, and duplicate versions surfaced.
Templates live in templates/<group>/files/**. Groups apply in order and later ones win on the
same path, so a feature group can replace a base file. Inside any text file:
// @if gui_eframe & !tray
use eframe::egui;
// @end
pub const NAME: &str = "@@displayName@@";@@token@@is substituted (unknown tokens throw, so typos fail tests loudly).@if/@elif/@else/@endlines after any comment leader are evaluated against the context flags and removed._gitignorebecomes.gitignore,.tmplis stripped, binaries are copied raw.- Cargo.toml and deny.toml are composed in JavaScript (
src/gen/), and groups declare crates throughtemplates/<group>/deps.jsinstead of editing Cargo.toml.
The full rules (Ctx shape, flags, tokens, manifests, the GUI runtime seam) are in docs/CONTRACTS.md; the design is in docs/PLAN.md.
npm ci
npm run typecheck # tsc, strict
npm test # node --test, straight from the .ts sources
npm run build # dist/, what npm publishes
node scripts/scaffold-check.mjs <preset> # scaffold + fmt + clippy -D warnings + test
node scripts/scaffold-check.mjs <preset> --gate check # cargo check only, faster
node scripts/scaffold-check.mjs cli --set crates.async=tokio --set crates.http=reqwestStrict TypeScript with only two runtime dependencies (@clack/core, picocolors). Node runs
the .ts sources directly during development, but it won't strip types inside node_modules,
which is where npx runs from, so the package ships compiled JS from dist/. Shared shapes
(Answers, Ctx, Dep, PlanEntry) live in src/types.ts.
Every preset must come out passing cargo fmt --check,
cargo clippy --all-targets --all-features -- -D warnings and cargo test. Commits use
conventional prefixes (feat:, fix:, docs:, test:, build:, ci: …), and notable changes
go under ## [Unreleased] in CHANGELOG.md.
Everything in assets/brand/ is generated by node scripts/brand.mjs from the same
hue math as the terminal banner, so the README, the social card and the CLI always agree:
| File | Use |
|---|---|
banner-dark.svg / banner-light.svg |
README header (<picture> picks by colour scheme) |
mark.svg / mark-transparent.svg |
the prism mark: six facets in the prompt-bullet colours and a > |
social-preview.svg / .png |
1280×640 card for Settings → Social preview on GitHub |
Palette: prompt stops #ff6ec7 #ff9f6e #ffd36e #b6ff6e #7cf7ff #8a5cff on #0c0b12.
Wordmark hue runs 140° → 266° (green → cyan → violet), with each letter 9° on from the last.
MIT © 2026 Lawrence Norton