git.stella-ops.org/docs/cli/cli-consolidation-migration.md

CLI Consolidation Migration Guide

Sprint: SPRINT_5100_0001_0001 Status: In Progress Effective Date: 2025-01-01 (deprecation begins) Sunset Date: 2025-07-01 (old CLIs removed)

Overview

StellaOps is consolidating multiple standalone CLI tools into a single unified stella command with plugin-based subcommands. This improves developer experience, simplifies distribution, and ensures consistent behavior across all CLI operations.

Migration Summary

Old CLI	New Command	Status
stella-aoc verify	stella aoc verify	Available
stella-symbols ingest	stella symbols ingest	Available
stella-symbols upload	stella symbols upload	Available
stella-symbols verify	stella symbols verify	Available
stella-symbols health	stella symbols health	Available
cryptoru	cryptoru (unchanged)	Separate

Note: cryptoru CLI remains separate due to regional compliance requirements.

Migration Steps

1. AOC CLI Migration

Before (deprecated):

stella-aoc verify --since 2025-01-01 --postgres "Host=localhost;..."

After:

stella aoc verify --since 2025-01-01 --postgres "Host=localhost;..."

Command Options (unchanged):

• --since, -s - Git commit SHA or ISO timestamp to verify from (required)
• --postgres, -p - PostgreSQL connection string (required)
• --output, -o - Path for JSON output report
• --ndjson, -n - Path for NDJSON output (one violation per line)
• --tenant, -t - Filter by tenant ID
• --dry-run - Validate configuration without querying database
• --verbose, -v - Enable verbose output

2. Symbols CLI Migration

Ingest Command

Before (deprecated):

stella-symbols ingest --binary ./myapp --debug ./myapp.pdb --server https://symbols.example.com

After:

stella symbols ingest --binary ./myapp --debug ./myapp.pdb --server https://symbols.example.com

Upload Command

Before (deprecated):

stella-symbols upload --manifest ./manifest.json --server https://symbols.example.com

After:

stella symbols upload --manifest ./manifest.json --server https://symbols.example.com

Verify Command

Before (deprecated):

stella-symbols verify --path ./manifest.json

After:

stella symbols verify --path ./manifest.json

Health Command

Before (deprecated):

stella-symbols health --server https://symbols.example.com

After:

stella symbols health --server https://symbols.example.com

CI/CD Updates

GitHub Actions

Before:

- name: Verify AOC compliance
  run: stella-aoc verify --since ${{ github.event.before }} --postgres "$POSTGRES_CONN"

After:

- name: Verify AOC compliance
  run: stella aoc verify --since ${{ github.event.before }} --postgres "$POSTGRES_CONN"

GitLab CI

Before:

aoc-verify:
  script:
    - stella-aoc verify --since $CI_COMMIT_BEFORE_SHA --postgres "$POSTGRES_CONN"

After:

aoc-verify:
  script:
    - stella aoc verify --since $CI_COMMIT_BEFORE_SHA --postgres "$POSTGRES_CONN"

Shell Scripts

Update any shell scripts that invoke the old CLIs:

# Find and replace patterns
sed -i 's/stella-aoc /stella aoc /g' scripts/*.sh
sed -i 's/stella-symbols /stella symbols /g' scripts/*.sh

Deprecation Timeline

Date	Action
2025-01-01	Deprecation warnings added to old CLIs
2025-03-01	Warning frequency increased (every invocation)
2025-05-01	Old CLIs emit error + warning, still functional
2025-07-01	Old CLIs removed from distribution

Deprecation Warnings

When using deprecated CLIs, you will see warnings like:

[DEPRECATED] stella-aoc is deprecated and will be removed on 2025-07-01.
Please migrate to: stella aoc verify ...
See: https://docs.stellaops.io/cli/migration

Plugin Architecture

The new stella CLI uses a plugin architecture. Plugins are automatically discovered from:

• <stella-install-dir>/plugins/cli/
• Custom directories via STELLAOPS_CLI_PLUGINS_DIR

Each plugin provides:

• A manifest file (*.manifest.json)
• A .NET assembly implementing ICliCommandModule

Troubleshooting

Plugin Not Found

If a subcommand is not available:

1. Check plugin directory exists:

   ls $(dirname $(which stella))/plugins/cli/
   

2. Verify manifest file:

   cat $(dirname $(which stella))/plugins/cli/StellaOps.Cli.Plugins.Aoc/stellaops.cli.plugins.aoc.manifest.json
   

3. Enable verbose logging:

   stella --verbose aoc verify ...
   

Version Compatibility

Ensure all components are from the same release:

stella --version
# StellaOps CLI v1.0.0

Environment Variables

The unified CLI respects all existing environment variables:

Variable	Description
STELLAOPS_BACKEND_URL	Backend API URL
STELLAOPS_CLI_PLUGINS_DIR	Custom plugins directory
STELLAOPS_AUTHORITY_URL	Authority service URL
STELLAOPS_LOG_LEVEL	Logging verbosity

Getting Help

• Documentation: https://docs.stellaops.io/cli
• Issues: https://github.com/stellaops/stellaops/issues
• Migration support: support@stellaops.io

Related Documentation

• CLI Reference
• Audit Pack Commands
• Unknowns CLI Reference