rust-script
Operate Rust scripting with Cargo-native scripts first, rust-script fallback second.
Default Mode
Use Cargo script mode:
<CARGO_SCRIPT_CMD> path/to/script.rs -- arg1 arg2
Use this for:
- single-file scripts with compile-time guarantees
- explicit Cargo invocation across supported platforms
- dependency management in embedded manifest frontmatter
- script workflows close to regular Cargo projects
Use rust-script only when user explicitly needs stable-only scripting ergonomics.
Choose <CARGO_SCRIPT_CMD>
Set command prefix by toolchain model:
- Rustup-managed toolchains:
CARGO_SCRIPT_CMD='cargo +nightly -Zscript'
- Nightly cargo already in PATH (common in Nix):
CARGO_SCRIPT_CMD='cargo -Zscript'
Detection hint:
- if
cargo -Zscript ... works, prefer it
- if
cargo +nightly errors with no such command: +nightly, do not use +nightly
Fast Decision Tree
- User asks for Rust scripting + accepts nightly:
- choose
<CARGO_SCRIPT_CMD>
- prefer frontmatter manifest (
---cargo ... ---)
- User wants stable-only and no nightly:
- use
rust-script fallback
- explain tradeoff vs Cargo-native scripts
- User asks about publishing/installing script file directly:
- explain current limitation (
package/publish unsupported; install --path file.rs unsupported)
- suggest converting to normal package (
cargo new --bin)
Core Rules
- Always pass
-Zscript before script path
- For extensionless executable scripts, call with path (
./tool), not bare token (tool)
- For script args that look like Cargo flags, use
-- separator when needed
- Prefer explicit edition in frontmatter to avoid default-edition warning churn
- Treat Cargo scripts as single-file bin packages, not workspace members
Engineering Discipline
- Keep scripts boring: parse external input once, return contextual errors, and add dependencies or abstractions only for a concrete script need
- Use the standard library for a small script; add
anyhow for ergonomic contextual errors or clap when argument parsing outgrows a few flags
- Do not add async, a framework, or a production-service stack by default. Use async only for concurrent I/O that benefits from it
- Treat
unsafe, FFI, manual Send/Sync, and custom lock-free code as an escalation out of script scope; move the risky core to a normal Cargo package and prove it there
Required follow-up reads
| Need |
Read |
When |
| Cargo script runbook |
references/cargo-script-workflow.md |
Building or debugging a Cargo-native script |
| Supported command surface |
references/command-support-matrix.md |
Before uncommon Cargo commands |
| Exact error recovery |
references/error-catalog.md |
A known command fails |
| Current stabilization state |
references/upstream-status.md |
Behavior may have changed upstream |
| Stable fallback |
references/rust-script-fallback.md |
Nightly is unavailable or rejected |
| Minimal scripts, frontmatter, verification, and sources |
references/contracts-and-verification.md |
Creating or validating a Cargo-native script |
| Error, type, async, test, or unsafe design inside a script |
references/scripting-engineering.md |
Applying Rust engineering checks without turning a script into a service |
| Opinionated production-Rust patterns |
references/advanced/rust/README.md, then its matching reference |
A script is becoming package-scale or needs deep async, CLI, web, type-state, test, concurrency, or safety guidance; repository policy and toolchain constraints take precedence |
| Undefined-behavior investigation |
references/advanced/rust-ub/README.md, then its matching reference |
Auditing unsafe code with Miri, sanitizers, Loom, or the UB taxonomy |
| Cross-language code-smell or logging review |
references/advanced/engineering/code-smells.md, references/advanced/engineering/logging.md |
Reviewing structure or observability beyond Rust-specific mechanics |
Legacy rust-script CLI |
reference/cli.md |
Exact fallback flags or environment variables are needed |
| Starter source |
templates/script.rs, templates/async.rs |
Creating a matching script |
Agent Operating Procedure
- Detect user intent:
- Cargo-native script mode or
rust-script fallback
- Validate command shape:
-Zscript position, path form, --manifest-path usage
- Apply known limits:
- block unsupported flows early (
package, publish, install --path file.rs, path dependency on script)
- Provide fix-ready command:
- return exact corrected command, no vague advice
- If behavior seems new/regressed:
- check
references/upstream-status.md
- then confirm live state with
gh issue view
1---2name: rust-script3description: Use when creating or debugging a single-file Rust script with Cargo, rust-script, or an embedded manifest.4license: AGPL-3.0-or-later5---67# rust-script89Operate Rust scripting with Cargo-native scripts first, `rust-script` fallback second.1011## Default Mode1213Use Cargo script mode:1415```sh16<CARGO_SCRIPT_CMD> path/to/script.rs -- arg1 arg217```1819Use this for:2021- single-file scripts with compile-time guarantees22- explicit Cargo invocation across supported platforms23- dependency management in embedded manifest frontmatter24- script workflows close to regular Cargo projects2526Use `rust-script` only when user explicitly needs stable-only scripting ergonomics.2728## Choose `<CARGO_SCRIPT_CMD>`2930Set command prefix by toolchain model:3132- Rustup-managed toolchains:33 - `CARGO_SCRIPT_CMD='cargo +nightly -Zscript'`34- Nightly cargo already in PATH (common in Nix):35 - `CARGO_SCRIPT_CMD='cargo -Zscript'`3637Detection hint:3839- if `cargo -Zscript ...` works, prefer it40- if `cargo +nightly` errors with `no such command: +nightly`, do not use `+nightly`4142## Fast Decision Tree43441. User asks for Rust scripting + accepts nightly:4546- choose `<CARGO_SCRIPT_CMD>`47- prefer frontmatter manifest (`---cargo ... ---`)48492. User wants stable-only and no nightly:5051- use `rust-script` fallback52- explain tradeoff vs Cargo-native scripts53543. User asks about publishing/installing script file directly:5556- explain current limitation (`package`/`publish` unsupported; `install --path file.rs` unsupported)57- suggest converting to normal package (`cargo new --bin`)5859## Core Rules6061- Always pass `-Zscript` before script path62- For extensionless executable scripts, call with path (`./tool`), not bare token (`tool`)63- For script args that look like Cargo flags, use `--` separator when needed64- Prefer explicit edition in frontmatter to avoid default-edition warning churn65- Treat Cargo scripts as single-file bin packages, not workspace members6667## Engineering Discipline6869- Keep scripts boring: parse external input once, return contextual errors, and add dependencies or abstractions only for a concrete script need70- Use the standard library for a small script; add `anyhow` for ergonomic contextual errors or `clap` when argument parsing outgrows a few flags71- Do not add async, a framework, or a production-service stack by default. Use async only for concurrent I/O that benefits from it72- Treat `unsafe`, FFI, manual `Send`/`Sync`, and custom lock-free code as an escalation out of script scope; move the risky core to a normal Cargo package and prove it there7374## Required follow-up reads7576|Need|Read|When|77|---|---|---|78|Cargo script runbook|`references/cargo-script-workflow.md`|Building or debugging a Cargo-native script|79|Supported command surface|`references/command-support-matrix.md`|Before uncommon Cargo commands|80|Exact error recovery|`references/error-catalog.md`|A known command fails|81|Current stabilization state|`references/upstream-status.md`|Behavior may have changed upstream|82|Stable fallback|`references/rust-script-fallback.md`|Nightly is unavailable or rejected|83|Minimal scripts, frontmatter, verification, and sources|`references/contracts-and-verification.md`|Creating or validating a Cargo-native script|84|Error, type, async, test, or unsafe design inside a script|`references/scripting-engineering.md`|Applying Rust engineering checks without turning a script into a service|85|Opinionated production-Rust patterns|`references/advanced/rust/README.md`, then its matching reference|A script is becoming package-scale or needs deep async, CLI, web, type-state, test, concurrency, or safety guidance; repository policy and toolchain constraints take precedence|86|Undefined-behavior investigation|`references/advanced/rust-ub/README.md`, then its matching reference|Auditing unsafe code with Miri, sanitizers, Loom, or the UB taxonomy|87|Cross-language code-smell or logging review|`references/advanced/engineering/code-smells.md`, `references/advanced/engineering/logging.md`|Reviewing structure or observability beyond Rust-specific mechanics|88|Legacy `rust-script` CLI|`reference/cli.md`|Exact fallback flags or environment variables are needed|89|Starter source|`templates/script.rs`, `templates/async.rs`|Creating a matching script|9091## Agent Operating Procedure92931. Detect user intent:9495- Cargo-native script mode or `rust-script` fallback96972. Validate command shape:9899- `-Zscript` position, path form, `--manifest-path` usage1001013. Apply known limits:102103- block unsupported flows early (`package`, `publish`, `install --path file.rs`, path dependency on script)1041054. Provide fix-ready command:106107- return exact corrected command, no vague advice1081095. If behavior seems new/regressed:110111- check `references/upstream-status.md`112- then confirm live state with `gh issue view`
anntnzrb