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 |
Example usage
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
Additional resources
For more advanced usage and detailed guides, refer to the following resources:
Optimize WASM binaries
The cargo-stylus tool allows you to optimize WebAssembly (WASM) binaries, ensuring that your contracts are as efficient as possible.
Learn how to optimize WASM binaries
Debug Stylus transactions
Gain insights into your Stylus contracts by debugging transactions.
Debug Stylus transactions
A guide to debugging transactions, helping you identify and fix issues.
Verify contracts
Ensure that your Stylus contracts are correctly verified.
Verify contracts
Step-by-step instructions on how to verify your contracts using cargo-stylus.
Optimize WASM binaries
Troubleshooting
Run a Stylus dev node
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.
Source code repository
The source code for cargo-stylus is available on GitHub. Explore the code, contribute, or use it as a reference.