chore(snip): clarify help text to describe both remove and filter modes (#192)

Author: bflad

README.md

@@ -131,7 +131,7 @@ The CLI provides four main command groups:
   - `localize` - Localize an OpenAPI specification by copying external references to a target directory
   - `optimize` - Optimize an OpenAPI specification by deduplicating inline schemas
   - `sanitize` - Remove unwanted elements from an OpenAPI specification
-  - `snip` - Remove selected operations from an OpenAPI specification (interactive or CLI)
+  - `snip` - Remove or filter operations in an OpenAPI specification (interactive or CLI)
   - `upgrade` - Upgrade an OpenAPI specification to the latest supported version
   - `validate` - Validate an OpenAPI specification document
   - `query` - Query an OpenAPI specification using the [oq pipeline language](./oq/README.md) to answer structural and semantic questions about schemas and operations

cmd/openapi/commands/openapi/README.md

@@ -1078,7 +1078,7 @@ What the explorer provides:
 
 ### `snip`
 
-Remove selected operations from an OpenAPI specification and automatically clean up unused components.
+Remove or filter operations in an OpenAPI specification and automatically clean up unused components.
 
 ```bash
 # Interactive mode - browse and select operations via TUI
@@ -1100,6 +1100,12 @@ openapi spec snip --operation /users/{id}:DELETE,/admin:GET ./spec.yaml
 # CLI mode - mixed approaches
 openapi spec snip --operationId deleteUser --operation /admin:GET ./spec.yaml
 
+# CLI mode - filter to only specific operations (remove everything else)
+openapi spec snip --keepOperationId getUser --keepOperationId listUsers ./spec.yaml
+
+# CLI mode - filter by path:method
+openapi spec snip --keepOperation /users:GET,/users/{id}:GET ./spec.yaml
+
 # Write in-place (CLI mode only)
 openapi spec snip -w --operation /internal/debug:GET ./spec.yaml
 ```
@@ -1116,10 +1122,10 @@ openapi spec snip -w --operation /internal/debug:GET ./spec.yaml
 
 **Command-Line Mode** (operation flags specified):
 
-- Remove operations specified via flags without UI
-- Supports `--operationId` for operation IDs
-- Supports `--operation` for path:method pairs
-- Both flags support comma-separated values or multiple flags
+- **Remove mode** (`--operationId`, `--operation`): remove the specified operations
+- **Filter mode** (`--keepOperationId`, `--keepOperation`): filter the spec down to only the specified operations, removing everything else
+- Remove and filter flags cannot be combined
+- All flags support comma-separated values or multiple flags
 
 **What snip does:**
 

cmd/openapi/commands/openapi/snip.go

@@ -24,8 +24,8 @@ var (
 
 var snipCmd = &cobra.Command{
 	Use:   "snip <input-file> [output-file]",
-	Short: "Remove operations from an OpenAPI specification",
-	Long: `Remove selected operations from an OpenAPI specification and clean up unused components.
+	Short: "Remove or filter operations in an OpenAPI specification",
+	Long: `Remove or filter operations in an OpenAPI specification and clean up unused components.
 
 Stdin is supported in CLI mode — either pipe data directly or use '-' explicitly:
   cat spec.yaml | openapi spec snip --operationId deleteUser
@@ -37,12 +37,16 @@ This command can operate in two modes:
    Launch a terminal UI to browse and select operations for removal.
    - Navigate with j/k or arrow keys
    - Press Space to select/deselect operations
-   - Press 'a' to select all, 'A' to deselect all  
+   - Press 'a' to select all, 'A' to deselect all
    - Press 'w' to write the result
    - Press 'q' or Esc to cancel
 
-2. Command-Line Mode (--operationId or --operation flags):
-   Remove operations specified via flags without launching the UI.
+2. Command-Line Mode (flags specified):
+   Remove or filter operations specified via flags without launching the UI.
+   - Remove mode (--operationId, --operation): remove the specified operations.
+   - Filter mode (--keepOperationId, --keepOperation): filter the spec down to
+     only the specified operations, removing everything else.
+   Remove and filter flags cannot be combined.
 
 Output options:
 - No output file: writes to stdout (pipe-friendly)
@@ -71,6 +75,12 @@ Examples:
   # CLI mode - mixed operation IDs and path:method
   openapi spec snip --operationId deleteUser --operation /admin:GET ./spec.yaml
 
+  # CLI mode - filter to only specific operations (remove everything else)
+  openapi spec snip --keepOperationId getUser --keepOperationId listUsers ./spec.yaml
+
+  # CLI mode - filter by path:method
+  openapi spec snip --keepOperation /users:GET,/users/{id}:GET ./spec.yaml
+
   # CLI mode - write to stdout for piping
   openapi spec snip --operation /internal/debug:GET ./spec.yaml > ./public-spec.yaml`,
 	Args: stdinOrFileArgs(1, 2),