feat: remove CLI command stuttering and enhance documentation

README.md

@@ -89,24 +89,24 @@ go install github.com/speakeasy-api/openapi/cmd/openapi@latest
 
 The CLI provides three main command groups:
 
-- **`openapi openapi`** - Commands for working with OpenAPI specifications ([documentation](./openapi/cmd/README.md))
+- **`openapi spec`** - Commands for working with OpenAPI specifications ([documentation](./openapi/cmd/README.md))
 - **`openapi arazzo`** - Commands for working with Arazzo workflow documents ([documentation](./arazzo/cmd/README.md))
 - **`openapi overlay`** - Commands for working with OpenAPI overlays ([documentation](./overlay/cmd/README.md))
 
 #### Quick Examples
 
 ```bash
 # Validate an OpenAPI specification
-openapi openapi validate ./spec.yaml
+openapi spec validate ./spec.yaml
 
 # Bundle external references into components section
-openapi openapi bundle ./spec.yaml ./bundled-spec.yaml
+openapi spec bundle ./spec.yaml ./bundled-spec.yaml
 
 # Inline all references to create a self-contained document
-openapi openapi inline ./spec.yaml ./inlined-spec.yaml
+openapi spec inline ./spec.yaml ./inlined-spec.yaml
 
 # Upgrade OpenAPI spec to latest version
-openapi openapi upgrade ./spec.yaml ./upgraded-spec.yaml
+openapi spec upgrade ./spec.yaml ./upgraded-spec.yaml
 
 # Apply an overlay to a specification
 openapi overlay apply --overlay overlay.yaml --schema spec.yaml

arazzo/cmd/README.md

@@ -4,6 +4,17 @@ Commands for working with Arazzo workflow documents.
 
 Arazzo workflows describe sequences of API calls and their dependencies. These commands help you validate and work with Arazzo documents according to the [Arazzo Specification](https://spec.openapis.org/arazzo/v1.0.0).
 
+## Table of Contents
+
+- [Table of Contents](#table-of-contents)
+- [Available Commands](#available-commands)
+  - [`validate`](#validate)
+- [What is Arazzo?](#what-is-arazzo)
+  - [Example Arazzo Document](#example-arazzo-document)
+- [Common Use Cases](#common-use-cases)
+- [Common Options](#common-options)
+- [Output Formats](#output-formats)
+
 ## Available Commands
 
 ### `validate`

cmd/openapi/main.go

@@ -97,7 +97,7 @@ without directly editing the original files. This is useful for:
 }
 
 var openapiCmds = &cobra.Command{
-	Use:   "openapi",
+	Use:   "spec",
 	Short: "Work with OpenAPI specifications",
 	Long: `Commands for working with OpenAPI specifications.
 

openapi/cmd/README.md

@@ -4,6 +4,23 @@ Commands for working with OpenAPI specifications.
 
 OpenAPI specifications define REST APIs in a standard format. These commands help you validate, transform, and work with OpenAPI documents.
 
