cargo-stylus command reference

Complete reference for all cargo-stylus commands (v0.10.2). Every command supports the --verbose global flag for debug output.

activate

Activate an already deployed Stylus contract onchain.

Alias: a

Usage:

cargo stylus activate \
  --address <CONTRACT_ADDRESS> \
  --private-key <KEY> \
  --endpoint <RPC_URL>

Options:

Option	Description	Default
`--address <ADDRESS>`	Deployed contract address to activate (required)	—
`--estimate-gas`	Only estimate gas without sending a transaction	`false`
`--data-fee-bump-percent <PERCENT>`	Percent to bump the estimated activation data fee	`20`

Also accepts authentication options and provider options.

build

Compile a Stylus contract to WASM.

Alias: b

Usage:

cargo stylus build

Options:

Option	Description	Default
`--features <FEATURES>`	Cargo features to enable when building	—
`--source-files-for-project-hash <FILES>`	Paths to include in the project hash for verification. If omitted, all `.rs`, `Cargo.toml`, and `Cargo.lock` files are included	—

Also accepts project options.

cache

Manage contract caching using the Stylus CacheManager. Has three subcommands.

cache bid

Place a bid to cache a deployed and activated contract.

Alias: b

Usage:

cargo stylus cache bid <ADDRESS> <BID>

Positional arguments:

Argument	Description
`<ADDRESS>`	Deployed and activated contract address
`<BID>`	Bid amount in wei (a value of 0 is valid)

Also accepts authentication options and provider options.

cache status

Check a contract's cache status.

Alias: s

Usage:

cargo stylus cache status --address <ADDRESS>

Options:

Option	Description	Default
`--address <ADDRESS>`	Contract address to check	—

Also accepts provider options.

cache suggest-bid

Get the suggested minimum bid for caching a contract.

Usage:

cargo stylus cache suggest-bid <ADDRESS>

Positional arguments:

Argument	Description
`<ADDRESS>`	Contract address to get suggested bid for

Also accepts provider options.

cgen

Generate C code bindings for a Stylus contract.

Usage:

cargo stylus cgen <INPUT_FILE> <OUTPUT_DIR>

Positional arguments:

Argument	Description
`<INPUT_FILE>`	Input file path
`<OUTPUT_DIR>`	Output directory path

check

Verify that a contract compiles to valid WASM and passes onchain activation checks.

Alias: c

Usage:

cargo stylus check --endpoint <RPC_URL>

Options:

Option	Description	Default
`--wasm-file <PATH>`	Prebuilt WASM file(s) to check instead of building from source	—
`--wasm-file-address <ADDRESS>`	Deployment address for the WASM file	random
`--contract-address <ADDRESS>`	Deployment address for the contract	random
`--data-fee-bump-percent <PERCENT>`	Percent to bump the estimated activation data fee	`20`

Also accepts build options, project options, and provider options.

Example:

cargo stylus check --endpoint https://sepolia-rollup.arbitrum.io/rpc

codehash-keepalive

Request to keep a contract's codehash from expiring in the ArbOS codehash registry.

Alias: k

Usage:

cargo stylus codehash-keepalive \
  --codehash <HASH> \
  --private-key <KEY>

Options:

Option	Description	Default
`--codehash <HASH>`	The codehash to keep alive (required)	—

Also accepts authentication options and provider options.

constructor

Print the signature of a contract's constructor.

Usage:

cargo stylus constructor

Also accepts project options and reflection options.

deploy

Deploy one or more Stylus contracts. By default, contracts are deployed through the Stylus deployer contract, which handles deployment, activation, and constructor initialization.

Alias: d

Usage:

cargo stylus deploy \
  --private-key <KEY> \
  --endpoint <RPC_URL>

Options:

