351 lines
7.5 KiB
Markdown
351 lines
7.5 KiB
Markdown
# 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 <artifact>
|
|
stella vex verify <artifact>
|
|
stella patchverify <artifact>
|
|
|
|
# After
|
|
stella verify attestation <artifact>
|
|
stella verify vex <artifact>
|
|
stella verify patch <artifact>
|
|
```
|
|
|
|
### Scanning
|
|
|
|
```bash
|
|
# Before (deprecated)
|
|
stella scangraph list
|
|
stella secrets bundle create <dir>
|
|
stella image inspect <ref>
|
|
|
|
# After
|
|
stella scan graph list
|
|
stella scan secrets bundle create <dir>
|
|
stella scan image inspect <ref>
|
|
```
|
|
|
|
### Evidence & Audit
|
|
|
|
```bash
|
|
# Before (deprecated)
|
|
stella evidenceholds list
|
|
stella audit export
|
|
stella prove --artifact <ref>
|
|
stella replay run
|
|
|
|
# After
|
|
stella evidence holds list
|
|
stella evidence audit export
|
|
stella evidence proof generate --artifact <ref>
|
|
stella evidence replay run
|
|
```
|
|
|
|
### Reachability
|
|
|
|
```bash
|
|
# Before (deprecated)
|
|
stella reachgraph list
|
|
stella slice create
|
|
stella witness show <path>
|
|
|
|
# After
|
|
stella reachability graph list
|
|
stella reachability slice create
|
|
stella reachability witness show <path>
|
|
```
|
|
|
|
### SBOM
|
|
|
|
```bash
|
|
# Before (deprecated)
|
|
stella sbomer compose
|
|
stella layersbom show <digest>
|
|
|
|
# After
|
|
stella sbom compose
|
|
stella sbom layer show <digest>
|
|
```
|
|
|
|
### Cryptography
|
|
|
|
```bash
|
|
# Before (deprecated)
|
|
stella keys list
|
|
stella issuerkeys list
|
|
stella sign image <ref>
|
|
|
|
# After
|
|
stella crypto keys list
|
|
stella crypto keys issuer list
|
|
stella crypto sign image <ref>
|
|
```
|
|
|
|
### 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 <cat>] # List config paths
|
|
├── show <path> # Show config value
|
|
├── set <path> <value> # Set config value
|
|
├── export # Export all config
|
|
├── import <file> # 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 <ref> # Image attestation
|
|
├── bundle <path> # Evidence bundle
|
|
├── offline <artifact> # Offline verification
|
|
├── attestation <artifact> # Attestation verification
|
|
├── vex <artifact> # VEX verification
|
|
├── patch <artifact> # Patch verification
|
|
└── sbom <file> # SBOM verification
|
|
```
|
|
|
|
### `stella scan` - Unified Scanning
|
|
|
|
All scanning under one command:
|
|
|
|
```
|
|
stella scan
|
|
├── run <ref> # Run a scan
|
|
├── status <id> # Check status
|
|
├── results <id> # 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
|