+## Table of Contents
+
+- [Table of Contents](#table-of-contents)
+- [Available Commands](#available-commands)
+  - [`validate`](#validate)
+  - [`upgrade`](#upgrade)
+  - [`inline`](#inline)
+  - [`bundle`](#bundle)
+    - [Bundle vs Inline](#bundle-vs-inline)
+  - [`join`](#join)
+  - [`bootstrap`](#bootstrap)
+- [Common Options](#common-options)
+- [Output Formats](#output-formats)
+- [Examples](#examples)
+  - [Validation Workflow](#validation-workflow)
+  - [Processing Pipeline](#processing-pipeline)
+
 ## Available Commands
 
 ### `validate`
@@ -12,10 +29,10 @@ Validate an OpenAPI specification document for compliance with the OpenAPI Speci
 
 ```bash
 # Validate a specification file
-openapi openapi validate ./spec.yaml
+openapi spec validate ./spec.yaml
 
 # Validate with verbose output
-openapi openapi validate -v ./spec.yaml
+openapi spec validate -v ./spec.yaml
 ```
 
 This command checks for:
@@ -31,16 +48,16 @@ Upgrade an OpenAPI specification to the latest supported version (3.1.1).
 
 ```bash
 # Upgrade to stdout
-openapi openapi upgrade ./spec.yaml
+openapi spec upgrade ./spec.yaml
 
 # Upgrade to specific file
-openapi openapi upgrade ./spec.yaml ./upgraded-spec.yaml
+openapi spec upgrade ./spec.yaml ./upgraded-spec.yaml
 
 # Upgrade in-place
-openapi openapi upgrade -w ./spec.yaml
+openapi spec upgrade -w ./spec.yaml
 
 # Upgrade with specific target version
-openapi openapi upgrade --version 3.1.0 ./spec.yaml
+openapi spec upgrade --version 3.1.0 ./spec.yaml
 ```
 
 Features:
@@ -56,13 +73,13 @@ Inline all references in an OpenAPI specification to create a self-contained doc
 
 ```bash
 # Inline to stdout (pipe-friendly)
-openapi openapi inline ./spec-with-refs.yaml
+openapi spec inline ./spec-with-refs.yaml
 
 # Inline to specific file
-openapi openapi inline ./spec.yaml ./inlined-spec.yaml
+openapi spec inline ./spec.yaml ./inlined-spec.yaml
 
 # Inline in-place
-openapi openapi inline -w ./spec.yaml
+openapi spec inline -w ./spec.yaml
 ```
 
 What inlining does:
@@ -116,16 +133,16 @@ Bundle external references into the components section while preserving the refe
 
 ```bash
 # Bundle to stdout (pipe-friendly)
-openapi openapi bundle ./spec-with-refs.yaml
+openapi spec bundle ./spec-with-refs.yaml
 
 # Bundle to specific file with filepath naming (default)
-openapi openapi bundle ./spec.yaml ./bundled-spec.yaml
+openapi spec bundle ./spec.yaml ./bundled-spec.yaml
 
 # Bundle in-place with counter naming
-openapi openapi bundle -w --naming counter ./spec.yaml
+openapi spec bundle -w --naming counter ./spec.yaml
 
 # Bundle with filepath naming (explicit)
-openapi openapi bundle --naming filepath ./spec.yaml ./bundled.yaml
+openapi spec bundle --naming filepath ./spec.yaml ./bundled.yaml
 ```
 
 **Naming Strategies:**
@@ -175,7 +192,7 @@ components:
         name: {type: string}
 ```
 
-## Bundle vs Inline
+#### Bundle vs Inline
 
 **Use Bundle when:**
 
@@ -191,6 +208,58 @@ components:
 - You want the simplest possible document structure
 - You're creating documentation or examples
 
+### `join`
+
+Join multiple OpenAPI specifications into a single document.
+
+```bash
+# Join specifications to stdout
+openapi spec join ./main.yaml ./additional.yaml
+
+# Join specifications to specific file
+openapi spec join ./main.yaml ./additional.yaml ./joined-spec.yaml
+
+# Join in-place (modifies the first file)
+openapi spec join -w ./main.yaml ./additional.yaml
+
+# Join with conflict resolution strategy
+openapi spec join --strategy merge ./main.yaml ./additional.yaml
+```
+
+Features:
+
+- Combines multiple OpenAPI specifications into one
+- Handles conflicts between specifications intelligently
+- Merges paths, components, and other sections
+- Preserves all valid OpenAPI structure and references
+
+### `bootstrap`
+
+Create a new OpenAPI document with best practice examples.
+
+```bash
+# Create bootstrap document and output to stdout
+openapi spec bootstrap
+
+# Create bootstrap document and save to file
+openapi spec bootstrap ./my-api.yaml
+
+# Create bootstrap document in current directory
+openapi spec bootstrap ./openapi.yaml
+```
+
+What bootstrap creates:
+
+- Complete OpenAPI specification template with comprehensive examples
+- Proper document structure and metadata (info, servers, tags)
+- Example operations with request/response definitions
+- Reusable components (schemas, responses, security schemes)
+- Reference usage ($ref) for component reuse
+- Security scheme definitions (API key authentication)
+- Comprehensive schema examples with validation rules
+
+The generated document serves as both a template for new APIs and a learning resource for OpenAPI best practices.
+
 ## Common Options
 
 All commands support these common options:
@@ -209,22 +278,22 @@ All commands work with both YAML and JSON input files and preserve the original
 
 ```bash
 # Validate before processing
-openapi openapi validate ./spec.yaml
+openapi spec validate ./spec.yaml
 
 # Upgrade if needed
-openapi openapi upgrade ./spec.yaml ./spec-v3.1.yaml
+openapi spec upgrade ./spec.yaml ./spec-v3.1.yaml
 
 # Bundle external references
-openapi openapi bundle ./spec-v3.1.yaml ./spec-bundled.yaml
+openapi spec bundle ./spec-v3.1.yaml ./spec-bundled.yaml
 
 # Final validation
-openapi openapi validate ./spec-bundled.yaml
+openapi spec validate ./spec-bundled.yaml
 ```
 
 ### Processing Pipeline
 
 ```bash
 # Create a processing pipeline
-openapi openapi bundle ./spec.yaml | \
-openapi openapi upgrade | \
-openapi openapi validate
+openapi spec bundle ./spec.yaml | \
+openapi spec upgrade | \
+openapi spec validate

openapi/cmd/bootstrap.go

@@ -29,13 +29,13 @@ resource for OpenAPI best practices.
 
 Examples:
   # Create bootstrap document and output to stdout
-  openapi openapi bootstrap
+  openapi spec bootstrap
 
   # Create bootstrap document and save to file
-  openapi openapi bootstrap ./my-api.yaml
+  openapi spec bootstrap ./my-api.yaml
 
   # Create bootstrap document in current directory
-  openapi openapi bootstrap ./openapi.yaml`,
+  openapi spec bootstrap ./openapi.yaml`,
 	Args: cobra.MaximumNArgs(1),
 	Run:  runBootstrap,
 }

openapi/cmd/bundle.go

@@ -32,16 +32,16 @@ The bundle command supports two naming strategies:
 
 Examples:
   # Bundle to stdout (pipe-friendly)
-  openapi openapi bundle ./spec-with-refs.yaml
+  openapi spec bundle ./spec-with-refs.yaml
 
   # Bundle to specific file
-  openapi openapi bundle ./spec.yaml ./bundled-spec.yaml
+  openapi spec bundle ./spec.yaml ./bundled-spec.yaml
 
   # Bundle in-place with counter naming
-  openapi openapi bundle -w --naming counter ./spec.yaml
+  openapi spec bundle -w --naming counter ./spec.yaml
 
   # Bundle with filepath naming (default)
-  openapi openapi bundle --naming filepath ./spec.yaml ./bundled.yaml`,
+  openapi spec bundle --naming filepath ./spec.yaml ./bundled.yaml`,
 	Args: cobra.RangeArgs(1, 2),
 	RunE: runBundleCommand,
 }

openapi/cmd/join.go

@@ -39,16 +39,16 @@ Smart conflict handling:
 
 Examples:
   # Join to stdout (pipe-friendly)
-  openapi openapi join ./main.yaml ./api1.yaml ./api2.yaml
+  openapi spec join ./main.yaml ./api1.yaml ./api2.yaml
 
   # Join to specific file
-  openapi openapi join ./main.yaml ./api1.yaml ./api2.yaml ./joined.yaml
+  openapi spec join ./main.yaml ./api1.yaml ./api2.yaml ./joined.yaml
 
   # Join in-place with counter strategy
-  openapi openapi join -w --strategy counter ./main.yaml ./api1.yaml
+  openapi spec join -w --strategy counter ./main.yaml ./api1.yaml
 
   # Join with filepath strategy (default)
-  openapi openapi join --strategy filepath ./main.yaml ./api1.yaml ./joined.yaml`,
+  openapi spec join --strategy filepath ./main.yaml ./api1.yaml ./joined.yaml`,
 	Args: cobra.MinimumNArgs(2),
 	RunE: runJoinCommand,
 }

overlay/cmd/README.md

@@ -4,6 +4,24 @@ Commands for working with OpenAPI Overlays.
 
 OpenAPI Overlays provide a way to modify OpenAPI and Arazzo specifications without directly editing the original files. This is useful for adding vendor-specific extensions, modifying specifications for different environments, and applying transformations to third-party APIs.
 
+## Table of Contents
+
+- [Table of Contents](#table-of-contents)
+- [Available Commands](#available-commands)
+  - [`apply`](#apply)
+  - [`validate`](#validate)
+  - [`compare`](#compare)
+- [What are OpenAPI Overlays?](#what-are-openapi-overlays)
+  - [Example Overlay](#example-overlay)
+- [Common Use Cases](#common-use-cases)
+- [Overlay Operations](#overlay-operations)
+- [Common Options](#common-options)
+- [Output Formats](#output-formats)
+- [Examples](#examples)
+  - [Basic Workflow](#basic-workflow)
+  - [Environment-Specific Modifications](#environment-specific-modifications)
+  - [Integration with Other Commands](#integration-with-other-commands)
+
 ## Available Commands
 
 ### `apply`
@@ -130,6 +148,7 @@ All commands work with both YAML and JSON input files, but always output YAML at
 ## Examples
 
 ### Basic Workflow
+
 ```bash
 # Create an overlay by comparing two specs
 openapi overlay compare --before original.yaml --after modified.yaml --out changes.overlay.yaml
@@ -142,6 +161,7 @@ openapi overlay apply --overlay changes.overlay.yaml --schema original.yaml --ou
 ```
 
 ### Environment-Specific Modifications
+
 ```bash
 # Apply production overlay
 openapi overlay apply --overlay prod.overlay.yaml --schema base-spec.yaml --out prod-spec.yaml
@@ -151,8 +171,9 @@ openapi overlay apply --overlay dev.overlay.yaml --schema base-spec.yaml --out d
 ```
 
 ### Integration with Other Commands
+
 ```bash
 # Validate base spec, apply overlay, then validate result
-openapi openapi validate ./base-spec.yaml
+openapi spec validate ./base-spec.yaml
 openapi overlay apply --overlay ./modifications.yaml --schema ./base-spec.yaml --out ./modified-spec.yaml
-openapi openapi validate ./modified-spec.yaml
+openapi spec validate ./modified-spec.yaml