Change CLI from hyphenated commands to subcommands

[frankbria]

Summary

Change the CLI interface from hyphenated commands to modern subcommand structure for better UX and consistency with common CLI patterns.

Current Commands (Hyphenated)

parallel-cc mcp-serve
parallel-cc watch-merges
parallel-cc merge-status
parallel-cc sandbox-run
parallel-cc sandbox-logs
parallel-cc sandbox-download
parallel-cc sandbox-kill

Proposed Commands (Subcommands)

parallel-cc mcp serve
parallel-cc watch merges
parallel-cc merge status
parallel-cc sandbox run
parallel-cc sandbox logs
parallel-cc sandbox download
parallel-cc sandbox kill

Benefits

• Modern CLI patterns: Follows conventions used by popular tools (git, kubectl, gh, docker)
• Better organization: Logical grouping of related commands (all sandbox operations under sandbox namespace)
• Improved discoverability: Users can run parallel-cc sandbox to see available sandbox operations
• Cleaner help output: Subcommands can have their own help sections

Implementation Considerations

• Maintain backward compatibility by supporting both formats during transition period
• Add deprecation warnings for hyphenated versions
• Update all documentation (README, docs/, examples)
• Update bash/zsh completion scripts

Breaking Change

This is a breaking change that should be part of a major version bump (v2.0.0).

Co-Authored-By: Warp agent@warp.dev

[traycerai]

Plan

Observations

The codebase uses Commander.js for CLI management with all commands currently defined as hyphenated commands (mcp-serve, watch-merges, merge-status, sandbox-run, sandbox-logs, sandbox-download, sandbox-kill, sandbox-list, sandbox-status). The templates command already follows the modern subcommand pattern, serving as a reference implementation. The CLI is defined in file:src/cli.ts (2979 lines), with extensive documentation in file:README.md and various docs files. No bash/zsh completion scripts exist yet.

Approach

Transform hyphenated commands to subcommand structure using Commander.js's nested command pattern (already demonstrated by the templates command). Implement backward compatibility by registering both old and new command formats, with deprecation warnings for hyphenated versions. This approach minimizes breaking changes during transition while guiding users toward modern CLI patterns. Update all documentation to reflect new command structure and mark this as a breaking change for v2.0.0.

Implementation Steps

1. Refactor CLI Command Structure in file:src/cli.ts

MCP Command Group (lines 815-830)

• Create mcpCmd using program.command('mcp').description('MCP server operations')
• Move mcp-serve logic to mcpCmd.command('serve')
• Keep existing program.command('mcp-serve') with deprecation warning
• Add .addHelpText('after', '\nDeprecated: Use "parallel-cc mcp serve" instead')

Watch Command Group (lines 835-927)

• Create watchCmd using program.command('watch').description('Watch and monitor operations')
• Move watch-merges logic to watchCmd.command('merges')
• Move merge-status logic to watchCmd.command('status') or create separate mergeCmd
• Alternative: Create mergeCmd for merge status to match the proposed structure
• Keep deprecated hyphenated versions with warnings

Sandbox Command Group (lines 1355-2555)

• Create sandboxCmd using program.command('sandbox').description('E2B sandbox operations (v1.0)')
• Migrate all sandbox commands as subcommands:
  • sandboxCmd.command('run') from sandbox-run (line 1355)
  • sandboxCmd.command('logs') from sandbox-logs (line 2157)
  • sandboxCmd.command('download') from sandbox-download (line 2235)
  • sandboxCmd.command('kill') from sandbox-kill (line 2341)
  • sandboxCmd.command('list') from sandbox-list (line 2418)
  • sandboxCmd.command('status') from sandbox-status (line 2473)
• Preserve all options and action handlers
• Keep deprecated versions with warnings

Deprecation Warning Helper

function showDeprecationWarning(oldCmd: string, newCmd: string) {
  console.log(chalk.yellow(`⚠ Warning: "${oldCmd}" is deprecated`));
  console.log(chalk.dim(`  Use "${newCmd}" instead`));
  console.log(chalk.dim(`  The old command will be removed in v2.0.0\n`));
}

2. Update Documentation

README.md (file:README.md)

