shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

rust-script

Expert guide for Cargo single-file Rust scripts (`-Zscript`) and fallback `rust-script` usage. Use when users ask about Rust scripting, shebang scripts, embedded Cargo manifests/frontmatter, `--manifest-path` for script files, command support/limits, migration from Python/TypeScript scripts, or debugging Cargo script errors and stabilization status.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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

  1. User asks for Rust scripting + accepts nightly:
  • choose <CARGO_SCRIPT_CMD>
  • prefer frontmatter manifest (---cargo ... ---)
  1. User wants stable-only and no nightly:
  • use rust-script fallback
  • explain tradeoff vs Cargo-native scripts
  1. 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

  1. Detect user intent:
  • Cargo-native script mode or rust-script fallback
  1. Validate command shape:
  • -Zscript position, path form, --manifest-path usage
  1. Apply known limits:
  • block unsupported flows early (package, publish, install --path file.rs, path dependency on script)
  1. Provide fix-ready command:
  • return exact corrected command, no vague advice
  1. If behavior seems new/regressed:
  • check references/upstream-status.md
  • then confirm live state with gh issue view