Migration guide from APIOps Toolkit to APIOps CLI

[petehauge]

Summary

Create documentation (and/or a guided walkthrough) that helps customers migrate from the existing APIOps Toolkit to APIOps CLI.

Problem

Customers currently using APIOps Toolkit need a clear path to adopt APIOps CLI. Without a migration guide, they face uncertainty about:

• How their existing extracted artifacts map to the new CLI's format
• How to recreate their CI/CD pipelines
• How to migrate their configuration (filters, overrides)
• What new capabilities they gain (e.g., Copilot-assisted configuration setup per Add interactive prompt for configuration file setup (filters & publishing overrides) #120)

Proposed Content

1. Conceptual Mapping

• Side-by-side comparison of Toolkit vs CLI concepts (extractor → apiops extract, publisher → apiops publish, etc.)
• Differences in artifact format and directory structure

2. Step-by-Step Migration

• How to initialize a new repo with apiops init
• How to migrate existing extracted artifacts (or re-extract from scratch)
• How to convert Toolkit configuration files to CLI configuration format
• How to update CI/CD pipelines (GitHub Actions / Azure DevOps)

3. Leveraging New Features

• Using the interactive Copilot-assisted configuration prompt (Add interactive prompt for configuration file setup (filters & publishing overrides) #120) to generate new configuration files from migrated artifacts
• New capabilities not available in Toolkit (incremental publish, etc.)

4. FAQ / Troubleshooting

• Common migration pitfalls
• Breaking changes between Toolkit and CLI

Related

• Add interactive prompt for configuration file setup (filters & publishing overrides) #120 — Interactive configuration prompt (relevant to migration step where users set up new config files)