CARGO-INIT(1)

📦 version 1.89.0, in ubuntu jammy, ubuntu noble

💖 CARGO-INIT — the glow-up command ✨

okay bestie, listen. this is cargo-init, straight outta the General Commands Manual, and it's literally the "make me a whole Rust package, right here, right now" button. no cap.

🌸 SYNOPSIS 🌸

cargo init [options] [path]

🎀 DESCRIPTION 🎀

so the whole vibe is: this command creates a brand-new Cargo manifest in the directory you're standing in. you can also hand it a path as an argument and it'll do the thing in that directory instead. iconic behaviour, honestly.

if there are already Rust source files sitting in there with the typical names, it's gonna use those. no drama. but if there aren't any, it'll spin up a lil sample src/main.rs for you — or src/lib.rs instead if you passed --lib. slay.

also, if the directory isn't already chilling inside a VCS repository, a new repository gets created. (peep --vcs down below, iykyk 👀)

pro tip from me to you: check out cargo-new(1) if you want the sibling command — that one makes a new package in a new directory. different energy, same family.

✨ OPTIONS ✨

💅 Init Options

  • --bin — makes a package with a binary target (src/main.rs). this is the default, so it's giving "I didn't even have to try" 😌
  • --lib — makes a package with a library target (src/lib.rs). library girlies rise 🦋
  • --edition edition — pick which Rust edition you want. default is 2024. the possible values are: 2015, 2018, 2021, 2024
  • --name name — set the package name yourself. if you don't, it defaults to the directory name (which is usually fine, but you do you 💁)
  • --vcs vcs — initialize a new VCS repository for the given version control system. your options are git, hg, pijul, or fossil — or none if you want zero version control, living dangerously fr fr. if you don't specify anything, it defaults to git, or to the configuration value cargo-new.vcs, or none if you're already inside a VCS repository.
  • --registry registry — this sets the publish field in Cargo.toml to the registry name you give it, which restricts publishing so it can only go to that registry. gatekeeping, but make it config.

registry names are defined in the Cargo config files at https://doc.rust-lang.org/cargo/reference/config.html. if you don't specify one, the default registry defined by the registry.default config key gets used. and if the default registry isn't set and you didn't use --registry? then the publish field just doesn't get set at all, which means publishing isn't restricted. free-for-all, periodt.

🌈 Display Options

  • -v, --verbose — verbose output, bestie. you can even specify it twice for "very verbose" output, which throws in extra stuff like dependency warnings and build script output. you can also set this with the term.verbose config value at https://doc.rust-lang.org/cargo/reference/config.html. say it with me: more words, more power.
  • -q, --quiet — do NOT print cargo log messages. silence is golden 💜. can also be set with the term.quiet config value at https://doc.rust-lang.org/cargo/reference/config.html.
  • --color when — controls when colored output shows up. valid values are:
    • auto (default): automatically detects if the terminal supports color. it's checking the vibe 🔍
    • always: always display colors. rainbow mode, no apologies 🌈
    • never: never display colors. minimalism era.

can also be set with the term.color config value at https://doc.rust-lang.org/cargo/reference/config.html.

👑 Common Options

  • +toolchain — if Cargo got installed with rustup, and the first argument to cargo starts with +, it gets interpreted as a rustup toolchain name — like +stable or +nightly. see the rustup documentation at https://rust-lang.github.io/rustup/overrides.html for more on how toolchain overrides work. cute lil plus sign, huge power.
  • --config KEY=VALUE or PATH — overrides a Cargo configuration value. the argument should be in TOML syntax as KEY=VALUE, or you can hand it a path to an extra configuration file instead. this flag can be specified multiple times. see the command-line overrides section at https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides for more info.
  • -C PATH — changes the current working directory before executing any specified operations. this affects stuff like where cargo looks by default for the project manifest (Cargo.toml), and also which directories get searched for discovering .cargo/config.toml, for example. this option has to come before the command name, like cargo -C path/to/my-project build.
heads up bestie: this option is only available on the nightly channel (https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) and it requires the -Z unstable-options flag to enable (see #10098 at https://github.com/rust-lang/cargo/issues/10098). so, y'know, not for the faint of heart 🫶
  • -h, --help — prints help information. when in doubt, ask for help, that's self-care 💖
  • -Z flag — unstable (nightly-only) flags to Cargo. run cargo -Z help for details. very "I know a guy" energy.

🌱 ENVIRONMENT 🌱

see the reference at https://doc.rust-lang.org/cargo/reference/environment-variables.html for all the details on environment variables that Cargo reads. it's a whole lore drop, ngl.

⭐ EXIT STATUS ⭐

  • 0: Cargo succeeded. we ate and left no crumbs 🍓
  • 101: Cargo failed to complete. 😭 it's not you, it's the build.

🧚 EXAMPLES 🧚

  1. Create a binary Cargo package in the current directory:
cargo init

🔥 SEE ALSO 🔥

and that's the whole page, bestie 💜 this was CARGO-INIT(1) from the General Commands Manual — shoutout to the source and version for making it all possible, and to the date for timestamping our little journey. go forth and cargo init, you absolute main character 👑✨

📦 where this page comes from