CLI Consolidation Migration Guide

Audience: operators and CI authors migrating from the standalone stella-* tools (stella-aoc, stella-symbols) to the unified stella command. The AOC tool has no successor command (section 1).

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). The separate v2.x → v3.0 command-tree reorganization completed 2026-08-25: retired command shapes were deleted outright (pre-release, no alias window), so only the canonical command tree parses.

Migration Summary

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

Migration Steps

1. AOC CLI (withdrawn)

Withdrawn (2026-10-01, SPRINT_20260928_008 PCD-153). There is no aoc command to migrate to. The CLI Aoc plug-in and its direct-PostgreSQL verify form were withdrawn on 2026-09-27 (SPRINT_20260927_003 PCD-62): they read a table no migration creates. The core aoc verify that replaced it posted to api/aoc/verify, a route no service maps, and was withdrawn on 2026-10-01. Remove stella-aoc steps from CI jobs; nothing replaces them. See the aoc command guide.

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

The stella-aoc verify CI steps have no replacement (see section 1); delete them. Symbols steps change only the binary name, as in section 2.

Shell Scripts

Update any shell scripts that invoke the old CLIs:

# Find and replace patterns
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-symbols is deprecated and will be removed on 2025-07-01.
Please migrate to: stella symbols ingest ...
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.Policy/stellaops.cli.plugins.policy.manifest.json
   

3. Enable verbose logging:

   stella --verbose symbols health ...
   

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