• Update CLI Commands section (lines 207-289)
• Change all command examples from hyphenated to subcommand format:
  • parallel-cc mcp-serve → parallel-cc mcp serve
  • parallel-cc watch-merges → parallel-cc watch merges
  • parallel-cc merge-status → parallel-cc merge status
  • parallel-cc sandbox-run → parallel-cc sandbox run
  • parallel-cc sandbox-logs → parallel-cc sandbox logs
  • parallel-cc sandbox-download → parallel-cc sandbox download
  • parallel-cc sandbox-kill → parallel-cc sandbox kill
• Add migration note in "What's New" section mentioning v2.0.0 breaking change
• Add backward compatibility note explaining deprecated commands still work

Other Documentation Files

• file:docs/E2B_GUIDE.md - Update all sandbox command examples
• file:ROADMAP.md - Add v2.0.0 CLI modernization entry
• file:CLAUDE.md - Update command references if present
• file:SANDBOX_INTEGRATION_PLAN.md - Update sandbox command examples
• Search and update all files in file:docs/ directory

3. Update Package Version

package.json (file:package.json)

• Bump version from 1.0.0 to 2.0.0 (line 3)
• Add note in description about modern CLI structure

4. Add Migration Guide

Create file:docs/MIGRATION_v1_to_v2.md:

• Document all command changes with side-by-side comparison table
• Explain backward compatibility period
• Provide migration timeline (deprecation warnings in v2.0.0, removal in v3.0.0)
• Include shell alias suggestions for users preferring old commands
• Add script examples for bulk updating in documentation/scripts

5. Update Help Text and Discoverability

Enhanced Help Output

• Add help text to parent commands showing available subcommands
• Example: parallel-cc sandbox --help shows all sandbox operations
• Add usage examples in command descriptions
• Ensure parallel-cc --help clearly shows command groups

Command Aliases (Optional Enhancement)

• Consider adding short aliases: parallel-cc sb run for parallel-cc sandbox run
• Document aliases in help text if implemented

6. Testing Considerations

Manual Testing Checklist

• Verify all new subcommands work with existing options
• Test deprecated commands show warnings but still function
• Validate help text displays correctly for all command levels
• Test JSON output modes remain unchanged
• Verify error messages reference new command format

Integration Testing

• Test command execution in both formats
• Verify backward compatibility with existing scripts
• Test help command at all levels (--help on parent and subcommands)

7. Update Installation Scripts

Scripts to Review

• file:scripts/install.sh - Update any command references
• file:scripts/uninstall.sh - Update any command references
• Check for any wrapper scripts that hardcode command names

Command Mapping Reference

Old Command (Deprecated)	New Command	Group
parallel-cc mcp-serve	parallel-cc mcp serve	MCP
parallel-cc watch-merges	parallel-cc watch merges	Watch
parallel-cc merge-status	parallel-cc merge status	Merge
parallel-cc sandbox-run	parallel-cc sandbox run	Sandbox
parallel-cc sandbox-logs	parallel-cc sandbox logs	Sandbox
parallel-cc sandbox-download	parallel-cc sandbox download	Sandbox
parallel-cc sandbox-kill	parallel-cc sandbox kill	Sandbox
parallel-cc sandbox-list	parallel-cc sandbox list	Sandbox
parallel-cc sandbox-status	parallel-cc sandbox status	Sandbox

Architecture Diagram

graph TD
    A[parallel-cc CLI] --> B[Core Commands]
    A --> C[mcp]
    A --> D[watch]
    A --> E[merge]
    A --> F[sandbox]
    A --> G[templates]
    
    B --> B1[register]
    B --> B2[release]
    B --> B3[status]
    B --> B4[cleanup]
    B --> B5[doctor]
    B --> B6[install]
    B --> B7[migrate]
    
    C --> C1[serve]
    
    D --> D1[merges]
    
    E --> E1[status]
    
    F --> F1[run]
    F --> F2[logs]
    F --> F3[download]
    F --> F4[kill]
    F --> F5[list]
    F --> F6[status]
    
    G --> G1[list]
    G --> G2[show]
    G --> G3[create]
    G --> G4[delete]
    G --> G5[export]
    G --> G6[import]
    
    style C fill:#e1f5ff
    style D fill:#e1f5ff
    style E fill:#e1f5ff
    style F fill:#e1f5ff
    style G fill:#90EE90
    
    classDef deprecated fill:#ffcccc,stroke:#ff0000,stroke-dasharray: 5 5

Loading

Breaking Change Notice

