git.stella-ops.org/docs/modules/cli/guides/migration-v3.md

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:

export STELLA_SUPPRESS_DEPRECATION_WARNINGS=1

---

Quick Migration Reference

Settings & Configuration

# 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

# 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

# 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

# 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

# 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

# Before (deprecated)
stella sbomer compose
stella layersbom show <digest>

# After
stella sbom compose
stella sbom layer show <digest>

Cryptography

# 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

# 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

# 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

# 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

# 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

# Before
script:
  - stella notify channels test --channel slack-alerts

# After
script:
  - stella config notify channels test --channel slack-alerts

Jenkins

// 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:

$ 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

export STELLA_SUPPRESS_DEPRECATION_WARNINGS=1
stella notify channels list  # No warning

---

Getting Help

# 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