cli-reference.md
1 # CLI Reference 2 3 Complete reference for the Gramr command-line interface. 4 5 ## Global Commands 6 7 ### `gramr --help` 8 9 Display help information for all commands. 10 11 ### `gramr --version` 12 13 Display version information. 14 15 ### `gramr wizard` 16 17 Launch the Wotan interactive wizard. 18 19 ## Main Command: `new` 20 21 Create new smart contract resources. 22 23 ```bash 24 gramr new <TYPE> <NAME> [OPTIONS] 25 ``` 26 27 ### Resource Types 28 29 | Type | Description | Example | 30 | ----------- | ------------------ | ------------------------------ | 31 | `contract` | Smart contract | `gramr new contract MyToken` | 32 | `library` | Reusable library | `gramr new library MathUtils` | 33 | `interface` | Contract interface | `gramr new interface IMyToken` | 34 | `abstract` | Abstract contract | `gramr new abstract BaseToken` | 35 | `test` | Test file | `gramr new test TokenTest` | 36 | `script` | Deployment script | `gramr new script DeployToken` | 37 38 ## Language Options 39 40 ### `--solidity` 41 42 Generate Solidity code for Foundry projects. 43 44 **Supports:** 45 46 - All token standards and extensions 47 - Upgradeable patterns 48 - Test and script generation 49 - Complete OpenZeppelin integration 50 51 ### `--rust-stylus` 52 53 Generate Rust code for Arbitrum Stylus projects. 54 55 **Supports:** 56 57 - Basic ERC20, ERC721, ERC1155 contracts 58 - Library generation 59 - OpenZeppelin Stylus integration 60 61 **Limitations:** 62 63 - No extensions support yet 64 - No upgradeable patterns 65 - No test/script generation 66 67 ## Token Standards 68 69 ### `--oz-erc20` 70 71 Generate OpenZeppelin ERC20 token contract. 72 73 ```bash 74 gramr new contract MyToken --solidity --oz-erc20 75 ``` 76 77 **Available Extensions:** 78 79 - `burnable` - Token burning capability 80 - `pausable` - Emergency pause functionality 81 - `capped` - Maximum supply limit 82 - `permit` - Gasless approvals (EIP-2612) 83 - `votes` - On-chain voting and delegation 84 - `wrapper` - Wrap other ERC20 tokens 85 - `flashmint` - Flash loan support 86 - `temporaryapproval` - Single-transaction approvals 87 - `bridgeable` - Cross-chain compatibility 88 - `erc1363` - Payable token standard 89 - `erc4626` - Tokenized vault standard 90 91 ### `--oz-erc721` 92 93 Generate OpenZeppelin ERC721 NFT contract. 94 95 ```bash 96 gramr new contract MyNFT --solidity --oz-erc721 97 ``` 98 99 **Available Extensions:** 100 101 - `enumerable` - Token enumeration and totalSupply 102 - `burnable` - NFT burning capability 103 - `pausable` - Emergency pause functionality 104 - `consecutive` - Efficient batch minting 105 - `uristorage` - Dynamic metadata URIs 106 - `votes` - NFT-based voting 107 - `royalty` - ERC2981 royalty standard 108 - `wrapper` - Wrap other NFTs 109 110 ### `--oz-erc1155` 111 112 Generate OpenZeppelin ERC1155 multi-token contract. 113 114 ```bash 115 gramr new contract GameAssets --solidity --oz-erc1155 116 ``` 117 118 **Available Extensions:** 119 120 - `burnable` - Multi-token burning 121 - `pausable` - Emergency pause functionality 122 - `supply` - Track token supplies 123 - `uristorage` - Per-token URI storage 124 125 ## Upgrade Patterns 126 127 ### `--upgradeable` 128 129 Use OpenZeppelin upgradeable contract patterns. 130 131 ```bash 132 gramr new contract MyToken --solidity --oz-erc20 --upgradeable 133 ``` 134 135 **Features:** 136 137 - Proxy-based upgradeability 138 - Storage layout protection 139 - Initializer patterns 140 - Gap variables for future upgrades 141 142 **Compatibility:** 143 144 - ✅ Solidity contracts 145 - ❌ Rust/Stylus (not yet supported) 146 147 ## Extension Configuration 148 149 ### `--extensions <LIST>` 150 151 Add comma-separated extensions to token contracts. 152 153 ```bash 154 # Single extension 155 gramr new contract MyToken --solidity --oz-erc20 --extensions burnable 156 157 # Multiple extensions 158 gramr new contract MyNFT --solidity --oz-erc721 --extensions enumerable,burnable,royalty 159 160 # All compatible extensions 161 gramr new contract AdvancedToken --solidity --oz-erc20 --extensions burnable,pausable,permit,votes,capped 162 ``` 163 164 **Extension Compatibility:** 165 166 | Extension | ERC20 | ERC721 | ERC1155 | 167 | ------------ | ----- | ------ | ------- | 168 | `burnable` | ✅ | ✅ | ✅ | 169 | `pausable` | ✅ | ✅ | ✅ | 170 | `enumerable` | ❌ | ✅ | ❌ | 171 | `uristorage` | ❌ | ✅ | ✅ | 172 | `supply` | ❌ | ❌ | ✅ | 173 | `votes` | ✅ | ✅ | ❌ | 174 | `permit` | ✅ | ❌ | ❌ | 175 | `royalty` | ❌ | ✅ | ❌ | 176 177 ## Generation Options 178 179 ### `--with-test` 180 181 Generate a corresponding test file. 182 183 ```bash 184 gramr new contract MyToken --solidity --oz-erc20 --with-test 185 ``` 186 187 **Creates:** 188 189 - `src/MyToken.sol` - The contract 190 - `test/MyToken.t.sol` - Foundry test suite 191 192 **Test Features:** 193 194 - Basic functionality tests 195 - Extension-specific tests 196 - Deployment tests 197 - Integration test examples 198 199 ### `--with-script` 200 201 Generate a deployment script. 202 203 ```bash 204 gramr new contract MyToken --solidity --oz-erc20 --with-script 205 ``` 206 207 **Creates:** 208 209 - `src/MyToken.sol` - The contract 210 - `script/MyToken.s.sol` - Foundry deployment script 211 212 **Script Features:** 213 214 - Deployment logic 215 - Constructor parameter configuration 216 - Post-deployment verification 217 - Multi-network support 218 219 ### `--with-section-markers` 220 221 Add organized comment sections to contracts. 222 223 ```bash 224 gramr new contract MyToken --solidity --oz-erc20 --with-section-markers 225 ``` 226 227 **Adds Sections:** 228 229 ```solidity 230 // ======================================== 231 // IMPORTS 232 // ======================================== 233 234 // ======================================== 235 // CONTRACT DECLARATION 236 // ======================================== 237 238 // ======================================== 239 // STATE VARIABLES 240 // ======================================== 241 242 // ======================================== 243 // CONSTRUCTOR 244 // ======================================== 245 246 // ======================================== 247 // PUBLIC FUNCTIONS 248 // ======================================== 249 250 // ======================================== 251 // INTERNAL FUNCTIONS 252 // ======================================== 253 ``` 254 255 ## Configuration Options 256 257 ### `--pragma <VERSION>` 258 259 Set Solidity pragma version. 260 261 ```bash 262 gramr new contract MyToken --solidity --oz-erc20 --pragma 0.8.25 263 ``` 264 265 **Default:** `0.8.30` 266 **Format:** `X.Y.Z` (semantic versioning) 267 268 ### `--license <LICENSE>` 269 270 Set SPDX license identifier. 271 272 ```bash 273 gramr new contract MyToken --solidity --oz-erc20 --license MIT 274 ``` 275 276 **Common Options:** 277 278 - `MIT` - MIT License 279 - `GPL-3.0` - GNU General Public License v3.0 280 - `Apache-2.0` - Apache License 2.0 281 - `BSD-3-Clause` - BSD 3-Clause License 282 - `UNLICENSED` - No license (default) 283 284 ## Complete Examples 285 286 ### Basic Contract Generation 287 288 ```bash 289 # Minimal ERC20 290 gramr new contract SimpleToken --solidity --oz-erc20 291 292 # Basic NFT 293 gramr new contract BasicNFT --solidity --oz-erc721 294 295 # Multi-token 296 gramr new contract GameItems --solidity --oz-erc1155 297 ``` 298 299 ### Advanced Contract Generation 300 301 ```bash 302 # Feature-rich ERC20 token 303 gramr new contract AdvancedToken --solidity --oz-erc20 \ 304 --extensions burnable,pausable,permit,votes \ 305 --with-test --with-script \ 306 --pragma 0.8.25 --license MIT 307 308 # Complete NFT collection 309 gramr new contract NFTCollection --solidity --oz-erc721 \ 310 --extensions enumerable,burnable,royalty,uristorage \ 311 --with-test --with-script \ 312 --with-section-markers 313 314 # Upgradeable gaming token 315 gramr new contract GameToken --solidity --oz-erc20 \ 316 --upgradeable \ 317 --extensions burnable,pausable \ 318 --with-test --with-script 319 ``` 320 321 ### Utility Generation 322 323 ```bash 324 # Library 325 gramr new library MathUtils --solidity 326 327 # Interface 328 gramr new interface IGovernance --solidity 329 330 # Abstract contract 331 gramr new abstract BaseVault --solidity 332 333 # Standalone test 334 gramr new test MyContractTest --solidity 335 336 # Deployment script 337 gramr new script DeployAll --solidity 338 ``` 339 340 ### Rust/Stylus Generation 341 342 ```bash 343 # Basic Stylus contracts 344 gramr new contract MyToken --rust-stylus --oz-erc20 345 gramr new contract MyNFT --rust-stylus --oz-erc721 346 gramr new library Utils --rust-stylus 347 348 # Note: Extensions not yet supported 349 # This will show helpful error: 350 gramr new contract MyToken --rust-stylus --oz-erc20 --extensions burnable 351 ``` 352 353 ## Error Handling 354 355 ### Common Errors 356 357 **Invalid Contract Name** 358 359 ``` 360 Error: Contract name must start with a letter and contain only alphanumeric characters and underscores 361 ``` 362 363 **Unsupported Extension Combination** 364 365 ``` 366 Error: Extension 'permit' is not supported for ERC721 contracts 367 ``` 368 369 **Missing Language Flag** 370 371 ``` 372 Error: Must specify either --solidity or --rust-stylus 373 ``` 374 375 **Rust/Stylus Limitations** 376 377 ``` 378 Error: Extensions are not yet supported for Rust/Stylus contracts 379 Help: Use basic token generation or switch to --solidity 380 ``` 381 382 ## Exit Codes 383 384 | Code | Meaning | 385 | ---- | ------------------------------ | 386 | `0` | Success | 387 | `1` | General error | 388 | `2` | Invalid arguments | 389 | `3` | Project detection failed | 390 | `4` | File generation failed | 391 | `5` | Dependency installation failed | 392 393 ## Environment Variables 394 395 ### `gramr_PROJECT_DIR` 396 397 Override project directory detection. 398 399 ```bash 400 gramr_PROJECT_DIR=/path/to/project gramr new contract MyToken --solidity --oz-erc20 401 ``` 402 403 ### `gramr_LOG_LEVEL` 404 405 Set logging level. 406 407 ```bash 408 gramr_LOG_LEVEL=debug gramr new contract MyToken --solidity --oz-erc20 409 ``` 410 411 **Levels:** `error`, `warn`, `info`, `debug`, `trace` 412 413 ## Integration with Other Tools 414 415 ### Foundry Integration 416 417 ```bash 418 # Generate and build 419 gramr new contract MyToken --solidity --oz-erc20 --with-test 420 forge build 421 422 # Generate and test 423 forge test 424 425 # Generate with script and deploy 426 forge script script/MyToken.s.sol --rpc-url $RPC_URL --broadcast 427 ``` 428 429 ### CI/CD Usage 430 431 ```yaml 432 # GitHub Actions example 433 - name: Generate contracts 434 run: | 435 gramr new contract ProductionToken --solidity --oz-erc20 \ 436 --extensions burnable,pausable --with-test 437 forge build 438 forge test 439 ``` 440 441 ### Docker Usage 442 443 ```bash 444 # Using Docker image 445 docker run --rm -v $(pwd):/workspace ghcr.io/pxlvre/gramr:latest \ 446 gramr new contract MyToken --solidity --oz-erc20 447 ``` 448 449 ## Tips & Best Practices 450 451 1. **Always specify language** - Use `--solidity` or `--rust-stylus` 452 2. **Use descriptive names** - Follow PascalCase for contracts 453 3. **Generate tests** - Always use `--with-test` for production contracts 454 4. **Start simple** - Begin with basic contracts, add extensions later 455 5. **Check compatibility** - Not all extensions work with all token types 456 6. **Version consistency** - Use consistent pragma versions across projects 457 7. **License clarity** - Always specify appropriate license 458 8. **Build after generation** - Run `forge build` to verify generated code