CLI Consolidation Migration Guide

Audience: operators and CI authors migrating from the standalone stella-* tools (stella-aoc, stella-symbols) to the unified stella command.

Overview

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

Note: This guide covers the standalone-binary consolidation (stella-aoc, stella-symbols → stella). For the separate v2.x → v3.0 command-tree reorganization, see the v2.x to v3.0 migration guide.

Migration Summary

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

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:

Getting Help

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

Related Documentation

• CLI command reference
• Audit pack commands
• Unknowns CLI reference
• v2.x to v3.0 migration guide