This is a breaking change requiring a major version bump to v2.0.0. The deprecation period allows users to migrate gradually:

• v2.0.0: New subcommands introduced, old commands deprecated with warnings
• v2.1.0+: Deprecation warnings continue
• v3.0.0: Old hyphenated commands removed entirely

Users should update scripts, documentation, and workflows to use new command format during the deprecation period.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase uses Commander.js for CLI management with all commands currently defined as hyphenated commands (`mcp-serve`, `watch-merges`, `merge-status`, `sandbox-run`, `sandbox-logs`, `sandbox-download`, `sandbox-kill`, `sandbox-list`, `sandbox-status`). The `templates` command already follows the modern subcommand pattern, serving as a reference implementation. The CLI is defined in `file:src/cli.ts` (2979 lines), with extensive documentation in `file:README.md` and various docs files. No bash/zsh completion scripts exist yet.

## Approach

Transform hyphenated commands to subcommand structure using Commander.js's nested command pattern (already demonstrated by the `templates` command). Implement backward compatibility by registering both old and new command formats, with deprecation warnings for hyphenated versions. This approach minimizes breaking changes during transition while guiding users toward modern CLI patterns. Update all documentation to reflect new command structure and mark this as a breaking change for v2.0.0.

## Implementation Steps

### 1. Refactor CLI Command Structure in `file:src/cli.ts`

**MCP Command Group** (lines 815-830)
- Create `mcpCmd` using `program.command('mcp').description('MCP server operations')`
- Move `mcp-serve` logic to `mcpCmd.command('serve')`
- Keep existing `program.command('mcp-serve')` with deprecation warning
- Add `.addHelpText('after', '\nDeprecated: Use "parallel-cc mcp serve" instead')`

**Watch Command Group** (lines 835-927)
- Create `watchCmd` using `program.command('watch').description('Watch and monitor operations')`
- Move `watch-merges` logic to `watchCmd.command('merges')`
- Move `merge-status` logic to `watchCmd.command('status')` or create separate `mergeCmd`
- Alternative: Create `mergeCmd` for `merge status` to match the proposed structure
- Keep deprecated hyphenated versions with warnings

**Sandbox Command Group** (lines 1355-2555)
- Create `sandboxCmd` using `program.command('sandbox').description('E2B sandbox operations (v1.0)')`
- Migrate all sandbox commands as subcommands:
  - `sandboxCmd.command('run')` from `sandbox-run` (line 1355)
  - `sandboxCmd.command('logs')` from `sandbox-logs` (line 2157)
  - `sandboxCmd.command('download')` from `sandbox-download` (line 2235)
  - `sandboxCmd.command('kill')` from `sandbox-kill` (line 2341)
  - `sandboxCmd.command('list')` from `sandbox-list` (line 2418)
  - `sandboxCmd.command('status')` from `sandbox-status` (line 2473)
- Preserve all options and action handlers
- Keep deprecated versions with warnings

**Deprecation Warning Helper**
```typescript
function showDeprecationWarning(oldCmd: string, newCmd: string) {
  console.log(chalk.yellow(`⚠ Warning: "${oldCmd}" is deprecated`));
  console.log(chalk.dim(`  Use "${newCmd}" instead`));
  console.log(chalk.dim(`  The old command will be removed in v2.0.0\n`));
}
```

### 2. Update Documentation

**README.md** (file:README.md)
- Update CLI Commands section (lines 207-289)
- Change all command examples from hyphenated to subcommand format:
  - `parallel-cc mcp-serve` → `parallel-cc mcp serve`
  - `parallel-cc watch-merges` → `parallel-cc watch merges`
  - `parallel-cc merge-status` → `parallel-cc merge status`
  - `parallel-cc sandbox-run` → `parallel-cc sandbox run`
  - `parallel-cc sandbox-logs` → `parallel-cc sandbox logs`
  - `parallel-cc sandbox-download` → `parallel-cc sandbox download`
  - `parallel-cc sandbox-kill` → `parallel-cc sandbox kill`
- Add migration note in "What's New" section mentioning v2.0.0 breaking change
- Add backward compatibility note explaining deprecated commands still work

**Other Documentation Files**
- `file:docs/E2B_GUIDE.md` - Update all sandbox command examples
- `file:ROADMAP.md` - Add v2.0.0 CLI modernization entry
- `file:CLAUDE.md` - Update command references if present
- `file:SANDBOX_INTEGRATION_PLAN.md` - Update sandbox command examples
- Search and update all files in `file:docs/` directory

