# CLI Migration Guide: v2.x to v3.0 This guide documents the CLI command consolidation that begins in v2.x (with deprecation warnings) and completes in v3.0 (old commands removed). --- ## Overview The Stella CLI has been reorganized for better discoverability and consistency: | Change | Reason | |--------|--------| | 81+ top-level commands → 18 | Easier to discover and remember | | Scattered settings → `stella config` | Unified configuration management | | Multiple verify commands → `stella verify` | Consistent verification interface | | Compound names → proper hierarchy | `scangraph` → `scan graph` | ## Deprecation Timeline - **v2.x**: Old commands work but show deprecation warnings - **v3.0**: Old commands removed To suppress deprecation warnings during transition: ```bash export STELLA_SUPPRESS_DEPRECATION_WARNINGS=1 ``` --- ## Quick Migration Reference ### Settings & Configuration ```bash # Before (deprecated) stella notify channels list stella admin feeds status stella registry list # After stella config notify channels list stella config feeds status stella config registry list ``` ### Verification ```bash # Before (deprecated) stella attest verify stella vex verify stella patchverify # After stella verify attestation stella verify vex stella verify patch ``` ### Scanning ```bash # Before (deprecated) stella scangraph list stella secrets bundle create stella image inspect # After stella scan graph list stella scan secrets bundle create stella scan image inspect ``` ### Evidence & Audit ```bash # Before (deprecated) stella evidenceholds list stella audit export stella prove --artifact stella replay run # After stella evidence holds list stella evidence audit export stella evidence proof generate --artifact stella evidence replay run ``` ### Reachability ```bash # Before (deprecated) stella reachgraph list stella slice create stella witness show # After stella reachability graph list stella reachability slice create stella reachability witness show ``` ### SBOM ```bash # Before (deprecated) stella sbomer compose stella layersbom show # After stella sbom compose stella sbom layer show ``` ### Cryptography ```bash # Before (deprecated) stella keys list stella issuerkeys list stella sign image # After stella crypto keys list stella crypto keys issuer list stella crypto sign image ``` ### Administration ```bash # Before (deprecated) stella doctor run stella db migrate stella admin users list # After stella admin doctor run stella admin db migrate stella auth users list ``` ### CI/CD ```bash # Before (deprecated) stella gate evaluate stella github upload # After (either works) stella release gate evaluate stella ci gate evaluate # shortcut for CI pipelines stella ci github upload ``` ### Utilities ```bash # Before (deprecated) stella binary diff stella hlc show stella timeline query # After stella tools binary diff stella tools hlc show stella tools timeline query ``` --- ## New Command Structure ### Primary Commands ``` stella scan # Scanning operations stella release # Release management stella verify # All verification stella attest # Create attestations stella evidence # Evidence management stella policy # Policy management stella vex # VEX operations stella reachability # Reachability analysis stella sbom # SBOM operations stella crypto # Cryptography stella config # Settings & configuration stella auth # Authentication stella admin # Administration stella ci # CI/CD integration stella setup # Initial setup stella explain # Explain decisions stella tools # Utility commands ``` ### `stella config` - Unified Settings All configuration is now under `stella config`: ``` stella config ├── list [--category ] # List config paths ├── show # Show config value ├── set # Set config value ├── export # Export all config ├── import # Import config ├── notify/ # Notification settings │ ├── channels list/test │ ├── templates list/render │ └── preferences export/import ├── feeds/ # Feed configuration │ ├── list │ ├── status │ └── refresh ├── integrations/ # Integration settings │ ├── list │ └── test ├── registry/ # Registry settings └── sources/ # Data sources ``` ### `stella verify` - Unified Verification All verification under one command: ``` stella verify ├── image # Image attestation ├── bundle # Evidence bundle ├── offline # Offline verification ├── attestation # Attestation verification ├── vex # VEX verification ├── patch # Patch verification └── sbom # SBOM verification ``` ### `stella scan` - Unified Scanning All scanning under one command: ``` stella scan ├── run # Run a scan ├── status # Check status ├── results # View results ├── download # Download scanner bundle ├── workers # Configure workers ├── graph/ # Scan graph operations ├── secrets/ # Secret detection │ └── bundle create/verify/info └── image/ # Image analysis ├── inspect └── layers ``` --- ## CI/CD Script Updates ### GitHub Actions ```yaml # Before - run: stella gate evaluate --artifact ${{ env.IMAGE_SHA }} # After (either works) - run: stella ci gate evaluate --artifact ${{ env.IMAGE_SHA }} # or - run: stella release gate evaluate --artifact ${{ env.IMAGE_SHA }} ``` ### GitLab CI ```yaml # Before script: - stella notify channels test --channel slack-alerts # After script: - stella config notify channels test --channel slack-alerts ``` ### Jenkins ```groovy // Before sh 'stella scangraph list --format json' // After sh 'stella scan graph list --format json' ``` --- ## Common Errors and Solutions ### "Command not found" in v3.0 If upgrading to v3.0 and a command fails: ```bash $ stella scangraph list Error: Unknown command 'scangraph'. Did you mean 'scan graph'? ``` Update your script to use the new path. ### "Deprecated command" warnings ``` WARNING: 'stella notify' is deprecated and will be removed in v3.0. Use 'stella config notify' instead. ``` This is informational. The command still works but should be updated. ### Suppressing warnings in CI ```bash export STELLA_SUPPRESS_DEPRECATION_WARNINGS=1 stella notify channels list # No warning ``` --- ## Getting Help ```bash # See all commands stella --help # See subcommands stella config --help stella verify --help # See command details stella config notify channels list --help ``` --- ## Migration Checklist - [ ] Update CI/CD pipelines to use new command paths - [ ] Update documentation referencing CLI commands - [ ] Update automation scripts - [ ] Test with `STELLA_SUPPRESS_DEPRECATION_WARNINGS=0` to find deprecated usage - [ ] Plan upgrade to v3.0 before end-of-support for v2.x