Stylus cargo stylus

arbitrum-docs/stylus/using-stylus-cli.mdx

@@ -0,0 +1,106 @@
+---
+id: using-stylus-cli
+title: 'Using Stylus CLI'
+description: 'Get started with Stylus CLI, a Rust toolkit for developing Stylus contracts'
+author: 'anegg0'
+sme: 'anegg0'
+sidebar_position: 2
+target_audience: Developers writing Stylus contracts in Rust using Stylus
+---
+
+This guide will get you started using [cargo stylus](https://github.com/OffchainLabs/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](https://www.rust-lang.org/tools/install) 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:
+
+```shell
+cargo install --force cargo-stylus
+```
+
+Add WASM ([WebAssembly](https://webassembly.org/)) 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:
+
+```shell
+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) <br />• --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) <br />• --json: Write JSON ABI using solc                                                                                              |
+| activate   | Activate an already deployed contract            | • --address: Contract address to activate <br />• --data-fee-bump-percent: Percent to bump estimated fee (default 20%) <br />• --estimate-gas: Only estimate gas without sending tx |
+| cache      | Cache contract using Stylus CacheManager         | Subcommands: <br />• bid: Place bid on contract <br />• status: Check contract status <br />• suggest-bid: Get suggested minimum bid                                                |
+| check      | Check a contract                                 | • --wasm-file: WASM to check <br />• --contract-address: Deploy address                                                                                                             |
+| deploy     | Deploy a contract                                | • --estimate-gas: Only perform estimation <br />• --no-verify: Skip reproducible container <br />• --cargo-stylus-version: Version for Docker image                                 |
+| verify     | Verify contract deployment                       | • --deployment-tx: Hash of deployment tx <br />• --no-verify: Skip reproducible container <br />• --cargo-stylus-version: Version for Docker image                                  |
+| cgen       | Generate C code bindings                         | • input: Input file path <br />• out_dir: Output directory path                                                                                                                     |
+| replay     | Replay transaction in gdb                        | • --stable-rust: Use stable Rust <br />• --child: Child process flag                                                                                                                |
+| trace      | Trace a transaction                              | • --endpoint: RPC endpoint <br />• --tx: Transaction hash <br />• --project: Project path <br />• --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](https://docs.arbitrum.io/stylus/how-tos/optimizing-binaries) | The `cargo-stylus` tool allows you to optimize WebAssembly (WASM) binaries, ensuring that your contracts are as efficient as possible.      |
+| [Debug Stylus transactions](https://docs.arbitrum.io/stylus/how-tos/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](https://docs.arbitrum.io/stylus/how-tos/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](https://docs.arbitrum.io/run-arbitrum-node/run-local-dev-node)             | Learn how to run a local Arbitrum dev node to test your Stylus contracts.                                                                    |
+
+#### Additional resources
+
+#### [Troubleshooting](https://docs.arbitrum.io/stylus/troubleshooting-building-stylus): solve the most common issues.
+
+#### [cargo-stylus repository](https://github.com/OffchainLabs/stylus): 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.

website/sidebars.js

@@ -515,6 +515,11 @@ const sidebars = {
             },
           ],
         },
+        {
+          type: 'doc',
+          id: 'stylus/using-stylus-cli',
+          label: 'Using Stylus CLI',
+        },
         {
           type: 'category',
           label: 'Concepts',