Option	Description	Default
`--estimate-gas`	Only estimate gas, don't deploy	`false`
`--no-verify`	Skip reproducible Docker container verification	`false`
`--no-activate`	Skip activation after deployment	`false`
`--cargo-stylus-version <VERSION>`	cargo-stylus version for the Docker image	local version
`--deployer-address <ADDRESS>`	Address of the Stylus deployer contract	Stylus default deployer
`--deployer-salt <SALT>`	Salt passed to the deployer for deterministic addresses	`0x0...0`
`--constructor-args <ARGS>...`	Constructor arguments (supports multiple values)	—
`--constructor-value <ETHER>`	Ether to send through the constructor (in ETH)	`0`
`--constructor-signature <SIG>`	Constructor signature when using `--wasm-file`	—
`--wasm-file <PATH>`	Deploy a prebuilt WASM file directly	—

Also accepts authentication options, build options, project options, and provider options.

Example:

cargo stylus deploy \
  --endpoint https://sepolia-rollup.arbitrum.io/rpc \
  --private-key $PRIVATE_KEY \
  --constructor-args "0xMyTokenName" "0xMTK" \
  --estimate-gas

export-abi

Export a Solidity ABI interface for a Stylus contract.

Usage:

cargo stylus export-abi

Also accepts project options and reflection options.

Example:

cargo stylus export-abi > IMyContract.sol
cargo stylus export-abi --json > abi.json

get-initcode

Generate and print the initialization code (initcode) for a Stylus contract.

Alias: e

Usage:

cargo stylus get-initcode

Options:

Option	Description	Default
`--output <FILE>`	Output file for the generated hex code	stdout

Also accepts build options and project options.

init

Initialize a Stylus project in an existing directory.

Usage:

cargo stylus init [PATH]

Positional arguments:

Argument	Description	Default
`[PATH]`	Path to existing directory, cargo crate, or cargo workspace	`.`

Options:

Option	Description	Default
`--contract`	Initialize as a Stylus contract	default
`--workspace`	Initialize as a Stylus workspace	`false`

new

Create a new Stylus project.

Usage:

cargo stylus new <PROJECT_NAME>

Positional arguments:

Argument	Description
`<PROJECT_NAME>`	Name or path for the new project

Options:

Option	Description	Default
`--contract`	Create a new contract project	default
`--workspace`	Create a new workspace project	`false`

Example:

cargo stylus new my-stylus-contract

replay

Replay a transaction using an external debugger (GDB, LLDB, or StylusDB).

Alias: r

Usage:

cargo stylus replay --tx <TX_HASH>

Options:

Option	Description	Default
`--tx <HASH>`	Transaction hash to replay (required)	—
`--project <PATH>`	Project path	`.`
`--debugger <DEBUGGER>`	Debugger to use: `gdb`, `lldb`, `stylusdb`, or `auto`	`auto`
`--features <FEATURES>`	Cargo features for building	—
`--package <NAME>`	Specific package to build during replay	—
`--contracts <MAPPING>`	Multi-contract debugging: `ADDRESS1:PATH1,ADDRESS2:PATH2`	—
`--addr-solidity <ADDRESSES>`	Comma-separated Solidity contract addresses for display	—
`--use-native-tracer`	Use the native tracer instead of JavaScript	`false`

Also accepts project options and provider options.

Example:

cargo stylus replay \
  --tx 0xd4...85 \
  --endpoint https://sepolia-rollup.arbitrum.io/rpc \
  --debugger stylusdb

simulate

Simulate a transaction without executing it onchain.

Alias: s

Usage:

cargo stylus simulate --to <ADDRESS> --data <HEX_DATA>

Options:

Option	Description	Default
`--from <ADDRESS>`	Sender address	—
`--to <ADDRESS>`	Target contract address	—
`--gas <LIMIT>`	Gas limit	—
`--gas-price <PRICE>`	Gas price (in wei)	—
`--value <AMOUNT>`	Value to send (in wei)	—
`--data <HEX>`	Calldata as hex string (with or without `0x` prefix)	—
`--use-native-tracer`	Use the native tracer instead of JavaScript	`false`

Also accepts provider options.

trace

Display a trace of a transaction.

Alias: t

Usage:

cargo stylus trace --tx <TX_HASH>

Options:

Option	Description	Default
`--tx <HASH>`	Transaction hash to trace (required)	—
`--project <PATH>`	Project path	`.`
`--use-native-tracer`	Use the native tracer instead of JavaScript	`false`

Also accepts provider options.

usertrace

Trace a transaction with StylusDB, capturing user function calls. Provides a higher-level view than trace by filtering for user-defined function calls.

Alias: ut

Usage:

cargo stylus usertrace --tx <TX_HASH>

Options:

Option	Description	Default
`--tx <HASH>`	Transaction hash to trace (required)	—
`--project <PATH>`	Project path	`.`
`--features <FEATURES>`	Cargo features for building	—
`--package <NAME>`	Specific package to build during trace	—
`--contracts <MAPPING>`	Multi-contract tracing: `ADDRESS1:PATH1,ADDRESS2:PATH2`	—
`--verbose-usertrace`	Include `stylus_sdk` functions in the trace	`false`
`--trace-external-usertrace <CRATES>`	Comma-separated list of additional crates to trace	—
`--enable-stylusdb-output`	Show StylusDB output (silenced by default)	`false`
`--use-native-tracer`	Use the native tracer instead of JavaScript	`false`

Also accepts project options and provider options.

verify

Verify the deployment of a Stylus contract using reproducible builds.

Usage:

cargo stylus verify --deployment-tx <TX_HASH>

Options:

Option	Description	Default
`--deployment-tx <HASH>`	Deployment transaction hash(es) to verify (required)	—
`--cargo-stylus-version <VERSION>`	cargo-stylus version for the Docker image	local version
`--no-verify`	Skip reproducible Docker container	`false`
`--skip-clean`	Skip cleaning before verification	`false`

Also accepts project options and provider options.

Example:

cargo stylus verify \
  --deployment-tx 0xd4...85 \
  --endpoint https://sepolia-rollup.arbitrum.io/rpc

Common options

These option groups are shared across multiple commands. Each command's documentation notes which groups it accepts.

Provider options

Option	Description	Default
`-e, --endpoint <URL>`	Arbitrum RPC endpoint URL	`http://localhost:8547`

Authentication options

Option	Description	Default
`--private-key <KEY>`	Private key as a hex string (exposes key to shell history)	—
`--private-key-path <FILE>`	Path to a text file containing a hex-encoded private key	—
`--keystore-path <FILE>`	Path to an Ethereum wallet keystore file (e.g., Clef)	—
`--keystore-password-path <FILE>`	Path to the keystore password file	—
`--max-fee-per-gas-gwei <GWEI>`	Maximum fee per gas in gwei	—

Build options

Option	Description	Default
`--features <FEATURES>`	Cargo features to enable	—
`--source-files-for-project-hash <FILES>`	Paths to include in project hash for verification	all `.rs`, `Cargo.toml`, `Cargo.lock`

Project options

Option	Description	Default
`--contract <NAME>`	Specific contract package(s) to target in a workspace	all default contracts

Reflection options

Option	Description	Default
`--output <FILE>`	Output file path	stdout
`--json`	Write JSON ABI (requires `solc`)	`false`
`--rust-features <FEATURES>`	Rust crate features to include in ABI export	—

Command aliases

Alias	Command
`a`	activate
`b`	build
`c`	check
`d`	deploy
`e`	get-initcode
`k`	codehash-keepalive
`r`	replay
`s`	simulate
`t`	trace
`ut`	usertrace

For usage examples and workflow guides, see the CLI tools overview.

activate​

build​

cache​

cache bid​

cache status​

cache suggest-bid​

cgen​

check​

codehash-keepalive​

constructor​

deploy​

export-abi​

get-initcode​

init​

new​

replay​

simulate​

trace​

usertrace​

verify​

Common options​

Provider options​

Authentication options​

Build options​

Project options​

Reflection options​

Command aliases​

activate

build

cache

cache bid

cache status

cache suggest-bid

cgen

check

codehash-keepalive

constructor

deploy

export-abi

get-initcode

init

new

replay

simulate

trace

usertrace

verify

Common options

Provider options

Authentication options

Build options

Project options

Reflection options

Command aliases