### 3. Update Package Version

**package.json** (file:package.json)
- Bump version from `1.0.0` to `2.0.0` (line 3)
- Add note in description about modern CLI structure

### 4. Add Migration Guide

Create `file:docs/MIGRATION_v1_to_v2.md`:
- Document all command changes with side-by-side comparison table
- Explain backward compatibility period
- Provide migration timeline (deprecation warnings in v2.0.0, removal in v3.0.0)
- Include shell alias suggestions for users preferring old commands
- Add script examples for bulk updating in documentation/scripts

### 5. Update Help Text and Discoverability

**Enhanced Help Output**
- Add help text to parent commands showing available subcommands
- Example: `parallel-cc sandbox --help` shows all sandbox operations
- Add usage examples in command descriptions
- Ensure `parallel-cc --help` clearly shows command groups

**Command Aliases** (Optional Enhancement)
- Consider adding short aliases: `parallel-cc sb run` for `parallel-cc sandbox run`
- Document aliases in help text if implemented

### 6. Testing Considerations

**Manual Testing Checklist**
- Verify all new subcommands work with existing options
- Test deprecated commands show warnings but still function
- Validate help text displays correctly for all command levels
- Test JSON output modes remain unchanged
- Verify error messages reference new command format

**Integration Testing**
- Test command execution in both formats
- Verify backward compatibility with existing scripts
- Test help command at all levels (`--help` on parent and subcommands)

### 7. Update Installation Scripts

**Scripts to Review**
- `file:scripts/install.sh` - Update any command references
- `file:scripts/uninstall.sh` - Update any command references
- Check for any wrapper scripts that hardcode command names

## Command Mapping Reference

| Old Command (Deprecated) | New Command | Group |
|-------------------------|-------------|-------|
| `parallel-cc mcp-serve` | `parallel-cc mcp serve` | MCP |
| `parallel-cc watch-merges` | `parallel-cc watch merges` | Watch |
| `parallel-cc merge-status` | `parallel-cc merge status` | Merge |
| `parallel-cc sandbox-run` | `parallel-cc sandbox run` | Sandbox |
| `parallel-cc sandbox-logs` | `parallel-cc sandbox logs` | Sandbox |
| `parallel-cc sandbox-download` | `parallel-cc sandbox download` | Sandbox |
| `parallel-cc sandbox-kill` | `parallel-cc sandbox kill` | Sandbox |
| `parallel-cc sandbox-list` | `parallel-cc sandbox list` | Sandbox |
| `parallel-cc sandbox-status` | `parallel-cc sandbox status` | Sandbox |

## Architecture Diagram

```mermaid
graph TD
    A[parallel-cc CLI] --> B[Core Commands]
    A --> C[mcp]
    A --> D[watch]
    A --> E[merge]
    A --> F[sandbox]
    A --> G[templates]
    
    B --> B1[register]
    B --> B2[release]
    B --> B3[status]
    B --> B4[cleanup]
    B --> B5[doctor]
    B --> B6[install]
    B --> B7[migrate]
    
    C --> C1[serve]
    
    D --> D1[merges]
    
    E --> E1[status]
    
    F --> F1[run]
    F --> F2[logs]
    F --> F3[download]
    F --> F4[kill]
    F --> F5[list]
    F --> F6[status]
    
    G --> G1[list]
    G --> G2[show]
    G --> G3[create]
    G --> G4[delete]
    G --> G5[export]
    G --> G6[import]
    
    style C fill:#e1f5ff
    style D fill:#e1f5ff
    style E fill:#e1f5ff
    style F fill:#e1f5ff
    style G fill:#90EE90
    
    classDef deprecated fill:#ffcccc,stroke:#ff0000,stroke-dasharray: 5 5
```

## Breaking Change Notice

This is a **breaking change** requiring a major version bump to **v2.0.0**. The deprecation period allows users to migrate gradually:

- **v2.0.0**: New subcommands introduced, old commands deprecated with warnings
- **v2.1.0+**: Deprecation warnings continue
- **v3.0.0**: Old hyphenated commands removed entirely

Users should update scripts, documentation, and workflows to use new command format during the deprecation period.

---

Execution Information

Branch: main
Commit: a25f317

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#1 - Add native sandboxing integration option [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!