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):**
```bash
stella-aoc verify --since 2025-01-01 --postgres "Host=localhost;..."
```

**After:**
```bash
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):**
```bash
stella-symbols ingest --binary ./myapp --debug ./myapp.pdb --server https://symbols.example.com
```

**After:**
```bash
stella symbols ingest --binary ./myapp --debug ./myapp.pdb --server https://symbols.example.com
```

#### Upload Command

**Before (deprecated):**
```bash
stella-symbols upload --manifest ./manifest.json --server https://symbols.example.com
```

**After:**
```bash
stella symbols upload --manifest ./manifest.json --server https://symbols.example.com
```

#### Verify Command

**Before (deprecated):**
```bash
stella-symbols verify --path ./manifest.json
```

**After:**
```bash
stella symbols verify --path ./manifest.json
```

#### Health Command

**Before (deprecated):**
```bash
stella-symbols health --server https://symbols.example.com
```

**After:**
```bash
stella symbols health --server https://symbols.example.com
```

## CI/CD Updates

### GitHub Actions

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

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

### GitLab CI

**Before:**
```yaml
aoc-verify:
  script:
    - stella-aoc verify --since $CI_COMMIT_BEFORE_SHA --postgres "$POSTGRES_CONN"
```

**After:**
```yaml
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:

```bash
# 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:
   ```bash
   ls $(dirname $(which stella))/plugins/cli/
   ```

2. Verify manifest file:
   ```bash
   cat $(dirname $(which stella))/plugins/cli/StellaOps.Cli.Plugins.Aoc/stellaops.cli.plugins.aoc.manifest.json
   ```

3. Enable verbose logging:
   ```bash
   stella --verbose aoc verify ...
   ```

### Version Compatibility

Ensure all components are from the same release:
```bash
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](../09_API_CLI_REFERENCE.md)
- [Audit Pack Commands](./audit-pack-commands.md)
- [Unknowns CLI Reference](./unknowns-cli-reference.md)