Using Stylus CLI
This guide will get you started using cargo stylus, a CLI toolkit to help developers manage, compile, and optimize their Stylus contracts efficiently.
This overview is meant to help discover cargo stylus' tools and learn to use them effectively.
Installing cargo stylus
Cargo stylus is available as a plugin to the standard cargo tool used for developing Rust programs.
Prerequisites
Rust toolchain
Follow the instructions on Rust Lang's installation page to install a complete Rust toolchain (v1.81 or older, v1.82 is currently not supported) on your system. After installation, ensure you can access the programs rustup, rustc, and cargo from your preferred terminal application.
Installation
In your terminal, run:
cargo install --force cargo-stylus
Add WASM (WebAssembly) as a build target for the specific Rust toolchain you are using. The below example sets your default Rust toolchain to 1.80 as well as adding the WASM build target:
rustup default 1.80
rustup target add wasm32-unknown-unknown --toolchain 1.80
You can verify that cargo stylus is installed by running cargo stylus -V in your terminal, returning something like:stylus 0.5.6
Using cargo stylus
Cargo Stylus commands reference
| Command | Description | Options |
|---|---|---|
| new | Create a new Stylus project | • name: Project name (required) • --minimal: Create a minimal contract |
| init | Initialize a Stylus project in current directory | • --minimal: Create a minimal contract |
| export-abi | Export a Solidity ABI | • --output: Output file (defaults to stdout) • --json: Write JSON ABI using solc |
| activate | Activate an already deployed contract | • --address: Contract address to activate • --data-fee-bump-percent: Percent to bump estimated fee (default 20%) • --estimate-gas: Only estimate gas without sending tx |
| cache | Cache contract using Stylus CacheManager | Subcommands: • bid: Place bid on contract • status: Check contract status • suggest-bid: Get suggested minimum bid |
| check | Check a contract | • --wasm-file: WASM to check • --contract-address: Deploy address |
| deploy | Deploy a contract | • --estimate-gas: Only perform estimation • --no-verify: Skip reproducible container • --cargo-stylus-version: Version for Docker image |
| verify | Verify contract deployment | • --deployment-tx: Hash of deployment tx • --no-verify: Skip reproducible container • --cargo-stylus-version: Version for Docker image |
| cgen | Generate C code bindings | • input: Input file path • out_dir: Output directory path |
| replay | Replay transaction in gdb | • --stable-rust: Use stable Rust • --child: Child process flag |
| trace | Trace a transaction | • --endpoint: RPC endpoint • --tx: Transaction hash • --project: Project path • --use-native-tracer: Use native tracer |
Common options
These options are available across multiple commands:
| Option | Description |
|---|---|
| --endpoint | Arbitrum RPC endpoint (default: http://localhost:8547) |
| --verbose | Print debug info |
| --source-files-for-project-hash | Paths to source files for project hash |
| --max-fee-per-gas-gwei | Optional max fee per gas in gwei |
Authentication options
Available for commands involving transactions:
| Option | Description |
|---|---|
| --private-key-path | Path to file containing hex-encoded private key |
| --private-key | Private key as hex string (exposes to shell history) |
| --keystore-path | Path to Ethereum wallet keystore file |
| --keystore-password-path | Keystore password file path |
Examples usage
| Description | Command |
|---|---|
| Create a new Stylus project | cargo stylus new my_project |
| Initialize a Stylus project in the current directory | cargo stylus init |
| Export a Solidity ABI | cargo stylus export-abi --output abi.json |
| Cache a contract using the Stylus CacheManager for Arbitrum chains | cargo stylus cache bid --address 0x1234567890123456789012345678901234567890 |
How-tos
| Topic | Description |
|---|---|
| Learn how to optimize WASM binaries | The cargo-stylus tool allows you to optimize WebAssembly (WASM) binaries, ensuring that your contracts are as efficient as possible. |
| Debug Stylus transactions | A guide to debugging transactions, helping you identify and fix issues. Gain insights into your Stylus contracts by debugging transactions. |
| Verify contracts | Ensure that your Stylus contracts are correctly verified. Step-by-step instructions on how to verify your contracts using cargo-stylus. |
| Run a Stylus dev node | Learn how to run a local Arbitrum dev node to test your Stylus contracts. |
Additional resources
Troubleshooting: solve the most common issues.
cargo-stylus repository: consult cargo stylus' source code.
This overview page serves as the starting point for mastering the CLI tools available for Stylus development. From optimizing your contracts to debugging and verifying them, the cargo-stylus toolset is integral to a smooth development experience.